provisioning/EXTENSION_DEMO.md

Extension System Demonstration

Overview

The provisioning system now has a complete extension architecture that allows adding custom providers, task services, and access control without forking the main codebase.

✅ What's Working

1. Extension Discovery and Loading

• Project-specific extensions: .provisioning/extensions/ (highest priority)
• User extensions: ~/.provisioning-extensions/
• System-wide extensions: /opt/provisioning-extensions/
• Environment override: $PROVISIONING_EXTENSIONS_PATH

2. Provider Extensions

Created working DigitalOcean provider extension:

.provisioning/extensions/providers/digitalocean/
├── manifest.yaml          # Extension metadata
├── nulib/digitalocean/
│   └── servers.nu         # Provider implementation
└── hooks/
    ├── validate-credentials.nu  # Pre-creation validation
    └── notify-created.nu       # Post-creation notification

3. TaskServ Extensions

Created monitoring task service with multiple profiles:

.provisioning/extensions/taskservs/monitoring/
├── manifest.yaml                    # Extension metadata
├── production/install-monitoring.sh # Full monitoring stack
├── staging/install-monitoring.sh    # Lighter configuration
└── development/install-monitoring.sh # Minimal setup

4. Access Control Profiles

Created three access profiles:

• cicd.yaml: Restricted CI/CD permissions
• developer.yaml: Moderate restrictions for developers
• readonly.yaml: Read-only access for monitoring

5. Persistent Registry

• Extensions are cached in ~/.cache/provisioning/extension-registry.json
• Registry persists between command invocations
• Automatic discovery and registration

🎯 Working Commands

Extension Management

# Initialize extension registry
./core/nulib/provisioning extensions init

# List all extensions
./core/nulib/provisioning extensions list

# List specific type
./core/nulib/provisioning extensions list --type provider
./core/nulib/provisioning extensions list --type taskserv

# Show extension details
./core/nulib/provisioning extensions show digitalocean
./core/nulib/provisioning extensions show monitoring

Profile Management

# Show current profile (unrestricted by default)
./core/nulib/provisioning profile show

# Use CI/CD restricted profile
PROVISIONING_PROFILE=cicd ./core/nulib/provisioning profile show

# Use developer profile
PROVISIONING_PROFILE=developer ./core/nulib/provisioning profile show

# Use read-only profile
PROVISIONING_PROFILE=readonly ./core/nulib/provisioning profile show

📋 Demo Results

Extension Discovery

Available Extensions:

Providers:
╭───┬──────────────┬─────────────────────────────────────╮
│ # │     name     │               path                  │
├───┼──────────────┼─────────────────────────────────────┤
│ 0 │ digitalocean │ .provisioning/extensions/providers/ │
│   │              │ digitalocean                        │
╰───┴──────────────┴─────────────────────────────────────╯

TaskServs:
╭───┬────────────┬───────────────────────────────────────╮
│ # │    name    │                path                   │
├───┼────────────┼───────────────────────────────────────┤
│ 0 │ monitoring │ .provisioning/extensions/taskservs/   │
│   │            │ monitoring                            │
╰───┴────────────┴───────────────────────────────────────╯

Extension Details

DigitalOcean provider includes:

• API token validation
• Multiple regions (nyc1, nyc3, ams3, sgp1, lon1, fra1, tor1, sfo3)
• Multiple server sizes (s-1vcpu-1gb through s-4vcpu-8gb)
• Pre/post creation hooks
• Complete server lifecycle management

Monitoring taskserv includes:

• Three deployment profiles (production, staging, development)
• Prometheus, Grafana, AlertManager stack
• Profile-specific configurations
• Helm-based installation scripts

Access Control

CI/CD profile restrictions:

• ✅ Allowed: server list, taskserv status, cluster status
• ❌ Blocked: server delete, sops edit, cluster create
• 🎯 Limited to: local/digitalocean providers, max 5 servers

🔧 Technical Implementation

Key Features

1. Environment Variable Configuration

   • PROVISIONING_EXTENSION_MODE: full, restricted, disabled
   • PROVISIONING_PROFILE: Active access control profile
   • PROVISIONING_EXTENSIONS_PATH: Custom extension path

2. File-based Registry Cache

   • Persistent storage in ~/.cache/provisioning/extension-registry.json
   • Automatic refresh on extensions init
   • Cross-session persistence

3. Manifest-driven Extensions

   • YAML manifests with metadata, requirements, permissions
   • Version management and dependency checking
   • Hook system for lifecycle events

4. Security Model

   • Profile-based access control
   • Extension allowlist/blocklist
   • Permission system
   • Command filtering

🚀 Benefits

1. No Fork Required: Extend functionality without modifying core codebase
2. Flexible Deployment: Project, user, and system-wide extension support
3. Secure by Default: Granular access control for different environments
4. Easy Management: Simple CLI commands for extension lifecycle
5. Persistent State: Registry survives command invocations

📖 Usage Examples

CI/CD Pipeline Integration

# Set restricted profile for CI/CD
export PROVISIONING_PROFILE=cicd
export PROVISIONING_EXTENSION_MODE=restricted

# These commands work in CI/CD
provisioning server list          ✅
provisioning taskserv status      ✅

# These commands are blocked
provisioning server delete        ❌
provisioning sops edit secrets    ❌

Developer Workflow

# Developer can create/delete but limited resources
export PROVISIONING_PROFILE=developer

provisioning server create --region nyc1 --size s-1vcpu-1gb  ✅
provisioning taskserv create monitoring --profile development ✅

Production Safety

# Read-only access for monitoring agents
export PROVISIONING_PROFILE=readonly

provisioning server list    ✅ (monitoring)
provisioning server delete  ❌ (blocked)

This extension system provides unlimited customization while maintaining security and simplicity.