<p align="center">
  <img src="resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
</p>
<p align="center">
  <img src="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/provisioning/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:

- **Hetzner**: infrastructure provider
- **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 Nickel 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**: Nickel 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.ncl"

# 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

### Nickel Schema Structure

Extensions use standardized Nickel schema patterns:

```nickel
# Provider schema
let provider_schema = {
  name : String,
  provider_field : String,
  version : String,
} in provider_schema

# Task service schema
let taskservice_schema = {
  name : String = "service-name",
  version : String,
  enabled : Bool = true,
} in taskservice_schema

# Cluster schema
let cluster_schema = {
  name : String = "cluster-name",
  components : Array String,
} in cluster_schema
```

### Module Configuration

Each extension includes a `manifest.toml` file:

```toml
[package]
name = "extension-name"
version = "0.0.1"

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

### Directory Structure

```bash
extension-name/
├── schemas/                # Nickel configuration schemas
│   ├── extension-name.ncl  # Main schema definition
│   ├── version.ncl         # Version management (optional)
│   ├── dependencies.ncl    # Dependencies (optional)
│   └── manifest.toml       # Module configuration
├── default/               # Default configurations
├── templates/             # Jinja2 templates (optional)
└── README.md              # Extension documentation
```

## Quality Assurance

### Validation Results

- **43 Nickel schema directories** with comprehensive schema validation
- **44 manifest.toml files** with proper import structure
- **Syntax validation**: All major components pass Nickel type checking
- **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/).