provisioning/docs/src/operations/platform.md

# Platform Services

The Provisioning Platform consists of microservices that work together to provide infrastructure automation capabilities.

## 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](orchestrator.md)

**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](control-center.md)

**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](kms-service.md)

**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](provisioning-server.md)

**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](extension-registry.md)

**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](oci-registry.md)

**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](installer.md)

**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](mcp-server.md)

**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>
```

## Related Documentation

- **[Architecture Overview](../architecture/ARCHITECTURE_OVERVIEW.md)**
- **[Integration Patterns](../architecture/integration-patterns.md)**
- **[Service Management Guide](../user/SERVICE_MANAGEMENT_GUIDE.md)**
- **[API Reference](../api/rest-api.md)**