6.3 KiB
6.3 KiB
\nnu provisioning/tools/create-taskserv-helper.nu interactive\n\n\n### Create a New Taskserv (Direct)\n\n\nnu provisioning/tools/create-taskserv-helper.nu create my-api \\n --category development \\n --port 8080 \\n --description "My REST API service"\n\n\n## 📋 5-Minute Setup\n\n### 1. Choose Your Method\n\n- Interactive: nu provisioning/tools/create-taskserv-helper.nu interactive\n- Command Line: Use the direct command above\n- Manual: Follow the structure guide below\n\n### 2. Basic Structure\n\n\nmy-service/\n├── nickel/\n│ ├── manifest.toml # Package definition\n│ ├── my-service.ncl # Main schema\n│ └── version.ncl # Version info\n├── default/\n│ ├── defs.toml # Default config\n│ └── install-*.sh # Install script\n└── README.md # Documentation\n\n\n### 3. Essential Files\n\nmanifest.toml (package definition):\n\n\n[package]\nname = "my-service"\nversion = "1.0.0"\ndescription = "My service"\n\n[dependencies]\nk8s = { oci = "oci://ghcr.io/kcl-lang/k8s", tag = "1.30" }\n\n\nmy-service.ncl (main schema):\n\n\nlet MyService = {\n name | String,\n version | String,\n port | Number,\n replicas | Number,\n} in\n\n{\n my_service_config = {\n name = "my-service",\n version = "latest",\n port = 8080,\n replicas = 1,\n }\n}\n\n\n### 4. Test Your Taskserv\n\n\n# Discover your taskserv\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; get-taskserv-info my-service"\n\n# Test layer resolution\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"\n\n# Deploy with check\nprovisioning/core/cli/provisioning taskserv create my-service --infra wuji --check\n\n\n## 🎯 Common Patterns\n\n### Web Service\n\n\nlet WebService = {\n name | String,\n version | String | default = "latest",\n port | Number | default = 8080,\n replicas | Number | default = 1,\n ingress | {\n enabled | Bool | default = true,\n hostname | String,\n tls | Bool | default = false,\n },\n resources | {\n cpu | String | default = "100m",\n memory | String | default = "128Mi",\n },\n} in\nWebService\n\n\n### Database Service\n\n\nlet DatabaseService = {\n name | String,\n version | String | default = "latest",\n port | Number | default = 5432,\n persistence | {\n enabled | Bool | default = true,\n size | String | default = "10Gi",\n storage_class | String | default = "ssd",\n },\n auth | {\n database | String | default = "app",\n username | String | default = "user",\n password_secret | String,\n },\n} in\nDatabaseService\n\n\n### Background Worker\n\n\nlet BackgroundWorker = {\n name | String,\n version | String | default = "latest",\n replicas | Number | default = 1,\n job | {\n schedule | String | optional, # Cron format for scheduled jobs\n parallelism | Number | default = 1,\n completions | Number | default = 1,\n },\n resources | {\n cpu | String | default = "500m",\n memory | String | default = "512Mi",\n },\n} in\nBackgroundWorker\n\n\n## 🛠️ CLI Shortcuts\n\n### Discovery\n\n\n# List all taskservs\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | select name group"\n\n# Search taskservs\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; search-taskservs redis"\n\n# Show stats\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; show_layer_stats"\n\n\n### Development\n\n\n# Check Nickel syntax\nnickel typecheck provisioning/extensions/taskservs/{category}/{name}/schemas/{name}.ncl\n\n# Generate configuration\nprovisioning/core/cli/provisioning taskserv generate {name} --infra {infra}\n\n# Version management\nprovisioning/core/cli/provisioning taskserv versions {name}\nprovisioning/core/cli/provisioning taskserv check-updates\n\n\n### Testing\n\n\n# Dry run deployment\nprovisioning/core/cli/provisioning taskserv create {name} --infra {infra} --check\n\n# Layer resolution debug\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution {name} {infra} {provider}"\n\n\n## 📚 Categories Reference\n\n| Category | Examples | Use Case |\n| ---------- | ---------- | ---------- |\n| container-runtime | containerd, crio, podman | Container runtime engines |\n| databases | postgres, redis | Database services |\n| development | coder, gitea, desktop | Development tools |\n| infrastructure | kms, webhook, os | System infrastructure |\n| kubernetes | kubernetes | Kubernetes orchestration |\n| networking | cilium, coredns, etcd | Network services |\n| storage | rook-ceph, external-nfs | Storage solutions |\n\n## 🔧 Troubleshooting\n\n### Taskserv Not Found\n\n\n# Check if discovered\nnu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | where name == my-service"\n\n# Verify kcl.mod exists\nls provisioning/extensions/taskservs/{category}/my-service/kcl/kcl.mod\n\n\n### Layer Resolution Issues\n\n\n# Debug resolution\nnu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"\n\n# Check template exists\nls provisioning/workspace/templates/taskservs/{category}/my-service.ncl\n\n\n### Nickel Syntax Errors\n\n\n# Check syntax\nnickel typecheck provisioning/extensions/taskservs/{category}/my-service/schemas/my-service.ncl\n\n# Format code\nnickel format provisioning/extensions/taskservs/{category}/my-service/schemas/\n\n\n## 💡 Pro Tips\n\n1. Use existing taskservs as templates - Copy and modify similar services\n2. Test with --check first - Always use dry run before actual deployment\n3. Follow naming conventions - Use kebab-case for consistency\n4. Document thoroughly - Good docs save time later\n5. Version your schemas - Include version.ncl for compatibility tracking\n\n## 🔗 Next Steps\n\n1. Read the full Taskserv Developer Guide\n2. Explore existing taskservs in provisioning/extensions/taskservs/\n3. Check out templates in provisioning/workspace/templates/taskservs/\n4. Join the development community for support