2026-01-14 03:09:18 +00:00
|
|
|
# Provider API Reference\n\nAPI documentation for creating and using infrastructure providers.\n\n## Overview\n\nProviders handle cloud-specific operations and resource provisioning. The provisioning platform supports multiple cloud providers through a unified API.\n\n## Supported Providers\n\n- **UpCloud** - European cloud provider\n- **AWS** - Amazon Web Services\n- **Local** - Local development environment\n\n## Provider Interface\n\nAll providers must implement the following interface:\n\n### Required Functions\n\n```\n# Provider initialization\nexport def init [] -> record { ... }\n\n# Server operations\nexport def create-servers [plan: record] -> list { ... }\nexport def delete-servers [ids: list] -> bool { ... }\nexport def list-servers [] -> table { ... }\n\n# Resource information\nexport def get-server-plans [] -> table { ... }\nexport def get-regions [] -> list { ... }\nexport def get-pricing [plan: string] -> record { ... }\n```\n\n### Provider Configuration\n\nEach provider requires configuration in Nickel format:\n\n```\n# Example: UpCloud provider configuration\n{\n provider = {\n name = "upcloud",\n type = "cloud",\n enabled = true,\n config = {\n username = "{{env.UPCLOUD_USERNAME}}",\n password = "{{env.UPCLOUD_PASSWORD}}",\n default_zone = "de-fra1",\n },\n }\n}\n```\n\n## Creating a Custom Provider\n\n### 1. Directory Structure\n\n```\nprovisioning/extensions/providers/my-provider/\n├── nulib/\n│ └── my_provider.nu # Provider implementation\n├── schemas/\n│ ├── main.ncl # Nickel schema\n│ └── defaults.ncl # Default configuration\n└── README.md # Provider documentation\n```\n\n### 2. Implementation Template\n\n```\n# my_provider.nu\nexport def init [] {\n {\n name: "my-provider"\n type: "cloud"\n ready: true\n }\n}\n\nexport def create-servers [plan: record] {\n # Implementation here\n []\n}\n\nexport def list-servers [] {\n # Implementation here\n []\n}\n\n# ... other required functions\n```\n\n### 3. Nickel Schema\n\n```\n# main.ncl\n{\n MyProvider = {\n # My custom provider schema\n name | String = "my-provider",\n type | String | "cloud" | "local" = "cloud",\n config | MyProviderConfig,\n },\n\n MyProviderConfig = {\n api_key | String,\n region | String = "us-east-1",\n },\n}\n```\n\n## Provider Discovery\n\nProviders are automatically discovered from:\n\n- `provisioning/extensions/providers/*/nu/*.nu`\n- User workspace: `workspace/extensions/providers/*/nu/*.nu`\n\n```\n# Discover available providers\nprovisioning module discover providers\n\n# Load provider\nprovisioning module load providers workspace my-provider\n```\n\n## Provider API Examples\n\n### Create Servers\n\n```\nuse my_provider.nu *\n\nlet plan = {\n count: 3\n size: "medium"\n zone: "us-east-1"\n}\n\ncreate-servers $plan\n```\n\n### List Servers\n\n```\nlist-servers | where status == "running" | select hostname ip_address\n```\n\n### Get Pricing\n\n```\nget-pricing "small" | to yaml\n```\n\n## Testing Providers\n\nUse the test environment system to test providers:\n\n```\n# Test provider without real resources\nprovisioning test env single my-provider --check\n```\n\n## Provider Development Guide\n\nFor complete provider development guide, see:\n\n- **[Provider Development](../development/QUICK_PROVIDER_GUIDE.md)** - Quick start guide\n- **[Extension Development](../development/extensions.md)** - Complete extension guide\n- **[Integration Examples](integration-examples.md)** - Example implementations\n\n## API Stability\n\nProvider API follows semantic versioning:\n\n- **Major**: Breaking changes\n- **Minor**: New features, backward compatible\n- **Patch**: Bug fixes\n\nCurrent API version: `2.0.0`\n\n---\n\nFor more examples, see [Integration Examples](integration-examples.md).
|
