2026-01-14 02:59:52 +00:00
|
|
|
# Extension Development API\n\nThis document provides comprehensive guidance for developing extensions for provisioning, including providers, task services, and cluster configurations.\n\n## Overview\n\nProvisioning supports three types of extensions:\n\n1. **Providers**: Cloud infrastructure providers (AWS, UpCloud, Local, etc.)\n2. **Task Services**: Infrastructure components (Kubernetes, Cilium, Containerd, etc.)\n3. **Clusters**: Complete deployment configurations (BuildKit, CI/CD, etc.)\n\nAll extensions follow a standardized structure and API for seamless integration.\n\n## Extension Structure\n\n### Standard Directory Layout\n\n```\nextension-name/\n├── manifest.toml # Extension metadata\n├── schemas/ # Nickel configuration files\n│ ├── main.ncl # Main schema\n│ ├── settings.ncl # Settings schema\n│ ├── version.ncl # Version configuration\n│ └── contracts.ncl # Contract definitions\n├── nulib/ # Nushell library modules\n│ ├── mod.nu # Main module\n│ ├── create.nu # Creation operations\n│ ├── delete.nu # Deletion operations\n│ └── utils.nu # Utility functions\n├── templates/ # Jinja2 templates\n│ ├── config.j2 # Configuration templates\n│ └── scripts/ # Script templates\n├── generate/ # Code generation scripts\n│ └── generate.nu # Generation commands\n├── README.md # Extension documentation\n└── metadata.toml # Extension metadata\n```\n\n## Provider Extension API\n\n### Provider Interface\n\nAll providers must implement the following interface:\n\n#### Core Operations\n\n- `create-server(config: record) -> record`\n- `delete-server(server_id: string) -> null`\n- `list-servers() -> list<record>`\n- `get-server-info(server_id: string) -> record`\n- `start-server(server_id: string) -> null`\n- `stop-server(server_id: string) -> null`\n- `reboot-server(server_id: string) -> null`\n\n#### Pricing and Plans\n\n- `get-pricing() -> list<record>`\n- `get-plans() -> list<record>`\n- `get-zones() -> list<record>`\n\n#### SSH and Access\n\n- `get-ssh-access(server_id: string) -> record`\n- `configure-firewall(server_id: string, rules: list<record>) -> null`\n\n### Provider Development Template\n\n#### Nickel Configuration Schema\n\nCreate `schemas/settings.ncl`:\n\n```\n# Provider settings schema\n{\n ProviderSettings = {\n # Authentication configuration\n auth | {\n method | "api_key" | "certificate" | "oauth" | "basic",\n api_key | String = null,\n api_secret | String = null,\n username | String = null,\n password | String = null,\n certificate_path | String = null,\n private_key_path | String = null,\n },\n\n # API configuration\n api | {\n base_url | String,\n version | String = "v1",\n timeout | Number = 30,\n retries | Number = 3,\n },\n\n # Default server configuration\n defaults: {\n plan?: str\n zone?: str\n os?: str\n ssh_keys?: [str]\n firewall_rules?: [FirewallRule]\n }\n\n # Provider-specific settings\n features: {\n load_balancer?: bool = false\n storage_encryption?: bool = true\n backup?: bool = true\n monitoring?: bool = false\n }\n}\n\nschema FirewallRule {\n direction: "ingress" | "egress"\n protocol: "tcp" | "udp" | "icmp"\n port?: str\n source?: str\n destination?: str\n action: "allow" | "deny"\n}\n\nschema ServerConfig {\n hostname: str\n plan: str\n zone: str\n os: str = "ubuntu-22.04"\n ssh_keys: [str] = []\n tags?: {str: str} = {}\n firewall_rules?: [FirewallRule] = []\n storage?: {\n size?: int\n type?: str\n encrypted?: bool = true\n }\n network?: {\n public_ip?: bool = true\n
|
