# Provisioning Platform Quick Reference **Version**: 3.5.0 **Last Updated**: 2025-10-09 --- ## Quick Navigation - [Plugin Commands](#plugin-commands) - Native Nushell plugins (10-50x faster) - [CLI Shortcuts](#cli-shortcuts) - 80+ command shortcuts - [Infrastructure Commands](#infrastructure-commands) - Servers, taskservs, clusters - [Orchestration Commands](#orchestration-commands) - Workflows, batch operations - [Configuration Commands](#configuration-commands) - Config, validation, environment - [Workspace Commands](#workspace-commands) - Multi-workspace management - [Security Commands](#security-commands) - Auth, MFA, secrets, compliance - [Common Workflows](#common-workflows) - Complete deployment examples - [Debug and Check Mode](#debug-and-check-mode) - Testing and troubleshooting - [Output Formats](#output-formats) - JSON, YAML, table formatting --- ## Plugin Commands Native Nushell plugins for high-performance operations. **10-50x faster than HTTP API**. ### Authentication Plugin (nu_plugin_auth) ```bash # Login (password prompted securely) auth login admin # Login with custom URL auth login admin --url https://control-center.example.com # Verify current session auth verify # Returns: { active: true, user: "admin", role: "Admin", expires_at: "...", mfa_verified: true } # List active sessions auth sessions # Logout auth logout # MFA enrollment auth mfa enroll totp # TOTP (Google Authenticator, Authy) auth mfa enroll webauthn # WebAuthn (YubiKey, Touch ID, Windows Hello) # MFA verification auth mfa verify --code 123456 auth mfa verify --code ABCD-EFGH-IJKL # Backup code ``` **Installation:** ```bash cd provisioning/core/plugins/nushell-plugins cargo build --release -p nu_plugin_auth plugin add target/release/nu_plugin_auth ``` ### KMS Plugin (nu_plugin_kms) **Performance**: 10x faster encryption (~5 ms vs ~50 ms HTTP) ```bash # Encrypt with auto-detected backend kms encrypt "secret data" # vault:v1:abc123... # Encrypt with specific backend kms encrypt "data" --backend rustyvault --key provisioning-main kms encrypt "data" --backend age --key age1xxxxxxxxx kms encrypt "data" --backend aws --key alias/provisioning # Encrypt with context (AAD for additional security) kms encrypt "data" --context "user=admin,env=production" # Decrypt (auto-detects backend from format) kms decrypt "vault:v1:abc123..." kms decrypt "-----BEGIN AGE ENCRYPTED FILE-----..." # Decrypt with context (must match encryption context) kms decrypt "vault:v1:abc123..." --context "user=admin,env=production" # Generate data encryption key kms generate-key kms generate-key --spec AES256 # Check backend status kms status ``` **Supported Backends:** - **rustyvault**: High-performance (~5 ms) - Production - **age**: Local encryption (~3 ms) - Development - **cosmian**: Cloud KMS (~30 ms) - **aws**: AWS KMS (~50 ms) - **vault**: HashiCorp Vault (~40 ms) **Installation:** ```bash cargo build --release -p nu_plugin_kms plugin add target/release/nu_plugin_kms # Set backend environment export RUSTYVAULT_ADDR="http://localhost:8200" export RUSTYVAULT_TOKEN="hvs.xxxxx" ``` ### Orchestrator Plugin (nu_plugin_orchestrator) **Performance**: 30-50x faster queries (~1 ms vs ~30-50 ms HTTP) ```bash # Get orchestrator status (direct file access, ~1 ms) orch status # { active_tasks: 5, completed_tasks: 120, health: "healthy" } # Validate workflow KCL file (~10 ms vs ~100 ms HTTP) orch validate workflows/deploy.ncl orch validate workflows/deploy.ncl --strict # List tasks (direct file read, ~5 ms) orch tasks orch tasks --status running orch tasks --status failed --limit 10 ``` **Installation:** ```bash cargo build --release -p nu_plugin_orchestrator plugin add target/release/nu_plugin_orchestrator ``` ### Plugin Performance Comparison | Operation | HTTP API | Plugin | Speedup | |-----------|----------|--------|---------| | KMS Encrypt | ~50 ms | ~5 ms | **10x** | | KMS Decrypt | ~50 ms | ~5 ms | **10x** | | Orch Status | ~30 ms | ~1 ms | **30x** | | Orch Validate | ~100 ms | ~10 ms | **10x** | | Orch Tasks | ~50 ms | ~5 ms | **10x** | | Auth Verify | ~50 ms | ~10 ms | **5x** | --- ## CLI Shortcuts ### Infrastructure Shortcuts ```bash # Server shortcuts provisioning s # server (same as 'provisioning server') provisioning s create # Create servers provisioning s delete # Delete servers provisioning s list # List servers provisioning s ssh web-01 # SSH into server # Taskserv shortcuts provisioning t # taskserv (same as 'provisioning taskserv') provisioning task # taskserv (alias) provisioning t create kubernetes provisioning t delete kubernetes provisioning t list provisioning t generate kubernetes provisioning t check-updates # Cluster shortcuts provisioning cl # cluster (same as 'provisioning cluster') provisioning cl create buildkit provisioning cl delete buildkit provisioning cl list # Infrastructure shortcuts provisioning i # infra (same as 'provisioning infra') provisioning infras # infra (alias) provisioning i list provisioning i validate ``` ### Orchestration Shortcuts ```bash # Workflow shortcuts provisioning wf # workflow (same as 'provisioning workflow') provisioning flow # workflow (alias) provisioning wf list provisioning wf status provisioning wf monitor provisioning wf stats provisioning wf cleanup # Batch shortcuts provisioning bat # batch (same as 'provisioning batch') provisioning batch submit workflows/example.ncl provisioning bat list provisioning bat status provisioning bat monitor provisioning bat rollback provisioning bat cancel provisioning bat stats # Orchestrator shortcuts provisioning orch # orchestrator (same as 'provisioning orchestrator') provisioning orch start provisioning orch stop provisioning orch status provisioning orch health provisioning orch logs ``` ### Development Shortcuts ```bash # Module shortcuts provisioning mod # module (same as 'provisioning module') provisioning mod discover taskserv provisioning mod discover provider provisioning mod discover cluster provisioning mod load taskserv workspace kubernetes provisioning mod list taskserv workspace provisioning mod unload taskserv workspace kubernetes provisioning mod sync-kcl # Layer shortcuts provisioning lyr # layer (same as 'provisioning layer') provisioning lyr explain provisioning lyr show provisioning lyr test provisioning lyr stats # Version shortcuts provisioning version check provisioning version show provisioning version updates provisioning version apply provisioning version taskserv # Package shortcuts provisioning pack core provisioning pack provider upcloud provisioning pack list provisioning pack clean ``` ### Workspace Shortcuts ```bash # Workspace shortcuts provisioning ws # workspace (same as 'provisioning workspace') provisioning ws init provisioning ws create provisioning ws validate provisioning ws info provisioning ws list provisioning ws migrate provisioning ws switch # Switch active workspace provisioning ws active # Show active workspace # Template shortcuts provisioning tpl # template (same as 'provisioning template') provisioning tmpl # template (alias) provisioning tpl list provisioning tpl types provisioning tpl show provisioning tpl apply provisioning tpl validate ``` ### Configuration Shortcuts ```bash # Environment shortcuts provisioning e # env (same as 'provisioning env') provisioning val # validate (same as 'provisioning validate') provisioning st # setup (same as 'provisioning setup') provisioning config # setup (alias) # Show shortcuts provisioning show settings provisioning show servers provisioning show config # Initialization provisioning init # All environment provisioning allenv # Show all config and environment ``` ### Utility Shortcuts ```bash # List shortcuts provisioning l # list (same as 'provisioning list') provisioning ls # list (alias) provisioning list # list (full) # SSH operations provisioning ssh # SOPS operations provisioning sops # Edit encrypted file # Cache management provisioning cache clear provisioning cache stats # Provider operations provisioning providers list provisioning providers info # Nushell session provisioning nu # Start Nushell with provisioning library loaded # QR code generation provisioning qr # Nushell information provisioning nuinfo # Plugin management provisioning plugin # plugin (same as 'provisioning plugin') provisioning plugins # plugin (alias) provisioning plugin list provisioning plugin test nu_plugin_kms ``` ### Generation Shortcuts ```bash # Generate shortcuts provisioning g # generate (same as 'provisioning generate') provisioning gen # generate (alias) provisioning g server provisioning g taskserv provisioning g cluster provisioning g infra --new provisioning g new ``` ### Action Shortcuts ```bash # Common actions provisioning c # create (same as 'provisioning create') provisioning d # delete (same as 'provisioning delete') provisioning u # update (same as 'provisioning update') # Pricing shortcuts provisioning price # Show server pricing provisioning cost # price (alias) provisioning costs # price (alias) # Create server + taskservs (combo command) provisioning cst # create-server-task provisioning csts # create-server-task (alias) ``` --- ## Infrastructure Commands ### Server Management ```bash # Create servers provisioning server create provisioning server create --check # Dry-run mode provisioning server create --yes # Skip confirmation # Delete servers provisioning server delete provisioning server delete --check provisioning server delete --yes # List servers provisioning server list provisioning server list --infra wuji provisioning server list --out json # SSH into server provisioning server ssh web-01 provisioning server ssh db-01 # Show pricing provisioning server price provisioning server price --provider upcloud ``` ### Taskserv Management ```bash # Create taskserv provisioning taskserv create kubernetes provisioning taskserv create kubernetes --check provisioning taskserv create kubernetes --infra wuji # Delete taskserv provisioning taskserv delete kubernetes provisioning taskserv delete kubernetes --check # List taskservs provisioning taskserv list provisioning taskserv list --infra wuji # Generate taskserv configuration provisioning taskserv generate kubernetes provisioning taskserv generate kubernetes --out yaml # Check for updates provisioning taskserv check-updates provisioning taskserv check-updates --taskserv kubernetes ``` ### Cluster Management ```bash # Create cluster provisioning cluster create buildkit provisioning cluster create buildkit --check provisioning cluster create buildkit --infra wuji # Delete cluster provisioning cluster delete buildkit provisioning cluster delete buildkit --check # List clusters provisioning cluster list provisioning cluster list --infra wuji ``` --- ## Orchestration Commands ### Workflow Management ```bash # Submit server creation workflow nu -c "use core/nulib/workflows/server_create.nu *; server_create_workflow 'wuji' '' [] --check" # Submit taskserv workflow nu -c "use core/nulib/workflows/taskserv.nu *; taskserv create 'kubernetes' 'wuji' --check" # Submit cluster workflow nu -c "use core/nulib/workflows/cluster.nu *; cluster create 'buildkit' 'wuji' --check" # List all workflows provisioning workflow list nu -c "use core/nulib/workflows/management.nu *; workflow list" # Get workflow statistics provisioning workflow stats nu -c "use core/nulib/workflows/management.nu *; workflow stats" # Monitor workflow in real-time provisioning workflow monitor nu -c "use core/nulib/workflows/management.nu *; workflow monitor " # Check orchestrator health provisioning workflow orchestrator nu -c "use core/nulib/workflows/management.nu *; workflow orchestrator" # Get specific workflow status provisioning workflow status nu -c "use core/nulib/workflows/management.nu *; workflow status " ``` ### Batch Operations ```bash # Submit batch workflow from KCL provisioning batch submit workflows/example_batch.ncl nu -c "use core/nulib/workflows/batch.nu *; batch submit workflows/example_batch.ncl" # Monitor batch workflow progress provisioning batch monitor nu -c "use core/nulib/workflows/batch.nu *; batch monitor " # List batch workflows with filtering provisioning batch list provisioning batch list --status Running nu -c "use core/nulib/workflows/batch.nu *; batch list --status Running" # Get detailed batch status provisioning batch status nu -c "use core/nulib/workflows/batch.nu *; batch status " # Initiate rollback for failed workflow provisioning batch rollback nu -c "use core/nulib/workflows/batch.nu *; batch rollback " # Cancel running batch provisioning batch cancel # Show batch workflow statistics provisioning batch stats nu -c "use core/nulib/workflows/batch.nu *; batch stats" ``` ### Orchestrator Management ```bash # Start orchestrator in background cd provisioning/platform/orchestrator ./scripts/start-orchestrator.nu --background # Check orchestrator status ./scripts/start-orchestrator.nu --check provisioning orchestrator status # Stop orchestrator ./scripts/start-orchestrator.nu --stop provisioning orchestrator stop # View logs tail -f provisioning/platform/orchestrator/data/orchestrator.log provisioning orchestrator logs ``` --- ## Configuration Commands ### Environment and Validation ```bash # Show environment variables provisioning env # Show all environment and configuration provisioning allenv # Validate configuration provisioning validate config provisioning validate infra # Setup wizard provisioning setup ``` ### Configuration Files ```bash # System defaults less provisioning/config/config.defaults.toml # User configuration vim workspace/config/local-overrides.toml # Environment-specific configs vim workspace/config/dev-defaults.toml vim workspace/config/test-defaults.toml vim workspace/config/prod-defaults.toml # Infrastructure-specific config vim workspace/infra//config.toml ``` ### HTTP Configuration ```bash # Configure HTTP client behavior # In workspace/config/local-overrides.toml: [http] use_curl = true # Use curl instead of ureq ``` --- ## Workspace Commands ### Workspace Management ```bash # List all workspaces provisioning workspace list # Show active workspace provisioning workspace active # Switch to another workspace provisioning workspace switch provisioning workspace activate # alias # Register new workspace provisioning workspace register provisioning workspace register --activate # Remove workspace from registry provisioning workspace remove provisioning workspace remove --force # Initialize new workspace provisioning workspace init provisioning workspace init --name production # Create new workspace provisioning workspace create # Validate workspace provisioning workspace validate # Show workspace info provisioning workspace info # Migrate workspace provisioning workspace migrate ``` ### User Preferences ```bash # View user preferences provisioning workspace preferences # Set user preference provisioning workspace set-preference editor vim provisioning workspace set-preference output_format yaml provisioning workspace set-preference confirm_delete true # Get user preference provisioning workspace get-preference editor ``` **User Config Location:** - macOS: `~/Library/Application Support/provisioning/user_config.yaml` - Linux: `~/.config/provisioning/user_config.yaml` - Windows: `%APPDATA%\provisioning\user_config.yaml` --- ## Security Commands ### Authentication (via CLI) ```bash # Login provisioning login admin # Logout provisioning logout # Show session status provisioning auth status # List active sessions provisioning auth sessions ``` ### Multi-Factor Authentication (MFA) ```bash # Enroll in TOTP (Google Authenticator, Authy) provisioning mfa totp enroll # Enroll in WebAuthn (YubiKey, Touch ID, Windows Hello) provisioning mfa webauthn enroll # Verify MFA code provisioning mfa totp verify --code 123456 provisioning mfa webauthn verify # List registered devices provisioning mfa devices ``` ### Secrets Management ```bash # Generate AWS STS credentials (15 min-12h TTL) provisioning secrets generate aws --ttl 1hr # Generate SSH key pair (Ed25519) provisioning secrets generate ssh --ttl 4hr # List active secrets provisioning secrets list # Revoke secret provisioning secrets revoke # Cleanup expired secrets provisioning secrets cleanup ``` ### SSH Temporal Keys ```bash # Connect to server with temporal key provisioning ssh connect server01 --ttl 1hr # Generate SSH key pair only provisioning ssh generate --ttl 4hr # List active SSH keys provisioning ssh list # Revoke SSH key provisioning ssh revoke ``` ### KMS Operations (via CLI) ```bash # Encrypt configuration file provisioning kms encrypt secure.yaml # Decrypt configuration file provisioning kms decrypt secure.yaml.enc # Encrypt entire config directory provisioning config encrypt workspace/infra/production/ # Decrypt config directory provisioning config decrypt workspace/infra/production/ ``` ### Break-Glass Emergency Access ```bash # Request emergency access provisioning break-glass request "Production database outage" # Approve emergency request (requires admin) provisioning break-glass approve --reason "Approved by CTO" # List break-glass sessions provisioning break-glass list # Revoke break-glass session provisioning break-glass revoke ``` ### Compliance and Audit ```bash # Generate compliance report provisioning compliance report provisioning compliance report --standard gdpr provisioning compliance report --standard soc2 provisioning compliance report --standard iso27001 # GDPR operations provisioning compliance gdpr export provisioning compliance gdpr delete provisioning compliance gdpr rectify # Incident management provisioning compliance incident create "Security breach detected" provisioning compliance incident list provisioning compliance incident update --status investigating # Audit log queries provisioning audit query --user alice --action deploy --from 24h provisioning audit export --format json --output audit-logs.json ``` --- ## Common Workflows ### Complete Deployment from Scratch ```bash # 1. Initialize workspace provisioning workspace init --name production # 2. Validate configuration provisioning validate config # 3. Create infrastructure definition provisioning generate infra --new production # 4. Create servers (check mode first) provisioning server create --infra production --check # 5. Create servers (actual deployment) provisioning server create --infra production --yes # 6. Install Kubernetes provisioning taskserv create kubernetes --infra production --check provisioning taskserv create kubernetes --infra production # 7. Deploy cluster services provisioning cluster create production --check provisioning cluster create production # 8. Verify deployment provisioning server list --infra production provisioning taskserv list --infra production # 9. SSH to servers provisioning server ssh k8s-master-01 ``` ### Multi-Environment Deployment ```bash # Deploy to dev provisioning server create --infra dev --check provisioning server create --infra dev provisioning taskserv create kubernetes --infra dev # Deploy to staging provisioning server create --infra staging --check provisioning server create --infra staging provisioning taskserv create kubernetes --infra staging # Deploy to production (with confirmation) provisioning server create --infra production --check provisioning server create --infra production provisioning taskserv create kubernetes --infra production ``` ### Update Infrastructure ```bash # 1. Check for updates provisioning taskserv check-updates # 2. Update specific taskserv (check mode) provisioning taskserv update kubernetes --check # 3. Apply update provisioning taskserv update kubernetes # 4. Verify update provisioning taskserv list --infra production | where name == kubernetes ``` ### Encrypted Secrets Deployment ```bash # 1. Authenticate auth login admin auth mfa verify --code 123456 # 2. Encrypt secrets kms encrypt (open secrets/production.yaml) --backend rustyvault | save secrets/production.enc # 3. Deploy with encrypted secrets provisioning cluster create production --secrets secrets/production.enc # 4. Verify deployment orch tasks --status completed ``` --- ## Debug and Check Mode ### Debug Mode Enable verbose logging with `--debug` or `-x` flag: ```bash # Server creation with debug output provisioning server create --debug provisioning server create -x # Taskserv creation with debug provisioning taskserv create kubernetes --debug # Show detailed error traces provisioning --debug taskserv create kubernetes ``` ### Check Mode (Dry Run) Preview changes without applying them with `--check` or `-c` flag: ```bash # Check what servers would be created provisioning server create --check provisioning server create -c # Check taskserv installation provisioning taskserv create kubernetes --check # Check cluster creation provisioning cluster create buildkit --check # Combine with debug for detailed preview provisioning server create --check --debug ``` ### Auto-Confirm Mode Skip confirmation prompts with `--yes` or `-y` flag: ```bash # Auto-confirm server creation provisioning server create --yes provisioning server create -y # Auto-confirm deletion provisioning server delete --yes ``` ### Wait Mode Wait for operations to complete with `--wait` or `-w` flag: ```bash # Wait for server creation to complete provisioning server create --wait # Wait for taskserv installation provisioning taskserv create kubernetes --wait ``` ### Infrastructure Selection Specify target infrastructure with `--infra` or `-i` flag: ```bash # Create servers in specific infrastructure provisioning server create --infra production provisioning server create -i production # List servers in specific infrastructure provisioning server list --infra production ``` --- ## Output Formats ### JSON Output ```bash # Output as JSON provisioning server list --out json provisioning taskserv list --out json # Pipeline JSON output provisioning server list --out json | jq '.[] | select(.status == "running")' ``` ### YAML Output ```bash # Output as YAML provisioning server list --out yaml provisioning taskserv list --out yaml # Pipeline YAML output provisioning server list --out yaml | yq '.[] | select(.status == "running")' ``` ### Table Output (Default) ```bash # Output as table (default) provisioning server list provisioning server list --out table # Pretty-printed table provisioning server list | table ``` ### Text Output ```bash # Output as plain text provisioning server list --out text ``` --- ## Performance Tips ### Use Plugins for Frequent Operations ```bash # ❌ Slow: HTTP API (50 ms per call) for i in 1..100 { http post http://localhost:9998/encrypt { data: "secret" } } # ✅ Fast: Plugin (5 ms per call, 10x faster) for i in 1..100 { kms encrypt "secret" } ``` ### Batch Operations ```bash # Use batch workflows for multiple operations provisioning batch submit workflows/multi-cloud-deploy.ncl ``` ### Check Mode for Testing ```bash # Always test with --check first provisioning server create --check provisioning server create # Only after verification ``` --- ## Help System ### Command-Specific Help ```bash # Show help for specific command provisioning help server provisioning help taskserv provisioning help cluster provisioning help workflow provisioning help batch # Show help for command category provisioning help infra provisioning help orch provisioning help dev provisioning help ws provisioning help config ``` ### Bi-Directional Help ```bash # All these work identically: provisioning help workspace provisioning workspace help provisioning ws help provisioning help ws ``` ### General Help ```bash # Show all commands provisioning help provisioning --help # Show version provisioning version provisioning --version ``` --- ## Quick Reference: Common Flags | Flag | Short | Description | Example | |------|-------|-------------|---------| | `--debug` | `-x` | Enable debug mode | `provisioning server create --debug` | | `--check` | `-c` | Check mode (dry run) | `provisioning server create --check` | | `--yes` | `-y` | Auto-confirm | `provisioning server delete --yes` | | `--wait` | `-w` | Wait for completion | `provisioning server create --wait` | | `--infra` | `-i` | Specify infrastructure | `provisioning server list --infra prod` | | `--out` | - | Output format | `provisioning server list --out json` | --- ## Plugin Installation Quick Reference ```bash # Build all plugins (one-time setup) cd provisioning/core/plugins/nushell-plugins cargo build --release --all # Register plugins plugin add target/release/nu_plugin_auth plugin add target/release/nu_plugin_kms plugin add target/release/nu_plugin_orchestrator # Verify installation plugin list | where name =~ "auth|kms|orch" auth --help kms --help orch --help # Set environment export RUSTYVAULT_ADDR="http://localhost:8200" export RUSTYVAULT_TOKEN="hvs.xxxxx" export CONTROL_CENTER_URL="http://localhost:3000" ``` --- ## Related Documentation - **Complete Plugin Guide**: `docs/user/PLUGIN_INTEGRATION_GUIDE.md` - **Plugin Reference**: `docs/user/NUSHELL_PLUGINS_GUIDE.md` - **From Scratch Guide**: `docs/guides/from-scratch.md` - **Update Infrastructure**: [Update Guide](../guides/update-infrastructure.md) - **Customize Infrastructure**: [Customize Guide](../guides/customize-infrastructure.md) - **CLI Architecture**: [CLI Reference](../infrastructure/cli-reference.md) - **Security System**: [Security Architecture](../security/security-system.md) --- **For fastest access to this guide**: `provisioning sc` **Last Updated**: 2025-10-09 **Maintained By**: Platform Team