provisioning/docs/src/development/taskservs/taskserv-quick-guide.md

Taskserv Quick Guide

🚀 Quick Start

Create a New Taskserv (Interactive)

nu provisioning/tools/create-taskserv-helper.nu interactive

Create a New Taskserv (Direct)

nu provisioning/tools/create-taskserv-helper.nu create my-api 
  --category development 
  --port 8080 
  --description "My REST API service"

📋 5-Minute Setup

1. Choose Your Method

• Interactive: nu provisioning/tools/create-taskserv-helper.nu interactive
• Command Line: Use the direct command above
• Manual: Follow the structure guide below

2. Basic Structure

my-service/
├── nickel/
│   ├── manifest.toml   # Package definition
│   ├── my-service.ncl  # Main schema
│   └── version.ncl     # Version info
├── default/
│   ├── defs.toml       # Default config
│   └── install-*.sh    # Install script
└── README.md           # Documentation

3. Essential Files

manifest.toml (package definition):

[package]
name = "my-service"
version = "1.0.0"
description = "My service"

[dependencies]
k8s = { oci = "oci://ghcr.io/kcl-lang/k8s", tag = "1.30" }

my-service.ncl (main schema):

let MyService = {
    name | String,
    version | String,
    port | Number,
    replicas | Number,
} in

{
    my_service_config = {
        name = "my-service",
        version = "latest",
        port = 8080,
        replicas = 1,
    }
}

4. Test Your Taskserv

# Discover your taskserv
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; get-taskserv-info my-service"

# Test layer resolution
nu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"

# Deploy with check
provisioning/core/cli/provisioning taskserv create my-service --infra wuji --check

🎯 Common Patterns

Web Service

let WebService = {
    name | String,
    version | String | default = "latest",
    port | Number | default = 8080,
    replicas | Number | default = 1,
    ingress | {
        enabled | Bool | default = true,
        hostname | String,
        tls | Bool | default = false,
    },
    resources | {
        cpu | String | default = "100m",
        memory | String | default = "128Mi",
    },
} in
WebService

Database Service

let DatabaseService = {
    name | String,
    version | String | default = "latest",
    port | Number | default = 5432,
    persistence | {
        enabled | Bool | default = true,
        size | String | default = "10Gi",
        storage_class | String | default = "ssd",
    },
    auth | {
        database | String | default = "app",
        username | String | default = "user",
        password_secret | String,
    },
} in
DatabaseService

Background Worker

let BackgroundWorker = {
    name | String,
    version | String | default = "latest",
    replicas | Number | default = 1,
    job | {
        schedule | String | optional,  # Cron format for scheduled jobs
        parallelism | Number | default = 1,
        completions | Number | default = 1,
    },
    resources | {
        cpu | String | default = "500m",
        memory | String | default = "512Mi",
    },
} in
BackgroundWorker

🛠️ CLI Shortcuts

Discovery

# List all taskservs
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | select name group"

# Search taskservs
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; search-taskservs redis"

# Show stats
nu -c "use provisioning/workspace/tools/layer-utils.nu *; show_layer_stats"

Development

# Check Nickel syntax
nickel typecheck provisioning/extensions/taskservs/{category}/{name}/schemas/{name}.ncl

# Generate configuration
provisioning/core/cli/provisioning taskserv generate {name} --infra {infra}

# Version management
provisioning/core/cli/provisioning taskserv versions {name}
provisioning/core/cli/provisioning taskserv check-updates

Testing

# Dry run deployment
provisioning/core/cli/provisioning taskserv create {name} --infra {infra} --check

# Layer resolution debug
nu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution {name} {infra} {provider}"

📚 Categories Reference

Category	Examples	Use Case
container-runtime	containerd, crio, podman	Container runtime engines
databases	postgres, redis	Database services
development	coder, gitea, desktop	Development tools
infrastructure	kms, webhook, os	System infrastructure
kubernetes	kubernetes	Kubernetes orchestration
networking	cilium, coredns, etcd	Network services
storage	rook-ceph, external-nfs	Storage solutions

🔧 Troubleshooting

Taskserv Not Found

# Check if discovered
nu -c "use provisioning/core/nulib/taskservs/discover.nu *; discover-taskservs | where name == my-service"

# Verify kcl.mod exists
ls provisioning/extensions/taskservs/{category}/my-service/kcl/kcl.mod

Layer Resolution Issues

# Debug resolution
nu -c "use provisioning/workspace/tools/layer-utils.nu *; test_layer_resolution my-service wuji upcloud"

# Check template exists
ls provisioning/workspace/templates/taskservs/{category}/my-service.ncl

Nickel Syntax Errors

# Check syntax
nickel typecheck provisioning/extensions/taskservs/{category}/my-service/schemas/my-service.ncl

# Format code
nickel format provisioning/extensions/taskservs/{category}/my-service/schemas/

💡 Pro Tips

1. Use existing taskservs as templates - Copy and modify similar services
2. Test with --check first - Always use dry run before actual deployment
3. Follow naming conventions - Use kebab-case for consistency
4. Document thoroughly - Good docs save time later
5. Version your schemas - Include version.ncl for compatibility tracking

🔗 Next Steps

1. Read the full Taskserv Developer Guide
2. Explore existing taskservs in provisioning/extensions/taskservs/
3. Check out templates in provisioning/workspace/templates/taskservs/
4. Join the development community for support