8.6 KiB
8.6 KiB
interface.nu)\n\nDefines the contract that all providers must implement:\n\n\n# Standard interface functions\n- query_servers\n- server_info\n- server_exists\n- create_server\n- delete_server\n- server_state\n- get_ip\n# ... and 20+ other functions\n\n\nKey Features:\n\n- Type-safe function signatures\n- Comprehensive validation\n- Provider capability flags\n- Interface versioning\n\n### 2. Provider Registry (registry.nu)\n\nManages provider discovery and registration:\n\n\n# Initialize registry\ninit-provider-registry\n\n# List available providers\nlist-providers --available-only\n\n# Check provider availability\nis-provider-available "aws"\n\n\nFeatures:\n\n- Automatic provider discovery\n- Core and extension provider support\n- Caching for performance\n- Provider capability tracking\n\n### 3. Provider Loader (loader.nu)\n\nHandles dynamic provider loading and validation:\n\n\n# Load provider dynamically\nload-provider "aws"\n\n# Get provider with auto-loading\nget-provider "upcloud"\n\n# Call provider function\ncall-provider-function "aws" "query_servers" $find $cols\n\n\nFeatures:\n\n- Lazy loading (load only when needed)\n- Interface compliance validation\n- Error handling and recovery\n- Provider health checking\n\n### 4. Provider Adapters\n\nEach provider implements a standard adapter:\n\n\nprovisioning/extensions/providers/\n├── aws/provider.nu # AWS adapter\n├── upcloud/provider.nu # UpCloud adapter\n├── local/provider.nu # Local adapter\n└── {custom}/provider.nu # Custom providers\n\n\nAdapter Structure:\n\n\n# AWS Provider Adapter\nexport def query_servers [find?: string, cols?: string] {\n aws_query_servers $find $cols\n}\n\nexport def create_server [settings: record, server: record, check: bool, wait: bool] {\n # AWS-specific implementation\n}\n\n\n### 5. Provider-Agnostic Middleware (middleware_provider_agnostic.nu)\n\nThe new middleware that uses dynamic dispatch:\n\n\n# No hardcoded imports!\nexport def mw_query_servers [settings: record, find?: string, cols?: string] {\n $settings.data.servers | each { |server|\n # Dynamic provider loading and dispatch\n dispatch_provider_function $server.provider "query_servers" $find $cols\n }\n}\n\n\n## Multi-Provider Support\n\n### Example: Mixed Provider Infrastructure\n\n\nlet servers = [\n {\n hostname = "compute-01",\n provider = "aws",\n # AWS-specific config\n },\n {\n hostname = "backup-01",\n provider = "upcloud",\n # UpCloud-specific config\n },\n {\n hostname = "api.example.com",\n provider = "cloudflare",\n # DNS-specific config\n },\n] in\nservers\n\n\n### Multi-Provider Deployment\n\n\n# Deploy across multiple providers automatically\nmw_deploy_multi_provider_infra $settings $deployment_plan\n\n# Get deployment strategy recommendations\nmw_suggest_deployment_strategy {\n regions: ["us-east-1", "eu-west-1"]\n high_availability: true\n cost_optimization: true\n}\n\n\n## Provider Capabilities\n\nProviders declare their capabilities:\n\n\ncapabilities: {\n server_management: true\n network_management: true\n auto_scaling: true # AWS: yes, Local: no\n multi_region: true # AWS: yes, Local: no\n serverless: true # AWS: yes, UpCloud: no\n compliance_certifications: ["SOC2", "HIPAA"]\n}\n\n\n## Migration Guide\n\n### From Old Middleware\n\nBefore (hardcoded):\n\n\n# middleware.nu\nuse ../aws/nulib/aws/servers.nu *\nuse ../upcloud/nulib/upcloud/servers.nu *\n\nmatch $server.provider {\n "aws" => { aws_query_servers $find $cols }\n "upcloud" => { upcloud_query_servers $find $cols }\n}\n\n\nAfter (provider-agnostic):\n\n\n# middleware_provider_agnostic.nu\n# No hardcoded imports!\n\n# Dynamic dispatch\ndispatch_provider_function $server.provider "query_servers" $find $cols\n\n\n### Migration Steps\n\n1. Replace middleware file:\n\n bash\n cp provisioning/extensions/providers/prov_lib/middleware.nu \\n provisioning/extensions/providers/prov_lib/middleware_legacy.backup\n\n cp provisioning/extensions/providers/prov_lib/middleware_provider_agnostic.nu \\n provisioning/extensions/providers/prov_lib/middleware.nu\n \n\n1. Test with existing infrastructure:\n\n nushell\n ./provisioning/tools/test-provider-agnostic.nu run-all-tests\n \n\n2. Update any custom code that directly imported provider modules\n\n## Adding New Providers\n\n### 1. Create Provider Adapter\n\nCreate provisioning/extensions/providers/{name}/provider.nu:\n\n\n# Digital Ocean Provider Example\nexport def get-provider-metadata [] {\n {\n name: "digitalocean"\n version: "1.0.0"\n capabilities: {\n server_management: true\n # ... other capabilities\n }\n }\n}\n\n# Implement required interface functions\nexport def query_servers [find?: string, cols?: string] {\n # DigitalOcean-specific implementation\n}\n\nexport def create_server [settings: record, server: record, check: bool, wait: bool] {\n # DigitalOcean-specific implementation\n}\n\n# ... implement all required functions\n\n\n### 2. Provider Discovery\n\nThe registry will automatically discover the new provider on next initialization.\n\n### 3. Test New Provider\n\n\n# Check if discovered\nis-provider-available "digitalocean"\n\n# Load and test\nload-provider "digitalocean"\ncheck-provider-health "digitalocean"\n\n\n## Best Practices\n\n### Provider Development\n\n1. Implement full interface - All functions must be implemented\n2. Handle errors gracefully - Return appropriate error values\n3. Follow naming conventions - Use consistent function naming\n4. Document capabilities - Accurately declare what your provider supports\n5. Test thoroughly - Validate against the interface specification\n\n### Multi-Provider Deployments\n\n1. Use capability-based selection - Choose providers based on required features\n2. Handle provider failures - Design for provider unavailability\n3. Optimize for cost/performance - Mix providers strategically\n4. Monitor cross-provider dependencies - Understand inter-provider communication\n\n### Profile-Based Security\n\n\n# Environment profiles can restrict providers\nPROVISIONING_PROFILE=production # Only allows certified providers\nPROVISIONING_PROFILE=development # Allows all providers including local\n\n\n## Troubleshooting\n\n### Common Issues\n\n1. Provider not found\n - Check provider is in correct directory\n - Verify provider.nu exists and implements interface\n - Run init-provider-registry to refresh\n\n2. Interface validation failed\n - Use validate-provider-interface to check compliance\n - Ensure all required functions are implemented\n - Check function signatures match interface\n\n3. Provider loading errors\n - Check Nushell module syntax\n - Verify import paths are correct\n - Use check-provider-health for diagnostics\n\n### Debug Commands\n\n\n# Registry diagnostics\nget-provider-stats\nlist-providers --verbose\n\n# Provider diagnostics\ncheck-provider-health "aws"\ncheck-all-providers-health\n\n# Loader diagnostics\nget-loader-stats\n\n\n## Performance Benefits\n\n1. Lazy Loading - Providers loaded only when needed\n2. Caching - Provider registry cached to disk\n3. Reduced Memory - No hardcoded imports reducing memory usage\n4. Parallel Operations - Multi-provider operations can run in parallel\n\n## Future Enhancements\n\n1. Provider Plugins - Support for external provider plugins\n2. Provider Versioning - Multiple versions of same provider\n3. Provider Composition - Compose providers for complex scenarios\n4. Provider Marketplace - Community provider sharing\n\n## API Reference\n\nSee the interface specification for complete function documentation:\n\n\nget-provider-interface-docs | table\n\n\nThis returns the complete API with signatures and descriptions for all provider interface functions.