prvng_extensions/README.md

<p align="center">
  <img src="https://repo.jesusperez.pro/jesus/provisioning/media/branch/main/resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
</p>
<p align="center">
  <img src="https://repo.jesusperez.pro/jesus/provisioning/media/branch/main/resources/logo-text.svg" alt="Provisioning" width="500"/>
</p>

# Provisioning Extensions

This directory contains the extensible components of the [Provisioning project](https://repo.jesusperez.pro/jesus/provisioning). Extensions provide modular, configurable infrastructure components that can be combined to create complete deployment solutions.

## Extension Types

### [Providers](providers/)
Cloud provider implementations for infrastructure provisioning:
- **AWS**: Amazon Web Services with EC2, VPC, and EBS support
- **UpCloud**: UpCloud infrastructure with backup and server grouping
- **Local**: Local development environment simulation

### [Task Services](taskservs/)
Modular infrastructure services that can be installed on servers:
- **Container Runtimes**: containerd, crio, podman, crun, youki
- **Orchestration**: kubernetes, cilium, coredns, etcd, rook-ceph
- **Development**: coder, desktop, gitea, webhook
- **Databases**: postgres, redis, external-nfs, mayastor
- **Networking**: ip-aliases, proxy, resolv, kms
- **Security**: oras, radicle

### [Clusters](clusters/)
Complete deployment configurations combining providers and task services:
- **Web**: Basic web service cluster
- **OCI Registry**: Container registry with storage and security
- **Planned**: buildkit, CI/CD pipelines, git hosting, databases

### Workflows
Core workflow templates integrated with the orchestrator:
- Server creation and management workflows
- Task service deployment workflows
- Cluster setup and configuration workflows
- Batch operations and multi-provider deployments
- Backup and recovery workflows

## Architecture

### Configuration-Driven Design
All extensions are defined using KCL schemas providing:
- Type safety and validation
- Hierarchical configuration inheritance
- Modular composition capabilities
- Provider-agnostic interfaces

### Dependency Management
Extensions support sophisticated dependency management:
- Service dependencies and ordering
- Resource requirements validation
- Health checks and monitoring
- Rollback and recovery capabilities

### Integration Points
Extensions integrate with:
- **Core Provisioning System**: Main CLI and library functions
- **Orchestrator**: High-performance Rust coordination layer
- **Workflow System**: Batch operations and automation
- **Configuration System**: KCL schema validation and templating

## Usage Patterns

### Basic Infrastructure Setup
```bash
# 1. Generate infrastructure configuration
provisioning/core/cli/provisioning generate infra --new myproject

# 2. Create servers using provider
provisioning/core/cli/provisioning server create --infra myproject

# 3. Install task services
provisioning/core/cli/provisioning taskserv create kubernetes --infra myproject

# 4. Deploy cluster services
provisioning/core/cli/provisioning cluster create web --infra myproject
```

### Batch Operations
```bash
# Multi-provider batch deployment
nu -c "use core/nulib/workflows/batch.nu *; batch submit workflows/multi_cloud.k"

# Monitor batch progress
nu -c "use core/nulib/workflows/batch.nu *; batch monitor <workflow_id>"
```

### Workflow Management
```bash
# List running workflows
nu -c "use core/nulib/workflows/management.nu *; workflow list"

# Monitor specific workflow
nu -c "use core/nulib/workflows/management.nu *; workflow monitor <task_id>"
```

## Extension Development

### KCL Schema Structure
Extensions use standardized KCL schema patterns:

```kcl
# Provider schema
schema ProviderName(provisioning.Storage):
    # Provider-specific fields
    provider_field: str
    check:
        len(provider_field) > 0

# Task service schema
schema TaskServiceName:
    name: str = "service-name"
    version: str
    enabled: bool = True
    # Service-specific configuration
    check:
        len(name) > 0

# Cluster schema
schema ClusterName:
    name: str = "cluster-name"
    components: [str]
    # Cluster composition
    check:
        len(components) > 0
```

### Module Configuration
Each extension includes a `kcl.mod` file:

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

[dependencies]
provisioning = { path = "../../../kcl", version = "0.0.1" }
# Additional dependencies as needed
```

### Directory Structure
```
extension-name/
├── kcl/                    # KCL configuration schemas
│   ├── extension-name.k    # Main schema definition
│   ├── version.k           # Version management (optional)
│   ├── dependencies.k      # Dependencies (optional)
│   └── kcl.mod            # Module configuration
├── default/               # Default configurations
├── templates/             # Jinja2 templates (optional)
└── README.md              # Extension documentation
```

## Quality Assurance

### Validation Results
- **43 KCL directories** with comprehensive schema validation
- **44 kcl.mod files** with proper import structure
- **Syntax validation**: All major components pass KCL validation
- **Schema compliance**: Follows project architecture principles (PAP)

### Best Practices
- Follow project architecture principles (PAP)
- Use configuration-driven approaches
- Implement comprehensive validation rules
- Provide detailed documentation
- Include usage examples
- Support batch operations
- Enable workflow orchestration

For detailed information about specific extension types, see the documentation in each subdirectory and the main [provisioning documentation](../../docs/).