425 lines
12 KiB
Markdown
425 lines
12 KiB
Markdown
# 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
|