Provider API Reference

API documentation for creating and using infrastructure providers.

Overview

Providers handle cloud-specific operations and resource provisioning. The provisioning platform supports multiple cloud providers through a unified API.

Supported Providers

• UpCloud - European cloud provider
• AWS - Amazon Web Services
• Local - Local development environment

Provider Interface

All providers must implement the following interface:

Required Functions

# Provider initialization
export def init [] -> record { ... }

# Server operations
export def create-servers [plan: record] -> list { ... }
export def delete-servers [ids: list] -> bool { ... }
export def list-servers [] -> table { ... }

# Resource information
export def get-server-plans [] -> table { ... }
export def get-regions [] -> list { ... }
export def get-pricing [plan: string] -> record { ... }

Provider Configuration

Each provider requires configuration in KCL format:

# Example: UpCloud provider configuration
provider: Provider = {
    name = "upcloud"
    type = "cloud"
    enabled = True

    config = {
        username = "{{ env.UPCLOUD_USERNAME }}"
        password = "{{ env.UPCLOUD_PASSWORD }}"
        default_zone = "de-fra1"
    }
}

Creating a Custom Provider

1. Directory Structure

provisioning/extensions/providers/my-provider/
├── nu/
│   └── my_provider.nu          # Provider implementation
├── kcl/
│   ├── my_provider.k           # KCL schema
│   └── defaults_my_provider.k  # Default configuration
└── README.md                   # Provider documentation

2. Implementation Template

# my_provider.nu
export def init [] {
    {
        name: "my-provider"
        type: "cloud"
        ready: true
    }
}

export def create-servers [plan: record] {
    # Implementation here
    []
}

export def list-servers [] {
    # Implementation here
    []
}

# ... other required functions

3. KCL Schema

# my_provider.k
import provisioning.lib as lib

schema MyProvider(lib.Provider):
    """My custom provider schema"""

    name: str = "my-provider"
    type: "cloud" | "local" = "cloud"

    config: MyProviderConfig

schema MyProviderConfig:
    api_key: str
    region: str = "us-east-1"

Provider Discovery

Providers are automatically discovered from:

• provisioning/extensions/providers/*/nu/*.nu
• User workspace: workspace/extensions/providers/*/nu/*.nu

# Discover available providers
provisioning module discover providers

# Load provider
provisioning module load providers workspace my-provider

Provider API Examples

Create Servers

use my_provider.nu *

let plan = {
    count: 3
    size: "medium"
    zone: "us-east-1"
}

create-servers $plan

List Servers

list-servers | where status == "running" | select hostname ip_address

Get Pricing

get-pricing "small" | to yaml

Testing Providers

Use the test environment system to test providers:

# Test provider without real resources
provisioning test env single my-provider --check

Provider Development Guide

For complete provider development guide, see:

• Provider Development - Quick start guide
• Extension Development - Complete extension guide
• Integration Examples - Example implementations

API Stability

Provider API follows semantic versioning:

• Major: Breaking changes
• Minor: New features, backward compatible
• Patch: Bug fixes

Current API version: 2.0.0

For more examples, see Integration Examples.