Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Platform Services

The Provisioning Platform consists of several microservices that work together to provide a complete infrastructure automation solution.

Overview

All platform services are built with Rust for performance, safety, and reliability. They expose REST APIs and integrate seamlessly with the Nushell-based CLI.

Core Services

Orchestrator

Purpose: Workflow coordination and task management

Key Features:

  • Hybrid Rust/Nushell architecture
  • Multi-storage backends (Filesystem, SurrealDB)
  • REST API for workflow submission
  • Test environment service for automated testing

Port: 8080
Status: Production-ready

Control Center

Purpose: Policy engine and security management

Key Features:

  • Cedar policy evaluation
  • JWT authentication
  • MFA support
  • Compliance framework (SOC2, HIPAA)
  • Anomaly detection

Port: 9090
Status: Production-ready

KMS Service

Purpose: Key management and encryption

Key Features:

  • Multiple backends (Age, RustyVault, Cosmian, AWS KMS, Vault)
  • REST API for encryption operations
  • Nushell CLI integration
  • Context-based encryption

Port: 8082
Status: Production-ready

API Server

Purpose: REST API for remote provisioning operations

Key Features:

  • Comprehensive REST API
  • JWT authentication
  • RBAC system (Admin, Operator, Developer, Viewer)
  • Async operations with status tracking
  • Audit logging

Port: 8083
Status: Production-ready

Extension Registry

Purpose: Extension discovery and download

Key Features:

  • Multi-backend support (Gitea, OCI)
  • Smart caching (LRU with TTL)
  • Prometheus metrics
  • Search functionality

Port: 8084
Status: Production-ready

OCI Registry

Purpose: Artifact storage and distribution

Supported Registries:

  • Zot (recommended for development)
  • Harbor (recommended for production)
  • Distribution (OCI reference)

Key Features:

  • Namespace organization
  • Access control
  • Garbage collection
  • High availability

Port: 5000
Status: Production-ready

Platform Installer

Purpose: Interactive platform deployment

Key Features:

  • Interactive Ratatui TUI
  • Headless mode for automation
  • Multiple deployment modes (Solo, Multi-User, CI/CD, Enterprise)
  • Platform-agnostic (Docker, Podman, Kubernetes, OrbStack)

Status: Complete (1,480 lines, 7 screens)

MCP Server

Purpose: Model Context Protocol for AI integration

Key Features:

  • Rust-native implementation
  • 1000x faster than Python version
  • AI-powered server parsing
  • Multi-provider support

Status: Proof of concept complete

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Provisioning Platform                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Orchestrator │  │Control Center│  │  API Server  │      │
│  │  :8080       │  │  :9090       │  │  :8083       │      │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
│         │                  │                  │              │
│  ┌──────┴──────────────────┴──────────────────┴───────┐    │
│  │         Service Mesh / API Gateway                  │    │
│  └──────────────────┬──────────────────────────────────┘    │
│                     │                                        │
│  ┌──────────────────┼──────────────────────────────────┐    │
│  │  KMS Service   Extension Registry   OCI Registry    │    │
│  │   :8082            :8084              :5000         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Deployment

Starting All Services

# Using platform installer (recommended)
provisioning-installer --headless --mode solo --yes

# Or manually with docker-compose
cd provisioning/platform
docker-compose up -d

# Or individually
provisioning platform start orchestrator
provisioning platform start control-center
provisioning platform start kms-service
provisioning platform start api-server

Checking Service Status

# Check all services
provisioning platform status

# Check specific service
provisioning platform status orchestrator

# View service logs
provisioning platform logs orchestrator --tail 100 --follow

Service Health Checks

Each service exposes a health endpoint:

# Orchestrator
curl http://localhost:8080/health

# Control Center
curl http://localhost:9090/health

# KMS Service
curl http://localhost:8082/api/v1/kms/health

# API Server
curl http://localhost:8083/health

# Extension Registry
curl http://localhost:8084/api/v1/health

# OCI Registry
curl http://localhost:5000/v2/

Service Dependencies

Orchestrator
└── Nushell CLI

Control Center
├── SurrealDB (storage)
└── Orchestrator (optional, for workflows)

KMS Service
├── Age (development)
└── Cosmian KMS (production)

API Server
└── Nushell CLI

Extension Registry
├── Gitea (optional)
└── OCI Registry (optional)

OCI Registry
└── Docker/Podman

Configuration

Each service uses TOML-based configuration:

provisioning/
├── config/
│   ├── orchestrator.toml
│   ├── control-center.toml
│   ├── kms.toml
│   ├── api-server.toml
│   ├── extension-registry.toml
│   └── oci-registry.toml

Monitoring

Metrics Collection

Services expose Prometheus metrics:

# prometheus.yml
scrape_configs:
  - job_name: 'orchestrator'
    static_configs:
      - targets: ['localhost:8080']
  
  - job_name: 'control-center'
    static_configs:
      - targets: ['localhost:9090']
  
  - job_name: 'kms-service'
    static_configs:
      - targets: ['localhost:8082']

Logging

All services use structured logging:

# View aggregated logs
provisioning platform logs --all

# Filter by level
provisioning platform logs --level error

# Export logs
provisioning platform logs --export /tmp/platform-logs.json

Security

Authentication

  • JWT Tokens: Used by API Server and Control Center
  • API Keys: Used by Extension Registry
  • mTLS: Optional for service-to-service communication

Encryption

  • TLS/SSL: All HTTP endpoints support TLS
  • At-Rest: KMS Service handles encryption keys
  • In-Transit: Network traffic encrypted with TLS

Access Control

  • RBAC: Control Center provides role-based access
  • Policies: Cedar policies enforce fine-grained permissions
  • Audit Logging: All operations logged for compliance

Troubleshooting

Service Won’t Start

# Check logs
provisioning platform logs <service> --tail 100

# Verify configuration
provisioning validate config --service <service>

# Check port availability
lsof -i :<port>

Service Unhealthy

# Check dependencies
provisioning platform deps <service>

# Restart service
provisioning platform restart <service>

# Full service reset
provisioning platform restart <service> --clean

High Resource Usage

# Check resource usage
provisioning platform resources

# View detailed metrics
provisioning platform metrics <service>