provisioning-code/templates/extensions/taskservs/basic-taskserv/README.md

# {{TASKSERV_DISPLAY_NAME}} Taskserv

{{TASKSERV_DESCRIPTION}}

## Overview

This taskserv provides deployment and management capabilities for {{TASKSERV_DISPLAY_NAME}} in Kubernetes environments.

## Features

- ✅ **Multi-environment support**: Development, staging, and production profiles
- ✅ **Resource management**: Configurable CPU, memory, and storage allocation
- ✅ **High availability**: Support for replicated deployments
- ✅ **Security**: Built-in security contexts and non-root execution
- ✅ **Monitoring**: Health checks and readiness probes
- ✅ **Storage**: Persistent storage with configurable storage classes
- ✅ **Networking**: Flexible service types and ingress configuration

## Configuration

### Basic Configuration

```toml
import .taskservs.{{TASKSERV_NAME}}.{{TASKSERV_NAME}} as {{TASKSERV_NAME_SNAKE}}

server_config = {
    taskservs = [
        {
            name = "{{TASKSERV_NAME}}"
            profile = "default"
        }
    ]
}
```

### Development Profile

```bash
server_config = {
    taskservs = [
        {
            name = "{{TASKSERV_NAME}}"
            profile = "development"
        }
    ]
}
```

### Production Profile

```bash
server_config = {
    taskservs = [
        {
            name = "{{TASKSERV_NAME}}"
            profile = "production"
        }
    ]
}
```

## Configuration Options

### Core Settings

| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | ------------- |
| `enabled` | bool | `true` | Enable/disable the service |
| `version` | string | `"latest"` | Service version to deploy |
| `port` | int | `{{DEFAULT_PORT}}` | Service port |
| `replicas` | int | `1` | Number of replicas |

### Resource Settings

| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | ------------- |
| `cpu_request` | string | `"100m"` | CPU request |
| `memory_request` | string | `"128Mi"` | Memory request |
| `cpu_limit` | string | `"500m"` | CPU limit |
| `memory_limit` | string | `"512Mi"` | Memory limit |

### Storage Settings

| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | ------------- |
| `storage_enabled` | bool | `true` | Enable persistent storage |
| `storage_size` | string | `"10Gi"` | Storage size |
| `storage_class` | string | optional | Storage class name |

### Network Settings

| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | ------------- |
| `service_type` | string | `"ClusterIP"` | Kubernetes service type |
| `ingress_enabled` | bool | `false` | Enable ingress |

### Security Settings

| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | ------------- |
| `security_context_enabled` | bool | `true` | Enable security context |
| `run_as_non_root` | bool | `true` | Run as non-root user |

## Dependencies

### Required Dependencies

- **kubernetes**: Kubernetes cluster is required for deployment

### Optional Dependencies

- **monitoring**: Enhanced monitoring and metrics collection
- **logging**: Centralized logging integration

### Provided Services

- **{{TASKSERV_NAME}}-api**: {{TASKSERV_DISPLAY_NAME}} API endpoint

## Profiles

### Default Profile

Basic configuration suitable for testing and development.

### Development Profile

Optimized for development environments:

- Single replica
- Reduced resource allocation
- Smaller storage size

### Production Profile

Production-ready configuration:

- Multiple replicas for high availability
- Increased resource allocation
- Load balancer service type
- Ingress enabled

## Installation

### Using Module Loader

```bash
# Load the taskserv
module-loader load taskservs . [{{TASKSERV_NAME}}]

# Deploy using provisioning CLI
provisioning taskserv create {{TASKSERV_NAME}} --infra . --profile production
```

### Manual KCL Configuration

```toml
# In your servers.k file
import .taskservs.{{TASKSERV_NAME}}.{{TASKSERV_NAME}} as {{TASKSERV_NAME_SNAKE}}

servers = [
    {
        hostname = "app-server-01"
        taskservs = [
            {
                name = "{{TASKSERV_NAME}}"
                profile = "production"
            }
        ]
    }
]
```

## Health Checks

The taskserv includes built-in health checks:

- **HTTP Health Check**: `curl -f http://localhost:{{DEFAULT_PORT}}/health`
- **Interval**: 30 seconds
- **Timeout**: 10 seconds
- **Retries**: 3 attempts

## Troubleshooting

### Common Issues

#### Service Not Starting

1. Check resource availability:

   ```bash
   kubectl describe pod {{TASKSERV_NAME}}-*
   ```

2. Verify configuration:

   ```bash
   kcl run servers.k
   ```

3. Check logs:

   ```bash
   kubectl logs -l app={{TASKSERV_NAME}}
   ```

#### Storage Issues

1. Verify storage class exists:

   ```bash
   kubectl get storageclass
   ```

2. Check PVC status:

   ```bash
   kubectl get pvc
   ```

#### Network Connectivity Issues

1. Verify service is running:

   ```bash
   kubectl get svc {{TASKSERV_NAME}}
   ```

2. Test connectivity:

   ```bash
   kubectl port-forward svc/{{TASKSERV_NAME}} {{DEFAULT_PORT}}:{{DEFAULT_PORT}}
   curl http://localhost:{{DEFAULT_PORT}}/health
   ```

### Debug Mode

Enable debug logging by setting environment variables:

```bash
config = {
    environment_vars = {
        "LOG_LEVEL" = "debug"
        "DEBUG" = "true"
    }
}
```

## Development

### Local Development

1. Clone the taskserv:

   ```bash
   cp -r templates/extensions/taskservs/basic-taskserv extensions/taskservs/my-{{TASKSERV_NAME}}
   ```

2. Customize the configuration in `my-{{TASKSERV_NAME}}.k`

3. Test locally:

   ```bash
   module-loader discover taskservs | grep my-{{TASKSERV_NAME}}
   ```

### Contributing

1. Follow the KCL schema validation requirements
2. Include comprehensive documentation
3. Add appropriate health checks
4. Test with multiple profiles
5. Update version information

## Version History

| Version | Date | Changes |
| --------- | ------ | --------- |
| 0.0.1 | {{DATE}} | Initial release |

## Support

- **Documentation**: {{DOCS_URL}}
- **Issues**: {{SUPPORT_URL}}
- **Repository**: {{REPOSITORY_URL}}

## License

{{LICENSE}}