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:

# 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

# 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

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

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

Batch Operations

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

Configuration Examples

AWS Configuration

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

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

Local Configuration

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

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