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/
├── kcl/
│   ├── kcl.mod         # Package definition
│   ├── my-service.k    # Main schema
│   └── version.k       # Version info
├── default/
│   ├── defs.toml       # Default config
│   └── install-*.sh    # Install script
└── README.md           # Documentation

3. Essential Files

kcl.mod (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.k (main schema):

schema MyService {
    name: str = "my-service"
    version: str = "latest"
    port: int = 8080
    replicas: int = 1
}

my_service_config: MyService = MyService {}

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

schema WebService {
    name: str
    version: str = "latest"
    port: int = 8080
    replicas: int = 1

    ingress: {
        enabled: bool = true
        hostname: str
        tls: bool = false
    }

    resources: {
        cpu: str = "100m"
        memory: str = "128Mi"
    }
}

Database Service

schema DatabaseService {
    name: str
    version: str = "latest"
    port: int = 5432

    persistence: {
        enabled: bool = true
        size: str = "10Gi"
        storage_class: str = "ssd"
    }

    auth: {
        database: str = "app"
        username: str = "user"
        password_secret: str
    }
}

Background Worker

schema BackgroundWorker {
    name: str
    version: str = "latest"
    replicas: int = 1

    job: {
        schedule?: str  # Cron format for scheduled jobs
        parallelism: int = 1
        completions: int = 1
    }

    resources: {
        cpu: str = "500m"
        memory: str = "512Mi"
    }
}

🛠️ 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 KCL syntax
kcl check provisioning/extensions/taskservs/{category}/{name}/kcl/{name}.k

# 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

🔧 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.k

KCL Syntax Errors

# Check syntax
kcl check provisioning/extensions/taskservs/{category}/my-service/kcl/my-service.k

# Format code
kcl fmt provisioning/extensions/taskservs/{category}/my-service/kcl/

💡 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.k 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