provisioning/docs/src/operations/platform.md

Platform Services\n\nThe Provisioning Platform consists of microservices that work together to provide infrastructure automation capabilities.\n\n## Overview\n\nAll platform services are built with Rust for performance, safety, and reliability. They expose REST APIs and integrate seamlessly with the\nNushell-based CLI.\n\n## Core Services\n\n### Orchestrator\n\nPurpose: Workflow coordination and task management\n\nKey Features:\n\n- Hybrid Rust/Nushell architecture\n- Multi-storage backends (Filesystem, SurrealDB)\n- REST API for workflow submission\n- Test environment service for automated testing\n\nPort: 8080 \nStatus: Production-ready\n\n---\n\n### Control Center\n\nPurpose: Policy engine and security management\n\nKey Features:\n\n- Cedar policy evaluation\n- JWT authentication\n- MFA support\n- Compliance framework (SOC2, HIPAA)\n- Anomaly detection\n\nPort: 9090 \nStatus: Production-ready\n\n---\n\n### KMS Service\n\nPurpose: Key management and encryption\n\nKey Features:\n\n- Multiple backends (Age, RustyVault, Cosmian, AWS KMS, Vault)\n- REST API for encryption operations\n- Nushell CLI integration\n- Context-based encryption\n\nPort: 8082 \nStatus: Production-ready\n\n---\n\n### API Server\n\nPurpose: REST API for remote provisioning operations\n\nKey Features:\n\n- Comprehensive REST API\n- JWT authentication\n- RBAC system (Admin, Operator, Developer, Viewer)\n- Async operations with status tracking\n- Audit logging\n\nPort: 8083 \nStatus: Production-ready\n\n---\n\n### Extension Registry\n\nPurpose: Extension discovery and download\n\nKey Features:\n\n- Multi-backend support (Gitea, OCI)\n- Smart caching (LRU with TTL)\n- Prometheus metrics\n- Search functionality\n\nPort: 8084 \nStatus: Production-ready\n\n---\n\n### OCI Registry\n\nPurpose: Artifact storage and distribution\n\nSupported Registries:\n\n- Zot (recommended for development)\n- Harbor (recommended for production)\n- Distribution (OCI reference)\n\nKey Features:\n\n- Namespace organization\n- Access control\n- Garbage collection\n- High availability\n\nPort: 5000 \nStatus: Production-ready\n\n---\n\n### Platform Installer\n\nPurpose: Interactive platform deployment\n\nKey Features:\n\n- Interactive Ratatui TUI\n- Headless mode for automation\n- Multiple deployment modes (Solo, Multi-User, CI/CD, Enterprise)\n- Platform-agnostic (Docker, Podman, Kubernetes, OrbStack)\n\nStatus: Complete (1,480 lines, 7 screens)\n\n---\n\n### MCP Server\n\nPurpose: Model Context Protocol for AI integration\n\nKey Features:\n\n- Rust-native implementation\n- 1000x faster than Python version\n- AI-powered server parsing\n- Multi-provider support\n\nStatus: Proof of concept complete\n\n---\n\n## Architecture\n\n\n┌─────────────────────────────────────────────────────────────┐\n│ Provisioning Platform │\n├─────────────────────────────────────────────────────────────┤\n│ │\n│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │\n│ │ Orchestrator │ │Control Center│ │ API Server │ │\n│ │ :8080 │ │ :9090 │ │ :8083 │ │\n│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │\n│ │ │ │ │\n│ ┌──────┴──────────────────┴──────────────────┴───────┐ │\n│ │ Service Mesh / API Gateway │ │\n│ └──────────────────┬──────────────────────────────────┘ │\n│ │ │\n│ ┌──────────────────┼──────────────────────────────────┐ │\n│ │ KMS Service Extension Registry OCI Registry │ │\n│ │ :8082 :8084 :5000 │ │\n│ └─────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────┘\n\n\n## Deployment\n\n### Starting All Services\n\n\n# Using platform installer (recommended)\nprovisioning-installer --headless --mode solo --yes\n\n# Or manually with docker-compose\ncd provisioning/platform\ndocker-compose up -d\n\n# Or individually\nprovisioning platform start orchestrator\nprovisioning platform start control-center\nprovisioning platform start kms-service\nprovisioning platform start api-server\n\n\n### Checking Service Status\n\n\n# Check all services\nprovisioning platform status\n\n# Check specific service\nprovisioning platform status orchestrator\n\n# View service logs\nprovisioning platform logs orchestrator --tail 100 --follow\n\n\n### Service Health Checks\n\nEach service exposes a health endpoint:\n\n\n# Orchestrator\ncurl http://localhost:8080/health\n\n# Control Center\ncurl http://localhost:9090/health\n\n# KMS Service\ncurl http://localhost:8082/api/v1/kms/health\n\n# API Server\ncurl http://localhost:8083/health\n\n# Extension Registry\ncurl http://localhost:8084/api/v1/health\n\n# OCI Registry\ncurl http://localhost:5000/v2/\n\n\n## Service Dependencies\n\n\nOrchestrator\n└── Nushell CLI\n\nControl Center\n├── SurrealDB (storage)\n└── Orchestrator (optional, for workflows)\n\nKMS Service\n├── Age (development)\n└── Cosmian KMS (production)\n\nAPI Server\n└── Nushell CLI\n\nExtension Registry\n├── Gitea (optional)\n└── OCI Registry (optional)\n\nOCI Registry\n└── Docker/Podman\n\n\n## Configuration\n\nEach service uses TOML-based configuration:\n\n\nprovisioning/\n├── config/\n│ ├── orchestrator.toml\n│ ├── control-center.toml\n│ ├── kms.toml\n│ ├── api-server.toml\n│ ├── extension-registry.toml\n│ └── oci-registry.toml\n\n\n## Monitoring\n\n### Metrics Collection\n\nServices expose Prometheus metrics:\n\n\n# prometheus.yml\nscrape_configs:\n - job_name: 'orchestrator'\n static_configs:\n - targets: ['localhost:8080']\n \n - job_name: 'control-center'\n static_configs:\n - targets: ['localhost:9090']\n \n - job_name: 'kms-service'\n static_configs:\n - targets: ['localhost:8082']\n\n\n### Logging\n\nAll services use structured logging:\n\n\n# View aggregated logs\nprovisioning platform logs --all\n\n# Filter by level\nprovisioning platform logs --level error\n\n# Export logs\nprovisioning platform logs --export /tmp/platform-logs.json\n\n\n## Security\n\n### Authentication\n\n- JWT Tokens: Used by API Server and Control Center\n- API Keys: Used by Extension Registry\n- mTLS: Optional for service-to-service communication\n\n### Encryption\n\n- TLS/SSL: All HTTP endpoints support TLS\n- At-Rest: KMS Service handles encryption keys\n- In-Transit: Network traffic encrypted with TLS\n\n### Access Control\n\n- RBAC: Control Center provides role-based access\n- Policies: Cedar policies enforce fine-grained permissions\n- Audit Logging: All operations logged for compliance\n\n## Troubleshooting\n\n### Service Won't Start\n\n\n# Check logs\nprovisioning platform logs <service> --tail 100\n\n# Verify configuration\nprovisioning validate config --service <service>\n\n# Check port availability\nlsof -i :<port>\n\n\n### Service Unhealthy\n\n\n# Check dependencies\nprovisioning platform deps <service>\n\n# Restart service\nprovisioning platform restart <service>\n\n# Full service reset\nprovisioning platform restart <service> --clean\n\n\n### High Resource Usage\n\n\n# Check resource usage\nprovisioning platform resources\n\n# View detailed metrics\nprovisioning platform metrics <service>\n\n\n## Related Documentation\n\n- Architecture Overview\n- Integration Patterns\n- Service Management Guide\n- API Reference