# Infrastructure Schemas

This directory contains Nickel type-safe schemas for infrastructure configuration generation.

## Overview

These schemas provide type contracts and validation for multi-format infrastructure configuration generation:

- **Docker Compose** (`docker-compose.ncl`) - Container orchestration via Docker Compose
- **Kubernetes** (`kubernetes.ncl`) - Kubernetes manifest generation (Deployments, Services, ConfigMaps)
- **Nginx** (`nginx.ncl`) - Reverse proxy and load balancer configuration
- **Prometheus** (`prometheus.ncl`) - Metrics collection and monitoring
- **Systemd** (`systemd.ncl`) - System service units for standalone deployments
- **OCI Registry** (`oci-registry.ncl`) - Container registry backend configuration (Zot, Distribution, Harbor)

## Key Features

### 1. Mode-Based Presets

Each schema includes presets for different deployment modes:

- **solo**: Single-node deployments (minimal resources)
- **multiuser**: Staging/small production (2 replicas, HA)
- **enterprise**: Large-scale production (3+ replicas, distributed storage)
- **cicd**: CI/CD pipeline deployments

### 2. Type Safety

```bash
# All fields are strongly typed with validation
ResourceLimits = {
  cpus | String,               # Type: string
  memory | String,
},

# Enum validation
ServiceType = [| 'ClusterIP, 'NodePort, 'LoadBalancer |],

# Numeric range validation
Port = Number | {
  predicate = fun n => n > 0 && n < 65536,
}
```

### 3. Export Formats

Schemas export to multiple formats:

```bash
# Export as YAML (K8s, Docker Compose)
nickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl

# Export as JSON (OCI Registry, Prometheus configs)
nickel export --format json provisioning/schemas/infrastructure/oci-registry.ncl

# Export as TOML (systemd, Nginx)
nickel export --format toml provisioning/schemas/infrastructure/systemd.ncl
```

## Single Source of Truth Pattern

Define service configuration once, generate multiple infrastructure outputs:

```toml
orchestrator.ncl (Platform Service Schema)
    ↓
Infrastructure Schemas (Docker, Kubernetes, Nginx, etc.)
    ↓
[Multiple Outputs]
├─→ docker-compose.yaml
├─→ kubernetes/deployment.yaml
├─→ nginx.conf
├─→ prometheus.yml
└─→ systemd/orchestrator.service
```

### Example: Service Port Definition

```bash
# Platform service schema (provisioning/schemas/platform/schemas/orchestrator.ncl)
server = {
  port | Number,  # Define port once
}

# Used in Docker Compose
docker-compose = {
  services.orchestrator = {
    ports = ["%{orchestrator.server.port}:8080"],
  }
}

# Used in Kubernetes
kubernetes = {
  containers.ports = [{
    containerPort = orchestrator.server.port,
  }]
}

# Used in Nginx
nginx = {
  upstreams.orchestrator.servers = [{
    address = "orchestrator:%{orchestrator.server.port}",
  }]
}
```

**Benefit**: Change port in one place, all infrastructure configs update automatically.

## Validation Before Deployment

```bash
# Type check schema
nickel typecheck provisioning/schemas/infrastructure/docker-compose.ncl

# Validate export
nickel export --format json provisioning/schemas/infrastructure/kubernetes.ncl 
  | jq .  # Validate JSON structure

# Check generated YAML
nickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl 
  | kubectl apply --dry-run=client -f -
```

## File Structure

```bash
infrastructure/
├── README.md                        # This file
├── docker-compose.ncl               # Docker Compose schema (232 lines)
├── kubernetes.ncl                   # Kubernetes manifests (376 lines)
├── nginx.ncl                        # Nginx configuration (233 lines)
├── prometheus.ncl                   # Prometheus configuration (280 lines)
├── systemd.ncl                      # Systemd service units (235 lines)
└── oci-registry.ncl                 # OCI Registry configuration (221 lines)
```

**Total**: 1,577 lines of type-safe infrastructure schemas

## Usage Patterns

### 1. Generate Solo Mode Infrastructure

```bash
# Export docker-compose for solo deployment
nickel export --format yaml provisioning/schemas/infrastructure/docker-compose.ncl 
  | tee provisioning/platform/infrastructure/docker/docker-compose.solo.yaml

# Validate with Docker
docker-compose -f docker-compose.solo.yaml config --quiet
```

### 2. Generate Enterprise HA Kubernetes

```yaml
# Export Kubernetes manifests
nickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl 
  > provisioning/platform/infrastructure/kubernetes/deployment.yaml

# Validate and apply
kubectl apply --dry-run=client -f deployment.yaml
kubectl apply -f deployment.yaml
```

### 3. Generate Monitoring Stack

```bash
# Prometheus configuration
nickel export --format yaml provisioning/schemas/infrastructure/prometheus.ncl 
  > provisioning/platform/infrastructure/prometheus/prometheus.yml

# Validate Prometheus config
promtool check config provisioning/platform/infrastructure/prometheus/prometheus.yml
```

### 4. Auto-Generate Infrastructure from Service Schemas

```bash
# Composition function: generate Docker Compose from service port
let service = import "../platform/schemas/orchestrator.ncl" in
{
  services.orchestrator = {
    image = "provisioning/orchestrator:latest",
    ports = ["%{service.server.port}:8080"],
    deploy.resources.limits = service.deploy.resources.limits,
  }
}
```

## Documentation

### Inline Schema Documentation

Each schema field includes inline documentation (via `| doc`):

```bash
field | Type | doc "description" | default = value
```

**Important**: With Nickel, `| doc` must come BEFORE `| default`:

```nickel
✅ CORRECT:   cpus | String | doc "CPU limit" | default = "2.0"
❌ INCORRECT: cpus | String | default = "2.0" | doc "CPU limit"
```

For details, see `.claude/guidelines/nickel.md`

## Validation Rules

### Docker Compose

- ✅ Valid service names, port ranges
- ✅ Resource limits: CPU and memory strings
- ✅ Health check configuration
- ✅ Environment variables typed as strings

### Kubernetes

- ✅ Valid API versions (apps/v1, v1)
- ✅ Container resource requests/limits
- ✅ Valid restart policies (Always, OnFailure, Never)
- ✅ Port ranges (1-65535)

### Nginx

- ✅ Upstream server addresses
- ✅ Rate limiting zones and rules
- ✅ TLS configuration validation
- ✅ Security headers structure

### Prometheus

- ✅ Scrape job configuration
- ✅ Alert manager targets
- ✅ Scrape intervals (duration format)
- ✅ Relabel configuration

### Systemd

- ✅ Unit dependencies (after, requires, wants)
- ✅ Resource limits (CPU quota, memory)
- ✅ Restart policies
- ✅ Service types (simple, forking, oneshot, etc.)

### OCI Registry

- ✅ Registry backends (Zot, Distribution, Harbor)
- ✅ Storage backend selection (filesystem, S3, Azure)
- ✅ Authentication methods (none, basic, bearer, OIDC)
- ✅ Access control policies

## Deployment Examples

Two comprehensive infrastructure examples are provided demonstrating solo and enterprise configurations:

### Solo Deployment Example

**File**: `examples-solo-deployment.ncl`

Minimal single-node setup for development/testing:

```bash
# Exports 4 infrastructure components
docker_compose_services  # 5 services: orchestrator, control-center, coredns, kms, oci_registry
nginx_config             # Simple upstream routing to localhost services
prometheus_config        # 4 scrape jobs for basic monitoring
oci_registry_config      # Zot backend with filesystem storage
```

**Resource Allocation**:
- Orchestrator: 1.0 CPU, 1024M RAM
- Control Center: 0.5 CPU, 512M RAM
- Other services: 0.25-0.5 CPU, 256-512M RAM

**Export to JSON**:

```bash
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl
# Output: 198 lines of configuration
```

### Enterprise Deployment Example

**File**: `examples-enterprise-deployment.ncl`

High-availability production-grade deployment:

```bash
# Exports 4 infrastructure components (HA versions)
docker_compose_services  # 6 services with 3 replicas for HA
nginx_config             # Multiple upstreams with rate limiting and failover
prometheus_config        # 7 scrape jobs with remote storage
oci_registry_config      # Harbor backend with S3 replication
```

**Resource Allocation**:
- Orchestrator: 4.0 CPU, 4096M RAM (3 replicas)
- Control Center: 2.0 CPU, 2048M RAM (HA)
- Services scale appropriately for production load

**Export to JSON**:

```bash
nickel export --format json provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl
# Output: 313 lines of configuration
```

### Example Comparison

| Aspect | Solo | Enterprise |
| -------- | ------ | ----------- |
| **Services** | 5 | 6 |
| **Orchestrator CPU** | 1.0 | 4.0 |
| **Orchestrator Memory** | 1024M | 4096M |
| **Prometheus Jobs** | 4 | 7 |
| **Registry Backend** | Zot | Harbor |
| **Use Case** | Dev/Testing | Production |
| **JSON Size** | 198 lines | 313 lines |

### Validation Results

Both examples have been tested and validated:

✅ **Solo Deployment** (`examples-solo-deployment.ncl`):
- Type-checks without errors
- Exports to valid JSON (198 lines)
- All resource limits validated
- Port range validation: 8080, 9090, 5432, 53
- JSON structure: docker_compose_services, nginx_config, prometheus_config, oci_registry_config

✅ **Enterprise Deployment** (`examples-enterprise-deployment.ncl`):
- Type-checks without errors
- Exports to valid JSON (313 lines)
- HA configuration with 3 replicas
- Enhanced monitoring: 7 vs 4 scrape jobs
- Distributed storage backend (Harbor vs Zot)
- Full JSON structure validated with jq

## Automation Scripts

Generate all infrastructure configs in one command:

```toml
# Generate all formats for all modes
provisioning/platform/scripts/generate-infrastructure-configs.nu

# Generate specific mode/format
provisioning/platform/scripts/generate-infrastructure-configs.nu --mode solo --format yaml

# Specify output directory
provisioning/platform/scripts/generate-infrastructure-configs.nu --output-dir /tmp/infra
```

See `provisioning/platform/scripts/generate-infrastructure-configs.nu` for implementation details.

## Validation and Testing

### Test Generated Configs

```toml
# Export solo deployment
nickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl 
  > solo-infra.json

# Validate JSON structure
jq . solo-infra.json

# Inspect specific component (Docker Compose services)
jq '.docker_compose_services | keys' solo-infra.json

# Check resource allocation
jq '.docker_compose_services.orchestrator.deploy.resources.limits' solo-infra.json
```

### Validate with Docker/Kubectl

```bash
# Export and validate Docker Compose
nickel export --format yaml examples-solo-deployment.ncl 
  | docker-compose config --quiet

# Validate Kubernetes (if applicable)
nickel export --format yaml examples-enterprise-deployment.ncl 
  | kubectl apply --dry-run=client -f -

# Validate Prometheus config
nickel export --format yaml prometheus.ncl 
  | promtool check config -
```

## Integration with ConfigLoader

Infrastructure schemas are independent from platform config schemas:

- **Platform configs** → Service-specific settings (port, timeouts, auth)
- **Infrastructure schemas** → Deployment-specific settings (replicas, resources, networking)

ConfigLoader automatically loads platform configs. Infrastructure configs are generated separately and deployed via infrastructure tools:

```toml
Platform Schema (Nickel)
    ↓ nickel export → TOML
    ↓ ConfigLoader → Service reads config

Infrastructure Schema (Nickel)
    ↓ nickel export → YAML/JSON
    ↓ Docker/Kubernetes/Nginx CLI
```

## Next Steps

1. **Use these schemas** in your infrastructure-as-code pipeline
2. **Generate configs** with the automation script
3. **Validate** before deployment using format-specific tools
4. **Maintain single source of truth** by updating schemas, not generated files

---

**Version**: 1.1.0 (Infrastructure Examples & Validation Added)
**Total Schemas**: 6 core files, 1,577 lines
**Deployment Examples**: 2 files, 54 lines (solo + enterprise)
**Validated**: All schemas and examples pass type-checking and export validation
**Last Updated**: 2025-01-06
**Nickel Version**: Latest