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

```text
# 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:

```text
# 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

```text
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

```text
# 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

```text
# 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`

```text
# Discover available providers
provisioning module discover providers

# Load provider
provisioning module load providers workspace my-provider
```

## Provider API Examples

### Create Servers

```text
use my_provider.nu *

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

create-servers $plan
```

### List Servers

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

### Get Pricing

```text
get-pricing "small" | to yaml
```

## Testing Providers

Use the test environment system to test providers:

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

## Provider Development Guide

For complete provider development guide, see:

- **[Provider Development](../development/QUICK_PROVIDER_GUIDE.md)** - Quick start guide
- **[Extension Development](../development/extensions.md)** - Complete extension guide
- **[Integration Examples](integration-examples.md)** - 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](integration-examples.md).