# Mode System Quick Reference\n\n**Version**: 1.0.0 | **Date**: 2025-10-06\n\n---\n\n## Quick Start\n\n```\n# Check current mode\nprovisioning mode current\n\n# List all available modes\nprovisioning mode list\n\n# Switch to a different mode\nprovisioning mode switch <mode-name>\n\n# Validate mode configuration\nprovisioning mode validate\n```\n\n---\n\n## Available Modes\n\n| Mode | Use Case | Auth | Orchestrator | OCI Registry |\n| ------ | ---------- | ------ | -------------- | -------------- |\n| **solo** | Local development | None | Local binary | Local Zot (optional) |\n| **multi-user** | Team collaboration | Token (JWT) | Remote | Remote Harbor |\n| **cicd** | CI/CD pipelines | Token (CI injected) | Remote | Remote Harbor |\n| **enterprise** | Production | mTLS | Kubernetes HA | Harbor HA + DR |\n\n---\n\n## Mode Comparison\n\n### Solo Mode\n\n- ✅ **Best for**: Individual developers\n- 🔐 **Authentication**: None\n- 🚀 **Services**: Local orchestrator only\n- 📦 **Extensions**: Local filesystem\n- 🔒 **Workspace Locking**: Disabled\n- 💾 **Resource Limits**: Unlimited\n\n### Multi-User Mode\n\n- ✅ **Best for**: Development teams (5-20 developers)\n- 🔐 **Authentication**: Token (JWT, 24h expiry)\n- 🚀 **Services**: Remote orchestrator, control-center, DNS, git\n- 📦 **Extensions**: OCI registry (Harbor)\n- 🔒 **Workspace Locking**: Enabled (Gitea provider)\n- 💾 **Resource Limits**: 10 servers, 32 cores, 128 GB per user\n\n### CI/CD Mode\n\n- ✅ **Best for**: Automated pipelines\n- 🔐 **Authentication**: Token (1h expiry, CI/CD injected)\n- 🚀 **Services**: Remote orchestrator, DNS, git\n- 📦 **Extensions**: OCI registry (always pull latest)\n- 🔒 **Workspace Locking**: Disabled (stateless)\n- 💾 **Resource Limits**: 5 servers, 16 cores, 64 GB per pipeline\n\n### Enterprise Mode\n\n- ✅ **Best for**: Large enterprises with strict compliance\n- 🔐 **Authentication**: mTLS (TLS 1.3)\n- 🚀 **Services**: All services on Kubernetes (HA)\n- 📦 **Extensions**: OCI registry (signature verification)\n- 🔒 **Workspace Locking**: Required (etcd provider)\n- 💾 **Resource Limits**: 20 servers, 64 cores, 256 GB per user\n\n---\n\n## Common Operations\n\n### Initialize Mode System\n\n```\nprovisioning mode init\n```\n\n### Check Current Mode\n\n```\nprovisioning mode current\n\n# Output:\n# mode: solo\n# configured: true\n# config_file: ~/.provisioning/config/active-mode.yaml\n```\n\n### List All Modes\n\n```\nprovisioning mode list\n\n# Output:\n# ┌───────────────┬───────────────────────────────────┬─────────┐\n# │ mode          │ description                        │ current │\n# ├───────────────┼───────────────────────────────────┼─────────┤\n# │ solo          │ Single developer local development │ ●       │\n# │ multi-user    │ Team collaboration                 │         │\n# │ cicd          │ CI/CD pipeline execution           │         │\n# │ enterprise    │ Production enterprise deployment   │         │\n# └───────────────┴───────────────────────────────────┴─────────┘\n```\n\n### Switch Mode\n\n```\n# Switch with confirmation\nprovisioning mode switch multi-user\n\n# Dry run (preview changes)\nprovisioning mode switch multi-user --dry-run\n\n# With validation\nprovisioning mode switch multi-user --validate\n```\n\n### Show Mode Details\n\n```\n# Show current mode\nprovisioning mode show\n\n# Show specific mode\nprovisioning mode show enterprise\n```\n\n### Validate Mode\n\n```\n# Validate current mode\nprovisioning mode validate\n\n# Validate specific mode\nprovisioning mode validate cicd\n```\n\n### Compare Modes\n\n```\nprovisioning mode compare solo multi-user\n\n# Output shows differences in:\n# - Authentication\n# - Service deployments\n# - Extension sources\n# - Workspace locking\n# - Security settings\n```\n\n---\n\n## OCI Registry Management\n\n### Solo Mode Only\n\n```\n# Start local OCI registry\nprovisioning mode oci-registry start\n\n# Check registry status\nprovisioning mode oci-registry status\n\n# View registry logs\nprovisioning mode oci-registry logs\n\n# Stop registry\nprovisioning mode oci-registry stop\n```\n\n**Note**: OCI registry management only works in solo mode with local deployment.\n\n---\n\n## Mode-Specific Workflows\n\n### Solo Mode Workflow\n\n```\n# 1. Initialize (defaults to solo)\nprovisioning workspace init\n\n# 2. Start orchestrator\ncd provisioning/platform/orchestrator\n./scripts/start-orchestrator.nu --background\n\n# 3. (Optional) Start OCI registry\nprovisioning mode oci-registry start\n\n# 4. Create infrastructure\nprovisioning server create web-01 --check\nprovisioning taskserv create kubernetes\n\n# Extensions loaded from local filesystem\n```\n\n### Multi-User Mode Workflow\n\n```\n# 1. Switch to multi-user mode\nprovisioning mode switch multi-user\n\n# 2. Authenticate\nprovisioning auth login\n# Enter JWT token from team admin\n\n# 3. Lock workspace\nprovisioning workspace lock my-infra\n\n# 4. Pull extensions from OCI registry\nprovisioning extension pull upcloud\nprovisioning extension pull kubernetes\n\n# 5. Create infrastructure\nprovisioning server create web-01\n\n# 6. Unlock workspace\nprovisioning workspace unlock my-infra\n```\n\n### CI/CD Mode Workflow\n\n```\n# GitLab CI example\ndeploy:\n  stage: deploy\n  script:\n    # Token injected by CI\n    - export PROVISIONING_MODE=cicd\n    - mkdir -p /var/run/secrets/provisioning\n    - echo "$PROVISIONING_TOKEN" > /var/run/secrets/provisioning/token\n\n    # Validate\n    - provisioning validate --all\n\n    # Test\n    - provisioning test quick kubernetes\n\n    # Deploy\n    - provisioning server create --check\n    - provisioning server create\n\n  after_script:\n    - provisioning workspace cleanup\n```\n\n### Enterprise Mode Workflow\n\n```\n# 1. Switch to enterprise mode\nprovisioning mode switch enterprise\n\n# 2. Verify Kubernetes connectivity\nkubectl get pods -n provisioning-system\n\n# 3. Login to Harbor\ndocker login harbor.enterprise.local\n\n# 4. Request workspace (requires approval)\nprovisioning workspace request prod-deployment\n# Approval from: platform-team, security-team\n\n# 5. After approval, lock workspace\nprovisioning workspace lock prod-deployment --provider etcd\n\n# 6. Pull extensions (with signature verification)\nprovisioning extension pull upcloud --verify-signature\n\n# 7. Deploy infrastructure\nprovisioning infra create --check\nprovisioning infra create\n\n# 8. Release workspace\nprovisioning workspace unlock prod-deployment\n```\n\n---\n\n## Configuration Files\n\n### Mode Templates\n\n```\nworkspace/config/modes/\n├── solo.yaml           # Solo mode configuration\n├── multi-user.yaml     # Multi-user mode configuration\n├── cicd.yaml           # CI/CD mode configuration\n└── enterprise.yaml     # Enterprise mode configuration\n```\n\n### Active Mode Configuration\n\n```\n~/.provisioning/config/active-mode.yaml\n```\n\nThis file is created/updated when you switch modes.\n\n---\n\n## OCI Registry Namespaces\n\nAll modes use the following OCI registry namespaces:\n\n| Namespace | Purpose | Example |\n| ----------- | --------- | --------- |\n| `*-extensions` | Extension artifacts | `provisioning-extensions/upcloud:latest` |\n| `*-schemas` | Nickel schema artifacts | `provisioning-schemas/lib:v1.0.0` |\n| `*-platform` | Platform service images | `provisioning-platform/orchestrator:latest` |\n| `*-test` | Test environment images | `provisioning-test/ubuntu:22.04` |\n\n**Note**: Prefix varies by mode (`dev-`, `provisioning-`, `cicd-`, `prod-`)\n\n---\n\n## Troubleshooting\n\n### Mode switch fails\n\n```\n# Validate mode first\nprovisioning mode validate <mode-name>\n\n# Check runtime requirements\nprovisioning mode validate <mode-name> --check-requirements\n```\n\n### Cannot start OCI registry (solo mode)\n\n```\n# Check if registry binary is installed\nwhich zot\n\n# Install Zot\n# macOS: brew install project-zot/tap/zot\n# Linux: Download from https://github.com/project-zot/zot/releases\n\n# Check if port 5000 is available\nlsof -i :5000\n```\n\n### Authentication fails (multi-user/cicd/enterprise)\n\n```\n# Check token expiry\nprovisioning auth status\n\n# Re-authenticate\nprovisioning auth login\n\n# For enterprise mTLS, verify certificates\nls -la /etc/provisioning/certs/\n# Should contain: client.crt, client.key, ca.crt\n```\n\n### Workspace locking issues (multi-user/enterprise)\n\n```\n# Check lock status\nprovisioning workspace lock-status <workspace-name>\n\n# Force unlock (use with caution)\nprovisioning workspace unlock <workspace-name> --force\n\n# Check lock provider status\n# Multi-user: Check Gitea connectivity\ncurl -I https://git.company.local\n\n# Enterprise: Check etcd cluster\netcdctl endpoint health\n```\n\n### OCI registry connection fails\n\n```\n# Test registry connectivity\ncurl https://harbor.company.local/v2/\n\n# Check authentication token\ncat ~/.provisioning/tokens/oci\n\n# Verify network connectivity\nping harbor.company.local\n\n# For Harbor, check credentials\ndocker login harbor.company.local\n```\n\n---\n\n## Environment Variables\n\n| Variable | Purpose | Example |\n| ---------- | --------- | --------- |\n| `PROVISIONING_MODE` | Override active mode | `export PROVISIONING_MODE=cicd` |\n| `PROVISIONING_WORKSPACE_CONFIG` | Override config location | `~/.provisioning/config` |\n| `PROVISIONING_PROJECT_ROOT` | Project root directory | `/opt/project-provisioning` |\n\n---\n\n## Best Practices\n\n### 1. Use Appropriate Mode\n\n- **Solo**: Individual development, experimentation\n- **Multi-User**: Team collaboration, shared infrastructure\n- **CI/CD**: Automated testing and deployment\n- **Enterprise**: Production deployments, compliance requirements\n\n### 2. Validate Before Switching\n\n```\nprovisioning mode validate <mode-name>\n```\n\n### 3. Backup Active Configuration\n\n```\n# Automatic backup created when switching\nls ~/.provisioning/config/active-mode.yaml.backup\n```\n\n### 4. Use Check Mode\n\n```\nprovisioning server create --check\n```\n\n### 5. Lock Workspaces in Multi-User/Enterprise\n\n```\nprovisioning workspace lock <workspace-name>\n# ... make changes ...\nprovisioning workspace unlock <workspace-name>\n```\n\n### 6. Pull Extensions from OCI (Multi-User/CI/CD/Enterprise)\n\n```\n# Don't use local extensions in shared modes\nprovisioning extension pull <extension-name>\n```\n\n---\n\n## Security Considerations\n\n### Solo Mode\n\n- ⚠️ No authentication (local development only)\n- ⚠️ No encryption (sensitive data should use SOPS)\n- ✅ Isolated environment\n\n### Multi-User Mode\n\n- ✅ Token-based authentication\n- ✅ TLS in transit\n- ✅ Audit logging\n- ⚠️ No encryption at rest (configure as needed)\n\n### CI/CD Mode\n\n- ✅ Token authentication (short expiry)\n- ✅ Full encryption (at rest + in transit)\n- ✅ KMS for secrets\n- ✅ Vulnerability scanning (critical threshold)\n- ✅ Image signing required\n\n### Enterprise Mode\n\n- ✅ mTLS authentication\n- ✅ Full encryption (at rest + in transit)\n- ✅ KMS for all secrets\n- ✅ Vulnerability scanning (critical threshold)\n- ✅ Image signing + signature verification\n- ✅ Network isolation\n- ✅ Compliance policies (SOC2, ISO27001, HIPAA)\n\n---\n\n## Support and Documentation\n\n- **Implementation Summary**: `MODE_SYSTEM_IMPLEMENTATION_SUMMARY.md`\n- **Nickel Schemas**: `provisioning/schemas/modes.ncl`, `provisioning/schemas/oci_registry.ncl`\n- **Mode Templates**: `workspace/config/modes/*.yaml`\n- **Commands**: `provisioning/core/nulib/lib_provisioning/mode/`\n\n---\n\n**Last Updated**: 2025-10-06 | **Version**: 1.0.0
