Provider Override Functionality¶

The --provider flag allows you to override the selected provider instance for any command, similar to how --scheduler overrides the scheduler strategy.

Overview¶

Provider override enables you to: - Test different provider configurations without changing config files - Use specific provider instances for individual commands - Switch between development, staging, and production providers - Combine with scheduler overrides for complete environment control

Usage¶

Basic Syntax¶

orb --provider PROVIDER_INSTANCE_NAME [command] [args...]

Provider Instance Names¶

Provider instances are defined in your configuration file with naming patterns:

AWS Provider Pattern: {type}_{profile}_{region} - aws_prod_us-west-2 - AWS production in US West 2 - aws_dev_eu-west-1 - AWS development in EU West 1 - aws_staging_us-east-1 - AWS staging in US East 1

Custom Naming: You can use any naming convention in your configuration: - aws-production - aws-development
- primary-aws - backup-aws

Examples¶

Template Operations¶

# List templates using production provider
orb --provider aws-prod templates list

# Generate templates for development provider
orb --provider aws-dev templates generate

# Show template with specific provider context
orb --provider aws-staging templates show aws-basic

Machine Requests¶

# Request machines from production provider
orb --provider aws-prod machines request aws-basic 5

# Request from development provider with different scheduler
orb --scheduler hostfactory --provider aws-dev machines request template-id 3

# Check machine status with specific provider
orb --provider aws-prod machines status i-1234567890abcdef0

Request Management¶

# Check request status with production provider
orb --provider aws-prod requests status req-123

# List requests from development environment
orb --provider aws-dev requests list --status pending

# Cancel request with specific provider context
orb --provider aws-staging requests cancel req-456

Provider Health Checks¶

# Check specific provider health
orb --provider aws-prod providers health

# Compare health across providers
orb --provider aws-prod providers health --format table
orb --provider aws-dev providers health --format table

Configuration Requirements¶

Provider Instance Definition¶

Your configuration file must define the provider instances:

{
  "provider": {
    "providers": [
      {
        "name": "aws-prod",
        "type": "aws",
        "enabled": true,
        "config": {
          "profile": "production",
          "region": "us-west-2",
          "role_arn": "arn:aws:iam::123456789012:role/ProdRole"
        }
      },
      {
        "name": "aws-dev",
        "type": "aws", 
        "enabled": true,
        "config": {
          "profile": "development",
          "region": "us-east-1"
        }
      },
      {
        "name": "aws-staging",
        "type": "aws",
        "enabled": true,
        "config": {
          "profile": "staging",
          "region": "eu-west-1"
        }
      }
    ]
  }
}

Validation¶

The system validates provider overrides:

Provider exists - Must be defined in configuration
Provider enabled - Must not be disabled
Provider compatible - Should work with requested operations

Error Handling¶

Provider Not Found¶

$ orb --provider nonexistent-provider templates list
Error: Provider instance 'nonexistent-provider' not found
Available providers: aws-prod, aws-dev, aws-staging

Provider Disabled¶

$ orb --provider disabled-provider machines request template-id 1
Error: Provider instance 'disabled-provider' is disabled

Configuration Issues¶

$ orb --provider aws-misconfigured providers health
Error: Provider 'aws-misconfigured' configuration invalid: missing required field 'region'

Precedence Order¶

When multiple provider selection methods are used:

CLI Override (--provider) - Highest precedence
Template Setting (provider_name in template) - Medium precedence
Configuration Default - Lowest precedence

Example¶

// Template with provider setting
{
  "template_id": "aws-basic",
  "provider_name": "aws-dev",
  // ... other fields
}

# CLI override wins over template setting
orb --provider aws-prod machines request aws-basic 1
# Uses aws-prod, not aws-dev from template

Multi-Provider Template Generation¶

Provider override works with template generation:

Generate for Specific Provider¶

# Generate templates for production provider only
orb --provider aws-prod templates generate

# Generate with specific API for development
orb --provider aws-dev templates generate --provider-api EC2Fleet

Provider-Aware Template Files¶

Generated templates are named by provider:

config/
├── aws-prod_templates.json     # Production templates
├── aws-dev_templates.json      # Development templates  
└── aws-staging_templates.json  # Staging templates

Combined with Scheduler Override¶

Provider and scheduler overrides work together:

# Use HostFactory scheduler with production provider
orb --scheduler hostfactory --provider aws-prod machines request template-id 5

# Use default scheduler with development provider
orb --scheduler default --provider aws-dev templates list --format table

# Test configuration with specific scheduler and provider
orb --scheduler hf --provider aws-staging system health --detailed

Best Practices¶

Development Workflow¶

# Development commands
orb --provider aws-dev templates generate
orb --provider aws-dev machines request test-template 1

# Staging validation
orb --provider aws-staging machines request prod-template 1 --dry-run

# Production deployment
orb --provider aws-prod machines request prod-template 10

Environment Testing¶

# Test same template across environments
orb --provider aws-dev machines request aws-basic 1
orb --provider aws-staging machines request aws-basic 1  
orb --provider aws-prod machines request aws-basic 1

# Compare provider health
orb --provider aws-dev providers health --format table
orb --provider aws-prod providers health --format table

Configuration Validation¶

# Validate each provider configuration
orb --provider aws-dev config validate
orb --provider aws-staging config validate
orb --provider aws-prod config validate

# Test connectivity
orb --provider aws-dev providers health
orb --provider aws-prod providers health

Troubleshooting¶

List Available Providers¶

# See all configured providers
orb providers list --format table

# Show detailed provider information
orb providers list --detailed --format yaml

Provider Configuration Details¶

# Show specific provider configuration
orb --provider aws-prod providers show --format yaml

# Check provider health
orb --provider aws-prod providers health --detailed

Debug Provider Selection¶

# Use verbose output to see provider selection
orb --verbose --provider aws-dev machines request template-id 1

# Check what provider would be selected
orb --dry-run --provider aws-prod machines request template-id 1

Integration with Other Features¶

MCP Server Mode¶

Provider override works with MCP server:

# Start MCP server with specific provider context
orb --provider aws-prod mcp serve --stdio

API Server Mode¶

# Start API server with provider override
orb --provider aws-dev system serve --port 8000

Batch Operations¶

# Process multiple requests with same provider
orb --provider aws-prod requests status req-123 req-456 req-789

# Return multiple machines from specific provider
orb --provider aws-prod machines return i-123 i-456 i-789