2 lines
12 KiB
Markdown
2 lines
12 KiB
Markdown
# Infrastructure Schemas\n\nThis directory contains Nickel type-safe schemas for infrastructure configuration generation.\n\n## Overview\n\nThese schemas provide type contracts and validation for multi-format infrastructure configuration generation:\n\n- **Docker Compose** (`docker-compose.ncl`) - Container orchestration via Docker Compose\n- **Kubernetes** (`kubernetes.ncl`) - Kubernetes manifest generation (Deployments, Services, ConfigMaps)\n- **Nginx** (`nginx.ncl`) - Reverse proxy and load balancer configuration\n- **Prometheus** (`prometheus.ncl`) - Metrics collection and monitoring\n- **Systemd** (`systemd.ncl`) - System service units for standalone deployments\n- **OCI Registry** (`oci-registry.ncl`) - Container registry backend configuration (Zot, Distribution, Harbor)\n\n## Key Features\n\n### 1. Mode-Based Presets\n\nEach schema includes presets for different deployment modes:\n\n- **solo**: Single-node deployments (minimal resources)\n- **multiuser**: Staging/small production (2 replicas, HA)\n- **enterprise**: Large-scale production (3+ replicas, distributed storage)\n- **cicd**: CI/CD pipeline deployments\n\n### 2. Type Safety\n\n```\n# All fields are strongly typed with validation\nResourceLimits = {\n cpus | String, # Type: string\n memory | String,\n},\n\n# Enum validation\nServiceType = [| 'ClusterIP, 'NodePort, 'LoadBalancer |],\n\n# Numeric range validation\nPort = Number | {\n predicate = fun n => n > 0 && n < 65536,\n}\n```\n\n### 3. Export Formats\n\nSchemas export to multiple formats:\n\n```\n# Export as YAML (K8s, Docker Compose)\nnickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl\n\n# Export as JSON (OCI Registry, Prometheus configs)\nnickel export --format json provisioning/schemas/infrastructure/oci-registry.ncl\n\n# Export as TOML (systemd, Nginx)\nnickel export --format toml provisioning/schemas/infrastructure/systemd.ncl\n```\n\n## Single Source of Truth Pattern\n\nDefine service configuration once, generate multiple infrastructure outputs:\n\n```\norchestrator.ncl (Platform Service Schema)\n ↓\nInfrastructure Schemas (Docker, Kubernetes, Nginx, etc.)\n ↓\n[Multiple Outputs]\n├─→ docker-compose.yaml\n├─→ kubernetes/deployment.yaml\n├─→ nginx.conf\n├─→ prometheus.yml\n└─→ systemd/orchestrator.service\n```\n\n### Example: Service Port Definition\n\n```\n# Platform service schema (provisioning/schemas/platform/schemas/orchestrator.ncl)\nserver = {\n port | Number, # Define port once\n}\n\n# Used in Docker Compose\ndocker-compose = {\n services.orchestrator = {\n ports = ["%{orchestrator.server.port}:8080"],\n }\n}\n\n# Used in Kubernetes\nkubernetes = {\n containers.ports = [{\n containerPort = orchestrator.server.port,\n }]\n}\n\n# Used in Nginx\nnginx = {\n upstreams.orchestrator.servers = [{\n address = "orchestrator:%{orchestrator.server.port}",\n }]\n}\n```\n\n**Benefit**: Change port in one place, all infrastructure configs update automatically.\n\n## Validation Before Deployment\n\n```\n# Type check schema\nnickel typecheck provisioning/schemas/infrastructure/docker-compose.ncl\n\n# Validate export\nnickel export --format json provisioning/schemas/infrastructure/kubernetes.ncl \\n | jq . # Validate JSON structure\n\n# Check generated YAML\nnickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl \\n | kubectl apply --dry-run=client -f -\n```\n\n## File Structure\n\n```\ninfrastructure/\n├── README.md # This file\n├── docker-compose.ncl # Docker Compose schema (232 lines)\n├── kubernetes.ncl # Kubernetes manifests (376 lines)\n├── nginx.ncl # Nginx configuration (233 lines)\n├── prometheus.ncl # Prometheus configuration (280 lines)\n├── systemd.ncl # Systemd service units (235 lines)\n└── oci-registry.ncl # OCI Registry configuration (221 lines)\n```\n\n**Total**: 1,577 lines of type-safe infrastructure schemas\n\n## Usage Patterns\n\n### 1. Generate Solo Mode Infrastructure\n\n```\n# Export docker-compose for solo deployment\nnickel export --format yaml provisioning/schemas/infrastructure/docker-compose.ncl \\n | tee provisioning/platform/infrastructure/docker/docker-compose.solo.yaml\n\n# Validate with Docker\ndocker-compose -f docker-compose.solo.yaml config --quiet\n```\n\n### 2. Generate Enterprise HA Kubernetes\n\n```\n# Export Kubernetes manifests\nnickel export --format yaml provisioning/schemas/infrastructure/kubernetes.ncl \\n > provisioning/platform/infrastructure/kubernetes/deployment.yaml\n\n# Validate and apply\nkubectl apply --dry-run=client -f deployment.yaml\nkubectl apply -f deployment.yaml\n```\n\n### 3. Generate Monitoring Stack\n\n```\n# Prometheus configuration\nnickel export --format yaml provisioning/schemas/infrastructure/prometheus.ncl \\n > provisioning/platform/infrastructure/prometheus/prometheus.yml\n\n# Validate Prometheus config\npromtool check config provisioning/platform/infrastructure/prometheus/prometheus.yml\n```\n\n### 4. Auto-Generate Infrastructure from Service Schemas\n\n```\n# Composition function: generate Docker Compose from service port\nlet service = import "../platform/schemas/orchestrator.ncl" in\n{\n services.orchestrator = {\n image = "provisioning/orchestrator:latest",\n ports = ["%{service.server.port}:8080"],\n deploy.resources.limits = service.deploy.resources.limits,\n }\n}\n```\n\n## Documentation\n\n### Inline Schema Documentation\n\nEach schema field includes inline documentation (via `| doc`):\n\n```\nfield | Type | doc "description" | default = value\n```\n\n**Important**: With Nickel, `| doc` must come BEFORE `| default`:\n\n```\n✅ CORRECT: cpus | String | doc "CPU limit" | default = "2.0"\n❌ INCORRECT: cpus | String | default = "2.0" | doc "CPU limit"\n```\n\nFor details, see `.claude/guidelines/nickel.md`\n\n## Validation Rules\n\n### Docker Compose\n\n- ✅ Valid service names, port ranges\n- ✅ Resource limits: CPU and memory strings\n- ✅ Health check configuration\n- ✅ Environment variables typed as strings\n\n### Kubernetes\n\n- ✅ Valid API versions (apps/v1, v1)\n- ✅ Container resource requests/limits\n- ✅ Valid restart policies (Always, OnFailure, Never)\n- ✅ Port ranges (1-65535)\n\n### Nginx\n\n- ✅ Upstream server addresses\n- ✅ Rate limiting zones and rules\n- ✅ TLS configuration validation\n- ✅ Security headers structure\n\n### Prometheus\n\n- ✅ Scrape job configuration\n- ✅ Alert manager targets\n- ✅ Scrape intervals (duration format)\n- ✅ Relabel configuration\n\n### Systemd\n\n- ✅ Unit dependencies (after, requires, wants)\n- ✅ Resource limits (CPU quota, memory)\n- ✅ Restart policies\n- ✅ Service types (simple, forking, oneshot, etc.)\n\n### OCI Registry\n\n- ✅ Registry backends (Zot, Distribution, Harbor)\n- ✅ Storage backend selection (filesystem, S3, Azure)\n- ✅ Authentication methods (none, basic, bearer, OIDC)\n- ✅ Access control policies\n\n## Deployment Examples\n\nTwo comprehensive infrastructure examples are provided demonstrating solo and enterprise configurations:\n\n### Solo Deployment Example\n\n**File**: `examples-solo-deployment.ncl`\n\nMinimal single-node setup for development/testing:\n\n```\n# Exports 4 infrastructure components\ndocker_compose_services # 5 services: orchestrator, control-center, coredns, kms, oci_registry\nnginx_config # Simple upstream routing to localhost services\nprometheus_config # 4 scrape jobs for basic monitoring\noci_registry_config # Zot backend with filesystem storage\n```\n\n**Resource Allocation**:\n- Orchestrator: 1.0 CPU, 1024M RAM\n- Control Center: 0.5 CPU, 512M RAM\n- Other services: 0.25-0.5 CPU, 256-512M RAM\n\n**Export to JSON**:\n\n```\nnickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl\n# Output: 198 lines of configuration\n```\n\n### Enterprise Deployment Example\n\n**File**: `examples-enterprise-deployment.ncl`\n\nHigh-availability production-grade deployment:\n\n```\n# Exports 4 infrastructure components (HA versions)\ndocker_compose_services # 6 services with 3 replicas for HA\nnginx_config # Multiple upstreams with rate limiting and failover\nprometheus_config # 7 scrape jobs with remote storage\noci_registry_config # Harbor backend with S3 replication\n```\n\n**Resource Allocation**:\n- Orchestrator: 4.0 CPU, 4096M RAM (3 replicas)\n- Control Center: 2.0 CPU, 2048M RAM (HA)\n- Services scale appropriately for production load\n\n**Export to JSON**:\n\n```\nnickel export --format json provisioning/schemas/infrastructure/examples-enterprise-deployment.ncl\n# Output: 313 lines of configuration\n```\n\n### Example Comparison\n\n| Aspect | Solo | Enterprise |\n| -------- | ------ | ----------- |\n| **Services** | 5 | 6 |\n| **Orchestrator CPU** | 1.0 | 4.0 |\n| **Orchestrator Memory** | 1024M | 4096M |\n| **Prometheus Jobs** | 4 | 7 |\n| **Registry Backend** | Zot | Harbor |\n| **Use Case** | Dev/Testing | Production |\n| **JSON Size** | 198 lines | 313 lines |\n\n### Validation Results\n\nBoth examples have been tested and validated:\n\n✅ **Solo Deployment** (`examples-solo-deployment.ncl`):\n- Type-checks without errors\n- Exports to valid JSON (198 lines)\n- All resource limits validated\n- Port range validation: 8080, 9090, 5432, 53\n- JSON structure: docker_compose_services, nginx_config, prometheus_config, oci_registry_config\n\n✅ **Enterprise Deployment** (`examples-enterprise-deployment.ncl`):\n- Type-checks without errors\n- Exports to valid JSON (313 lines)\n- HA configuration with 3 replicas\n- Enhanced monitoring: 7 vs 4 scrape jobs\n- Distributed storage backend (Harbor vs Zot)\n- Full JSON structure validated with jq\n\n## Automation Scripts\n\nGenerate all infrastructure configs in one command:\n\n```\n# Generate all formats for all modes\nprovisioning/platform/scripts/generate-infrastructure-configs.nu\n\n# Generate specific mode/format\nprovisioning/platform/scripts/generate-infrastructure-configs.nu --mode solo --format yaml\n\n# Specify output directory\nprovisioning/platform/scripts/generate-infrastructure-configs.nu --output-dir /tmp/infra\n```\n\nSee `provisioning/platform/scripts/generate-infrastructure-configs.nu` for implementation details.\n\n## Validation and Testing\n\n### Test Generated Configs\n\n```\n# Export solo deployment\nnickel export --format json provisioning/schemas/infrastructure/examples-solo-deployment.ncl \\n > solo-infra.json\n\n# Validate JSON structure\njq . solo-infra.json\n\n# Inspect specific component (Docker Compose services)\njq '.docker_compose_services | keys' solo-infra.json\n\n# Check resource allocation\njq '.docker_compose_services.orchestrator.deploy.resources.limits' solo-infra.json\n```\n\n### Validate with Docker/Kubectl\n\n```\n# Export and validate Docker Compose\nnickel export --format yaml examples-solo-deployment.ncl \\n | docker-compose config --quiet\n\n# Validate Kubernetes (if applicable)\nnickel export --format yaml examples-enterprise-deployment.ncl \\n | kubectl apply --dry-run=client -f -\n\n# Validate Prometheus config\nnickel export --format yaml prometheus.ncl \\n | promtool check config -\n```\n\n## Integration with ConfigLoader\n\nInfrastructure schemas are independent from platform config schemas:\n\n- **Platform configs** → Service-specific settings (port, timeouts, auth)\n- **Infrastructure schemas** → Deployment-specific settings (replicas, resources, networking)\n\nConfigLoader automatically loads platform configs. Infrastructure configs are generated separately and deployed via infrastructure tools:\n\n```\nPlatform Schema (Nickel)\n ↓ nickel export → TOML\n ↓ ConfigLoader → Service reads config\n\nInfrastructure Schema (Nickel)\n ↓ nickel export → YAML/JSON\n ↓ Docker/Kubernetes/Nginx CLI\n```\n\n## Next Steps\n\n1. **Use these schemas** in your infrastructure-as-code pipeline\n2. **Generate configs** with the automation script\n3. **Validate** before deployment using format-specific tools\n4. **Maintain single source of truth** by updating schemas, not generated files\n\n---\n\n**Version**: 1.1.0 (Infrastructure Examples & Validation Added)\n**Total Schemas**: 6 core files, 1,577 lines\n**Deployment Examples**: 2 files, 54 lines (solo + enterprise)\n**Validated**: All schemas and examples pass type-checking and export validation\n**Last Updated**: 2025-01-06\n**Nickel Version**: Latest
|