provisioning-catalog/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/schemas/defaults_aws.ncl`, `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/schemas/defaults_upcloud.ncl`, `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/schemas/defaults_local.ncl`, `server_local.k`, `provision_local.k`

## Provider Architecture

### Schema Structure

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

```bash
# Common base schemas extended by each provider
let storage_provider = { /* provider-specific fields */ } in storage_provider
let server_defaults_provider = { /* server defaults */ } in server_defaults_provider
let provision_provider = { /* provisioning config */ } in provision_provider
```

### Configuration Patterns

1. **defaults_*.ncl**: Provider-specific default configurations and schemas
2. **server_*.ncl**: Server provisioning and management schemas
3. **provision_*.ncl**: Environment and provisioning settings
4. **dependencies.ncl**: 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

```toml
# 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.ncl"
```

## Configuration Examples

### AWS Configuration

```javascript
let aws_config = {
  volumes = [
    {
      device = "/dev/sda1",
      size_gb = 20,
      volume_type = "gp3",
      encrypted = true,
    }
  ],
  vpc = {
    cidr_block = "10.0.0.0/16",
    enable_dns_hostnames = true,
  },
} in aws_config
```

### UpCloud Configuration

```javascript
let upcloud_config = {
  volumes = [
    {
      size_gb = 25,
      volume_type = "maxiops",
      backup = {
        enabled = true,
        schedule = "daily",
        retention_days = 7,
      },
    }
  ],
} in upcloud_config
```

### Local Configuration

```javascript
let local_config = {
  volumes = [
    {
      size_gb = 10,
      mount_path = "/data",
    }
  ],
  network = {
    bridge_name = "provisioning-br0",
  },
} in local_config
```

## 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 Nickel schemas directory: `mkdir <provider-name>/schemas`
3. Implement required schemas:
   - `defaults_<provider>.ncl` - Provider defaults and schemas
   - `server_<provider>.ncl` - Server management
   - `provision_<provider>.ncl` - Environment settings
   - `dependencies.ncl` - Dependency management
4. Add module definition: `manifest.toml`
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 Nickel definitions
nickel typecheck <provider>/schemas/*.ncl

# 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/).