provisioning/docs/src/api-reference/provider-api.md

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 Nickel format:

# Example: UpCloud provider configuration
{
  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/
├── nulib/
│   └── my_provider.nu          # Provider implementation
├── schemas/
│   ├── main.ncl                # Nickel schema
│   └── defaults.ncl            # 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. Nickel Schema

# main.ncl
{
  MyProvider = {
    # My custom provider schema
    name | String = "my-provider",
    type | String | "cloud" | "local" = "cloud",
    config | MyProviderConfig,
  },

  MyProviderConfig = {
    api_key | String,
    region | String = "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.