prvng_extensions/providers/README.md

# Cloud Providers

This directory contains provider implementations for different cloud platforms and local environments. Providers handle the infrastructure provisioning and management for servers, networking, and storage resources.

## Available Providers

### AWS Provider (`aws/`)
**Platform**: Amazon Web Services
**Features**:
- EC2 instance management with multiple instance types
- VPC networking with Security Groups and multi-AZ support
- EBS volume types (gp2, gp3, io1, io2, st1, sc1)
- Advanced networking with subnet and route table management
- IAM integration for security and access control

**Configuration**: `aws/kcl/defaults_aws.k`, `server_aws.k`, `provision_aws.k`

### UpCloud Provider (`upcloud/`)
**Platform**: UpCloud infrastructure
**Features**:
- Server provisioning with flexible plans and zones
- Advanced backup scheduling with automated snapshots
- Server grouping and organization capabilities
- Multiple storage types (maxiops, hdd, custom) with backup support
- Network configuration with firewall rules

**Configuration**: `upcloud/kcl/defaults_upcloud.k`, `server_upcloud.k`, `provision_upcloud.k`

### Local Provider (`local/`)
**Platform**: Local development environment
**Features**:
- Local server simulation for development and testing
- Simplified storage and networking configuration
- Container-based local infrastructure
- Development workflow optimization
- Testing and validation support

**Configuration**: `local/kcl/defaults_local.k`, `server_local.k`, `provision_local.k`

## Provider Architecture

### Schema Structure
Each provider implements a consistent interface while providing platform-specific capabilities:

```kcl
# Common base schemas extended by each provider
Storage_provider(provisioning.Storage)
ServerDefaults_provider(provisioning.ServerDefaults)
Provision_provider(provisioning.Provision)
```

### Configuration Patterns
1. **defaults_*.k**: Provider-specific default configurations and schemas
2. **server_*.k**: Server provisioning and management schemas
3. **provision_*.k**: Environment and provisioning settings
4. **dependencies.k**: Dependency management for batch workflows

## Usage

### Server Creation

```bash
# Using specific provider
PROVISIONING_PROVIDER=aws provisioning/core/cli/provisioning server create

# Provider auto-detection based on infrastructure configuration
provisioning/core/cli/provisioning server create --infra <infra-name>
```

### Provider Configuration

```bash
# Show provider-specific settings
provisioning/core/cli/provisioning show settings --provider aws

# List provider capabilities
provisioning/core/cli/provisioning show providers
```

### Batch Operations

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

## Configuration Examples

### AWS Configuration
```kcl
aws_config: Storage_aws = {
    volumes = [
        {
            device = "/dev/sda1"
            size_gb = 20
            volume_type = "gp3"
            encrypted = True
        }
    ]
    vpc = {
        cidr_block = "10.0.0.0/16"
        enable_dns_hostnames = True
    }
}
```

### UpCloud Configuration
```kcl
upcloud_config: Storage_upcloud = {
    volumes = [
        {
            size_gb = 25
            volume_type = "maxiops"
            backup = {
                enabled = True
                schedule = "daily"
                retention_days = 7
            }
        }
    ]
}
```

### Local Configuration
```kcl
local_config: Storage_local = {
    volumes = [
        {
            size_gb = 10
            mount_path = "/data"
        }
    ]
    network = {
        bridge_name = "provisioning-br0"
    }
}
```

## Integration Features

### Batch Workflow Support
All providers support batch operations for:
- Multiple server provisioning
- Cross-provider deployments
- Dependency management and ordering
- Rollback and recovery capabilities

### Task Service Integration
Providers integrate seamlessly with task services for:
- Container runtime installation
- Kubernetes cluster setup
- Networking configuration
- Storage provisioning

### Orchestrator Support
Full integration with the Rust orchestrator for:
- High-performance coordination
- REST API access
- Real-time monitoring
- State management

## Development

### Adding a New Provider

1. Create provider directory: `mkdir <provider-name>`
2. Create KCL directory: `mkdir <provider-name>/kcl`
3. Implement required schemas:
   - `defaults_<provider>.k` - Provider defaults and schemas
   - `server_<provider>.k` - Server management
   - `provision_<provider>.k` - Environment settings
   - `dependencies.k` - Dependency management
4. Add module definition: `kcl.mod`
5. Register provider in main provisioning module

### Provider Interface Requirements

Providers must implement:
- Server lifecycle management (create, delete, list, status)
- Storage and volume management
- Network configuration
- Security and access control
- Monitoring and health checks

### Validation and Testing

```bash
# Validate provider KCL definitions
kcl run <provider>/kcl/

# Test provider functionality
provisioning/core/cli/provisioning --debug --check server create --provider <provider>
```

For detailed provider-specific documentation, see the individual provider directories and the main [provisioning documentation](../../../docs/).