# Mode System Quick Reference

**Version**: 1.0.0 | **Date**: 2025-10-06

---

## Quick Start

```bash
# Check current mode
provisioning mode current

# List all available modes
provisioning mode list

# Switch to a different mode
provisioning mode switch <mode-name>

# Validate mode configuration
provisioning mode validate
```plaintext

---

## Available Modes

| Mode | Use Case | Auth | Orchestrator | OCI Registry |
|------|----------|------|--------------|--------------|
| **solo** | Local development | None | Local binary | Local Zot (optional) |
| **multi-user** | Team collaboration | Token (JWT) | Remote | Remote Harbor |
| **cicd** | CI/CD pipelines | Token (CI injected) | Remote | Remote Harbor |
| **enterprise** | Production | mTLS | Kubernetes HA | Harbor HA + DR |

---

## Mode Comparison

### Solo Mode

- ✅ **Best for**: Individual developers
- 🔐 **Authentication**: None
- 🚀 **Services**: Local orchestrator only
- 📦 **Extensions**: Local filesystem
- 🔒 **Workspace Locking**: Disabled
- 💾 **Resource Limits**: Unlimited

### Multi-User Mode

- ✅ **Best for**: Development teams (5-20 developers)
- 🔐 **Authentication**: Token (JWT, 24h expiry)
- 🚀 **Services**: Remote orchestrator, control-center, DNS, git
- 📦 **Extensions**: OCI registry (Harbor)
- 🔒 **Workspace Locking**: Enabled (Gitea provider)
- 💾 **Resource Limits**: 10 servers, 32 cores, 128 GB per user

### CI/CD Mode

- ✅ **Best for**: Automated pipelines
- 🔐 **Authentication**: Token (1h expiry, CI/CD injected)
- 🚀 **Services**: Remote orchestrator, DNS, git
- 📦 **Extensions**: OCI registry (always pull latest)
- 🔒 **Workspace Locking**: Disabled (stateless)
- 💾 **Resource Limits**: 5 servers, 16 cores, 64 GB per pipeline

### Enterprise Mode

- ✅ **Best for**: Large enterprises with strict compliance
- 🔐 **Authentication**: mTLS (TLS 1.3)
- 🚀 **Services**: All services on Kubernetes (HA)
- 📦 **Extensions**: OCI registry (signature verification)
- 🔒 **Workspace Locking**: Required (etcd provider)
- 💾 **Resource Limits**: 20 servers, 64 cores, 256 GB per user

---

## Common Operations

### Initialize Mode System

```bash
provisioning mode init
```plaintext

### Check Current Mode

```bash
provisioning mode current

# Output:
# mode: solo
# configured: true
# config_file: ~/.provisioning/config/active-mode.yaml
```plaintext

### List All Modes

```bash
provisioning mode list

# Output:
# ┌───────────────┬───────────────────────────────────┬─────────┐
# │ mode          │ description                        │ current │
# ├───────────────┼───────────────────────────────────┼─────────┤
# │ solo          │ Single developer local development │ ●       │
# │ multi-user    │ Team collaboration                 │         │
# │ cicd          │ CI/CD pipeline execution           │         │
# │ enterprise    │ Production enterprise deployment   │         │
# └───────────────┴───────────────────────────────────┴─────────┘
```plaintext

### Switch Mode

```bash
# Switch with confirmation
provisioning mode switch multi-user

# Dry run (preview changes)
provisioning mode switch multi-user --dry-run

# With validation
provisioning mode switch multi-user --validate
```plaintext

### Show Mode Details

```bash
# Show current mode
provisioning mode show

# Show specific mode
provisioning mode show enterprise
```plaintext

### Validate Mode

```bash
# Validate current mode
provisioning mode validate

# Validate specific mode
provisioning mode validate cicd
```plaintext

### Compare Modes

```bash
provisioning mode compare solo multi-user

# Output shows differences in:
# - Authentication
# - Service deployments
# - Extension sources
# - Workspace locking
# - Security settings
```plaintext

---

## OCI Registry Management

### Solo Mode Only

```bash
# Start local OCI registry
provisioning mode oci-registry start

# Check registry status
provisioning mode oci-registry status

# View registry logs
provisioning mode oci-registry logs

# Stop registry
provisioning mode oci-registry stop
```plaintext

**Note**: OCI registry management only works in solo mode with local deployment.

---

## Mode-Specific Workflows

### Solo Mode Workflow

```bash
# 1. Initialize (defaults to solo)
provisioning workspace init

# 2. Start orchestrator
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background

# 3. (Optional) Start OCI registry
provisioning mode oci-registry start

# 4. Create infrastructure
provisioning server create web-01 --check
provisioning taskserv create kubernetes

# Extensions loaded from local filesystem
```plaintext

### Multi-User Mode Workflow

```bash
# 1. Switch to multi-user mode
provisioning mode switch multi-user

# 2. Authenticate
provisioning auth login
# Enter JWT token from team admin

# 3. Lock workspace
provisioning workspace lock my-infra

# 4. Pull extensions from OCI registry
provisioning extension pull upcloud
provisioning extension pull kubernetes

# 5. Create infrastructure
provisioning server create web-01

# 6. Unlock workspace
provisioning workspace unlock my-infra
```plaintext

### CI/CD Mode Workflow

```yaml
# GitLab CI example
deploy:
  stage: deploy
  script:
    # Token injected by CI
    - export PROVISIONING_MODE=cicd
    - mkdir -p /var/run/secrets/provisioning
    - echo "$PROVISIONING_TOKEN" > /var/run/secrets/provisioning/token

    # Validate
    - provisioning validate --all

    # Test
    - provisioning test quick kubernetes

    # Deploy
    - provisioning server create --check
    - provisioning server create

  after_script:
    - provisioning workspace cleanup
```plaintext

### Enterprise Mode Workflow

```bash
# 1. Switch to enterprise mode
provisioning mode switch enterprise

# 2. Verify Kubernetes connectivity
kubectl get pods -n provisioning-system

# 3. Login to Harbor
docker login harbor.enterprise.local

# 4. Request workspace (requires approval)
provisioning workspace request prod-deployment
# Approval from: platform-team, security-team

# 5. After approval, lock workspace
provisioning workspace lock prod-deployment --provider etcd

# 6. Pull extensions (with signature verification)
provisioning extension pull upcloud --verify-signature

# 7. Deploy infrastructure
provisioning infra create --check
provisioning infra create

# 8. Release workspace
provisioning workspace unlock prod-deployment
```plaintext

---

## Configuration Files

### Mode Templates

```plaintext
workspace/config/modes/
├── solo.yaml           # Solo mode configuration
├── multi-user.yaml     # Multi-user mode configuration
├── cicd.yaml           # CI/CD mode configuration
└── enterprise.yaml     # Enterprise mode configuration
```plaintext

### Active Mode Configuration

```plaintext
~/.provisioning/config/active-mode.yaml
```plaintext

This file is created/updated when you switch modes.

---

## OCI Registry Namespaces

All modes use the following OCI registry namespaces:

| Namespace | Purpose | Example |
|-----------|---------|---------|
| `*-extensions` | Extension artifacts | `provisioning-extensions/upcloud:latest` |
| `*-schemas` | Nickel schema artifacts | `provisioning-schemas/lib:v1.0.0` |
| `*-platform` | Platform service images | `provisioning-platform/orchestrator:latest` |
| `*-test` | Test environment images | `provisioning-test/ubuntu:22.04` |

**Note**: Prefix varies by mode (`dev-`, `provisioning-`, `cicd-`, `prod-`)

---

## Troubleshooting

### Mode switch fails

```bash
# Validate mode first
provisioning mode validate <mode-name>

# Check runtime requirements
provisioning mode validate <mode-name> --check-requirements
```plaintext

### Cannot start OCI registry (solo mode)

```bash
# Check if registry binary is installed
which zot

# Install Zot
# macOS: brew install project-zot/tap/zot
# Linux: Download from https://github.com/project-zot/zot/releases

# Check if port 5000 is available
lsof -i :5000
```plaintext

### Authentication fails (multi-user/cicd/enterprise)

```bash
# Check token expiry
provisioning auth status

# Re-authenticate
provisioning auth login

# For enterprise mTLS, verify certificates
ls -la /etc/provisioning/certs/
# Should contain: client.crt, client.key, ca.crt
```plaintext

### Workspace locking issues (multi-user/enterprise)

```bash
# Check lock status
provisioning workspace lock-status <workspace-name>

# Force unlock (use with caution)
provisioning workspace unlock <workspace-name> --force

# Check lock provider status
# Multi-user: Check Gitea connectivity
curl -I https://git.company.local

# Enterprise: Check etcd cluster
etcdctl endpoint health
```plaintext

### OCI registry connection fails

```bash
# Test registry connectivity
curl https://harbor.company.local/v2/

# Check authentication token
cat ~/.provisioning/tokens/oci

# Verify network connectivity
ping harbor.company.local

# For Harbor, check credentials
docker login harbor.company.local
```plaintext

---

## Environment Variables

| Variable | Purpose | Example |
|----------|---------|---------|
| `PROVISIONING_MODE` | Override active mode | `export PROVISIONING_MODE=cicd` |
| `PROVISIONING_WORKSPACE_CONFIG` | Override config location | `~/.provisioning/config` |
| `PROVISIONING_PROJECT_ROOT` | Project root directory | `/opt/project-provisioning` |

---

## Best Practices

### 1. Use Appropriate Mode

- **Solo**: Individual development, experimentation
- **Multi-User**: Team collaboration, shared infrastructure
- **CI/CD**: Automated testing and deployment
- **Enterprise**: Production deployments, compliance requirements

### 2. Validate Before Switching

```bash
provisioning mode validate <mode-name>
```plaintext

### 3. Backup Active Configuration

```bash
# Automatic backup created when switching
ls ~/.provisioning/config/active-mode.yaml.backup
```plaintext

### 4. Use Check Mode

```bash
provisioning server create --check
```plaintext

### 5. Lock Workspaces in Multi-User/Enterprise

```bash
provisioning workspace lock <workspace-name>
# ... make changes ...
provisioning workspace unlock <workspace-name>
```plaintext

### 6. Pull Extensions from OCI (Multi-User/CI/CD/Enterprise)

```bash
# Don't use local extensions in shared modes
provisioning extension pull <extension-name>
```plaintext

---

## Security Considerations

### Solo Mode

- ⚠️ No authentication (local development only)
- ⚠️ No encryption (sensitive data should use SOPS)
- ✅ Isolated environment

### Multi-User Mode

- ✅ Token-based authentication
- ✅ TLS in transit
- ✅ Audit logging
- ⚠️ No encryption at rest (configure as needed)

### CI/CD Mode

- ✅ Token authentication (short expiry)
- ✅ Full encryption (at rest + in transit)
- ✅ KMS for secrets
- ✅ Vulnerability scanning (critical threshold)
- ✅ Image signing required

### Enterprise Mode

- ✅ mTLS authentication
- ✅ Full encryption (at rest + in transit)
- ✅ KMS for all secrets
- ✅ Vulnerability scanning (critical threshold)
- ✅ Image signing + signature verification
- ✅ Network isolation
- ✅ Compliance policies (SOC2, ISO27001, HIPAA)

---

## Support and Documentation

- **Implementation Summary**: `MODE_SYSTEM_IMPLEMENTATION_SUMMARY.md`
- **Nickel Schemas**: `provisioning/schemas/modes.ncl`, `provisioning/schemas/oci_registry.ncl`
- **Mode Templates**: `workspace/config/modes/*.yaml`
- **Commands**: `provisioning/core/nulib/lib_provisioning/mode/`

---

**Last Updated**: 2025-10-06 | **Version**: 1.0.0
