prvng_extensions/taskservs/README.md

# Task Services

This directory contains task service definitions for infrastructure components that can be installed and managed on provisioned servers. Task services are modular, reusable components that handle specific infrastructure capabilities.

## Task Service Categories

### Container Runtimes
- **containerd**: Industry-standard container runtime with CRI support
- **crio**: Lightweight container runtime for Kubernetes
- **podman**: Daemonless container engine with Docker compatibility
- **crun**: Fast and lightweight OCI runtime written in C
- **youki**: Container runtime written in Rust

### Container Engines
- **runc**: Reference implementation of the OCI runtime specification
- **crun**: Fast and low-memory footprint OCI runtime

### Orchestration and Kubernetes
- **kubernetes**: Complete Kubernetes cluster with comprehensive configuration
- **cilium**: eBPF-based networking and security for Kubernetes
- **coredns**: DNS server and service discovery for Kubernetes
- **etcd**: Distributed key-value store for Kubernetes cluster data
- **rook-ceph**: Cloud-native storage orchestrator for Kubernetes

### Development and CI/CD
- **coder**: Cloud development environments and workspaces
- **desktop**: Remote desktop and development environment access
- **gitea**: Self-hosted Git service with web interface
- **polkadot-validator**: Polkadot blockchain validator node
- **webhook**: Git webhook server for automation

### Databases and Storage
- **postgres**: PostgreSQL database server
- **redis**: In-memory data structure store and cache
- **external-nfs**: Network File System external storage
- **mayastor**: High-performance software-defined storage

### Networking and Infrastructure
- **ip-aliases**: Network IP alias management
- **proxy**: HTTP/HTTPS proxy server configuration
- **resolv**: DNS resolution configuration
- **kms**: Key Management Service for encryption

### Security and Monitoring
- **oras**: OCI Registry As Storage for artifact management
- **radicle**: Decentralized code collaboration platform

## Task Service Architecture

### Schema Structure
Each task service typically includes:

1. **Main Schema** (`{taskserv}.k`): Primary configuration definition
2. **Version Management** (`version.k`): Version tracking with GitHub integration
3. **Dependencies** (`dependencies.k`): Resource requirements and health checks

### Common Patterns

#### Basic Task Service
```kcl
schema TaskServiceName:
    name: str = "taskserv-name"
    version: str
    enabled: bool = True
    # Service-specific configuration
    check:
        len(name) > 0, "Service name cannot be empty"
```

#### Advanced Task Service (e.g., Kubernetes)
```kcl
schema Kubernetes:
    name: str = "kubernetes"
    version: str
    # Network configuration
    pod_cidr: str = "10.244.0.0/16"
    service_cidr: str = "10.96.0.0/12"
    # Runtime configuration
    container_runtime: str = "containerd"
    cri_socket: str = "/run/containerd/containerd.sock"
    # Storage and etcd
    etcd_data_dir: str = "/var/lib/etcd"
    # Validation rules
    check:
        regex.match(pod_cidr, r"^([0-9]{1,3}\.){3}[0-9]{1,3}\/[0-9]{1,2}$")
        regex.match(service_cidr, r"^([0-9]{1,3}\.){3}[0-9]{1,3}\/[0-9]{1,2}$")
```

## Usage

### Installing Task Services

```bash
# Install single task service
provisioning/core/cli/provisioning taskserv create kubernetes --infra <infra-name>

# Using workflow system
nu -c "use core/nulib/workflows/taskserv.nu *; taskserv create 'kubernetes' '<infra-name>' --check"
```

### Managing Task Services

```bash
# List available task services
provisioning/core/cli/provisioning taskserv list

# Check for updates
provisioning/core/cli/provisioning taskserv check-updates

# Generate configuration
provisioning/core/cli/provisioning taskserv generate kubernetes

# Remove task service
nu -c "use core/nulib/workflows/taskserv.nu *; taskserv delete 'kubernetes' '<infra-name>' --check"
```

### Version Management

```bash
# Check specific taskserv versions
provisioning/core/cli/provisioning taskserv versions kubernetes

# Update specific taskserv
provisioning/core/cli/provisioning taskserv check-updates kubernetes
```

## Configuration Examples

### Kubernetes Task Service
```kcl
kubernetes_config: Kubernetes = {
    name = "kubernetes"
    version = "1.28.0"
    pod_cidr = "10.244.0.0/16"
    service_cidr = "10.96.0.0/12"
    container_runtime = "containerd"
    enable_metrics_server = True
    enable_dashboard = False
}
```

### Redis Task Service
```kcl
redis_config: Redis = {
    name = "redis"
    version = "7.0"
    port = 6379
    max_memory = "256mb"
    persistence = {
        enabled = True
        backup_schedule = "0 2 * * *"
    }
    security = {
        require_auth = True
        password_file = "/etc/redis/auth"
    }
}
```

### PostgreSQL Task Service
```kcl
postgres_config: Postgres = {
    name = "postgres"
    version = "15"
    port = 5432
    max_connections = 100
    shared_buffers = "256MB"
    databases = ["app_db", "metrics_db"]
    users = [
        {name = "app_user", databases = ["app_db"]}
    ]
}
```

## Integration Features

### Dependency Management
Task services can define dependencies and resource requirements:

```kcl
dependencies: TaskServDependencies = {
    system_requirements = {
        min_memory_gb = 2
        min_cpu_cores = 1
        min_disk_gb = 20
    }
    service_dependencies = ["containerd", "cilium"]
    health_checks = [
        {
            name = "service_ready"
            endpoint = "http://localhost:8080/health"
            timeout_seconds = 30
        }
    ]
}
```

### Version Tracking
Automated version management with GitHub integration:

```kcl
version_config: TaskServVersionConfig = {
    current_version = "1.28.0"
    github_repo = "kubernetes/kubernetes"
    update_channel = "stable"
    auto_update = False
}
```

### Orchestrator Integration
Full support for workflow orchestration:
- Parallel installation across multiple servers
- Dependency resolution and ordering
- Health monitoring and validation
- Rollback capabilities

## Development

### Creating a New Task Service

1. Create task service directory: `mkdir <taskserv-name>`
2. Create KCL directory: `mkdir <taskserv-name>/kcl`
3. Define schemas:
   - `<taskserv-name>.k` - Main configuration schema
   - `version.k` - Version management (optional)
   - `dependencies.k` - Dependencies and requirements (optional)
4. Add module definition: `kcl.mod`
5. Register in task service registry

### Required KCL Module Structure

```toml
[package]
name = "taskserv-name"
edition = "v0.11.2"
version = "0.0.1"

[dependencies]
provisioning = { path = "../../../kcl", version = "0.0.1" }
taskservs = { path = "../..", version = "0.0.1" }
```

### Validation and Testing

```bash
# Validate task service KCL
kcl run <taskserv>/kcl/

# Test installation
provisioning/core/cli/provisioning --debug --check taskserv create <taskserv>
```

### Implementation Requirements

Task services should implement:
- Installation and configuration procedures
- Health check endpoints
- Service lifecycle management (start, stop, restart)
- Monitoring and logging integration
- Backup and recovery procedures
- Security configuration

For detailed information about specific task services, see their individual directories and the main [provisioning documentation](../../../docs/).