jesus/prvng_platform

Fork 0

Jesús Pérez a747d8a201

chore: update README and CHANGELOG with ops control plane, audit-mirror, contract-tests

2026-05-12 03:13:17 +01:00

23 KiB

Raw Blame History

Provisioning Logo

Platform Services

Platform-level services for the Provisioning project infrastructure automation platform. These services provide the high-performance execution layer, management interfaces, and supporting infrastructure for the entire provisioning system.

Overview

The Platform layer consists of production-ready services built primarily in Rust, providing:

Workflow Execution - High-performance orchestration and task coordination
Management Interfaces - Web UI and REST APIs for infrastructure management
Security & Authorization - Enterprise-grade access control and permissions
Installation & Distribution - Multi-mode installer with TUI, CLI, and unattended modes
AI Integration - Model Context Protocol (MCP) server for intelligent assistance
Extension Management - OCI-based registry for distributing modules

Core Platform Services

1. Orchestrator (`orchestrator/`)

High-performance Rust/Nushell hybrid orchestrator for workflow execution.

Language: Rust + Nushell integration

Purpose: Workflow execution, task scheduling, state management

Key Features:

File-based persistence for reliability
Priority processing with retry logic
Checkpoint recovery and automatic rollback
REST API endpoints for external integration
Solves deep call stack limitations
Parallel task execution with dependency resolution

Status: ✅ Production Ready (v3.0.0)

Documentation: See Orchestrator Endpoints

Quick Start:

cd orchestrator
./scripts/start-orchestrator.nu --background

REST API:

GET http://localhost:8080/health - Health check
GET http://localhost:8080/tasks - List all tasks
POST http://localhost:8080/workflows/servers/create - Server workflow
POST http://localhost:8080/workflows/taskserv/create - Taskserv workflow

2. Control Center (`control-center/`)

Backend control center service with authorization and permissions management.

Language: Rust

Purpose: Web-based infrastructure management with RBAC

Key Features:

Authorization and permissions control (enterprise security)
Role-Based Access Control (RBAC)
Audit logging and compliance tracking
System management APIs
Configuration management
Resource monitoring

Status: ✅ Active Development

Security Features:

Fine-grained permissions system
User authentication and session management
API key management
Activity audit logs

3. Control Center UI (`control-center-ui/`)

Frontend web interface for infrastructure management.

Language: Web (HTML/CSS/JavaScript)

Purpose: User-friendly dashboard and administration interface

Key Features:

Dashboard with real-time monitoring
Configuration management interface
System administration tools
Workflow visualization
Log viewing and search

Status: ✅ Active Development

Integration: Communicates with Control Center backend and Orchestrator APIs

4. Installer (`installer/`)

Multi-mode platform installation system with interactive TUI, headless CLI, and unattended modes.

Language: Rust (Ratatui TUI) + Nushell scripts

Purpose: Platform installation and configuration generation

Key Features:

Interactive TUI Mode: Beautiful terminal UI with 7 screens
Headless Mode: CLI automation for scripted installations
Unattended Mode: Zero-interaction CI/CD deployments
Deployment Modes: Solo (2 CPU/4GB), MultiUser (4 CPU/8GB), CICD (8 CPU/16GB), Enterprise (16 CPU/32GB)
MCP Integration: 7 AI-powered settings tools for intelligent configuration
Nushell Scripts: Complete deployment automation for Docker, Podman, Kubernetes, OrbStack

Status: ✅ Production Ready (v3.5.0)

Quick Start:

# Interactive TUI
provisioning-installer

# Headless mode
provisioning-installer --headless --mode solo --yes

# Unattended CI/CD
provisioning-installer --unattended --config config.toml

Documentation: installer/docs/ - Complete guides and references

5. MCP Server (`mcp-server/`)

Model Context Protocol server for AI-powered assistance.

Language: Nushell

Purpose: AI integration for intelligent configuration and assistance

Key Features:

7 AI-powered settings tools
Intelligent config completion
Natural language infrastructure queries
Configuration validation and suggestions
Context-aware help system

Status: ✅ Active Development

MCP Tools:

Settings generation
Configuration validation
Best practice recommendations
Infrastructure planning assistance
Error diagnosis and resolution

6. OCI Registry (`infrastructure/oci-registry/`)

OCI-compliant registry for extension distribution and versioning.

Purpose: Distributing and managing extensions

Key Features:

Task service packages
Provider packages
Cluster templates
Workflow definitions
Version management and updates
Dependency resolution

Status: 🔄 Planned

Benefits:

Centralized extension management
Version control and rollback
Dependency tracking
Community marketplace ready

7. ops-keeper (`crates/ops-keeper/`)

Policy-based operation gate — signs approved operations with Ed25519 keys before forwarding to the control plane.

Language: Rust

Purpose: Operation approval, policy enforcement, and keeper-signed JWT emission

Key Features:

Glob-based PolicyDef matching against op type, image patterns, and target patterns
Signer wraps an Ed25519 key pair; emits compact JWTs (OpsClaims) on approval
PendingOp tracking with NATS JetStream durable consumer (ops.pending.*)
AuditEvent emission to ops.audit.* stream on approval or rejection
Nickel-driven policy config (keeper_policy.ncl)

Status: ✅ Active Development

8. ops-controller (`crates/ops-controller/`)

NATS JetStream consumer that processes keeper-approved operations, calls the orchestrator, and enforces idempotency via SurrealDB.

Language: Rust

Purpose: Durable control plane execution with at-least-once delivery guarantees

Key Features:

Pull consumer on ops.pending.* JetStream stream
Ed25519 JWT verification of keeper-signed claims before dispatch
Idempotency check via SurrealDB; reconciles stale pending ops on startup
Orchestrator HTTP dispatch with structured AckResult (Ack/Nak/Term)
Audit emission (ops.audit.*) on every terminal outcome

Status: ✅ Active Development

ADR: ADR-038 (ops control plane design)

9. audit-mirror (`crates/audit-mirror/`)

Sidecar that consumes ops.audit.* NATS events and mirrors each event as a signed git commit into a Radicle repository.

Language: Rust

Purpose: Immutable, content-addressed audit trail via Radicle git storage

Key Features:

NATS JetStream pull consumer on ops.audit.*
JTI deduplication — skips already-committed event IDs via git log scan
commit_writer creates signed commits with the audit payload as the blob
radicle_publish announces the repo to the Radicle network after each commit
Configurable via CLI flags (NATS URL, workspace, Radicle repo path, key path)

Status: ✅ Active Development

ADR: ADR-038

10. API Gateway (`infrastructure/api-gateway/`)

Unified REST API gateway for external integration.

Language: Rust

Purpose: API routing, authentication, and rate limiting

Key Features:

Request routing to backend services
Authentication and authorization
Rate limiting and throttling
API versioning

Status: 🔄 Planned

11. Extension Registry (`crates/extension-registry/`)

Registry and catalog for browsing, discovering, and distributing extensions.

Language: Rust

Purpose: Extension discovery, metadata management, and OCI/Forgejo-backed distribution

Status: ✅ Active Development

12. contract-tests (`crates/contract-tests/`)

G3 contract test suite — verifies semantic equivalence across the CLI↔HTTP↔MCP tier stack.

Language: Rust (test crate)

Purpose: Prevent drift between registry, HTTP daemon, and MCP server response shapes

Key Features:

Tier A: direct registry invocation (reference baseline)
Tier B: axum HTTP server on 127.0.0.1:0 (ephemeral port)
Tier C: in-process MCP handle_request
Normaliser strips volatile fields (trace_id, timestamp) — asserts semantic, not byte-for-byte equality
JSON schema validation against listing_output_schema on every tier

Status: ✅ Active Development

13. ncl-sync (`crates/ncl-sync/`)

Nickel configuration sync daemon — compiles NCL to JSON proactively and maintains a shared cache for all Nu processes.

Language: Rust

Purpose: Eliminate nickel export latency (~2–5s per call) from CLI commands by pre-compiling NCL files and serving results from an in-memory-backed file cache.

Key Features:

File watcher (notify) on workspace NCL directories — re-exports on change automatically
Warm-up on prvng platform start — first command of the day already finds cache hot
Shared cache at ~/.cache/provisioning/config-cache/ used by both this daemon and nu_plugin_nickel
Content-addressed keys: SHA256(file_content + sorted_import_paths + format) — identical to plugin key strategy, zero coordination overhead
Post-operation sync: Nu writes .sync-<pid>.json sidecar after mutations; daemon re-exports within 500 ms
Configurable via platform/config/ncl-sync.ncl (idle timeout, concurrency, poll interval)
No NATS, no SurrealDB, no platform service dependencies — intentional to avoid bootstrap circularity

Status: ✅ Production Ready

Install:

cargo build --release --package ncl-sync
install -m 0755 target/release/provisioning-ncl-sync ~/.local/bin/provisioning-ncl-sync

Usage:

# Start daemon for a workspace
ncl-sync daemon --workspace ~/workspaces/libre-daoshi

# One-shot warm-up
ncl-sync warm ~/workspaces/libre-daoshi

# Evict a specific file from cache
ncl-sync invalidate settings.ncl

# Print cache key (parity testing)
ncl-sync key settings.ncl --import-path /ws --import-path /prov

# Cache statistics
ncl-sync stats

Lifecycle integration: Started automatically by prvng platform start, stopped by prvng platform stop. Status visible in prvng platform status.

Performance impact (with warm cache):

Command	Before	After
`prvng component list`	~3–7 s	~1.5 s
`prvng workflow list`	~3–5 s	~1.5 s
`prvng deploy`	~15–30 s	~3–5 s

Configuration (platform/config/ncl-sync.ncl):

{
  ncl_sync = {
    idle_timeout_secs = 600,     # daemon auto-shutdown after N seconds idle
    sync_poll_interval_ms = 500, # how often to check for sync-request sidecars
    warm_concurrency = 4,        # max parallel nickel export during warm-up
    extra_import_paths = [],     # additional import paths beyond workspace + $PROVISIONING
  }
}

ADRs: ADR-022 (daemon design), ADR-023 (Nu wrapper strategy)

Supporting Services

CoreDNS (`config/coredns/`)

DNS service configuration for cluster environments.

Purpose: Service discovery and DNS resolution

Status: ✅ Configuration Ready

Monitoring (`infrastructure/monitoring/`)

Observability and monitoring infrastructure.

Purpose: Metrics, logging, and alerting

Components:

Prometheus configuration
Grafana dashboards
Alert rules

Status: ✅ Configuration Ready

Nginx (`infrastructure/nginx/`)

Reverse proxy and load balancer configurations.

Purpose: HTTP routing and SSL termination

Status: ✅ Configuration Ready

Docker Compose (`infrastructure/docker/`)

Docker Compose configurations for local development.

Purpose: Quick local platform deployment

Status: ✅ Ready for Development

Systemd (`infrastructure/systemd/`)

Systemd service units for platform services.

Purpose: Production deployment with systemd

Status: ✅ Ready for Production

Architecture

┌──────────────────────────────────────────────────────────────┐
│                   User Interfaces                            │
│  • CLI (provisioning command)                                │
│  • Web UI (Control Center UI)                                │
│  • API Clients                                               │
└──────────────────────────────────────────────────────────────┘
                             ↓
┌──────────────────────────────────────────────────────────────┐
│                   API Gateway                                │
│  • Request Routing                                           │
│  • Authentication & Authorization                            │
│  • Rate Limiting                                             │
└──────────────────────────────────────────────────────────────┘
                             ↓
┌──────────────────────────────────────────────────────────────┐
│              Platform Services Layer                         │
│                                                              │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│   │ Orchestrator │  │ Control Ctr  │  │ MCP Server   │       │
│   │   (Rust)     │  │   (Rust)     │  │ (Nushell)    │       │
│   └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                              │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│   │  Installer   │  │ Extension    │  │  ops-keeper  │       │
│   │  (Rust/Nu)   │  │  Registry    │  │  (Rust)      │       │
│   └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                              │
│   ┌──────────────┐  ┌──────────────┐                         │
│   │ops-controller│  │ audit-mirror │                         │
│   │   (Rust)     │  │   (Rust)     │                         │
│   └──────────────┘  └──────────────┘                         │
│                                                              │
│   ┌──────────────────────────────────────────────────────┐   │
│   │  ncl-sync daemon  (Rust)                             │   │
│   │  ~/.cache/provisioning/config-cache/  ←→  Nu procs  │   │
│   └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
                             ↓
┌──────────────────────────────────────────────────────────────┐
│                Data & State Layer                            │
│  • NATS JetStream (ops.pending.*, ops.audit.*, TASKS)        │
│  • SurrealDB (State Management, Idempotency)                 │
│  • Radicle (Immutable Audit Log via git)                     │
│  • File-based Persistence (Checkpoints)                      │
└──────────────────────────────────────────────────────────────┘

Technology Stack

Primary Languages

Language	Usage	Services
Rust	Platform services, performance layer	Orchestrator, Control Center, Installer, API Gateway
Nushell	Scripting, automation, MCP integration	MCP Server, Installer scripts
Web	Frontend interfaces	Control Center UI

Key Dependencies

tokio - Async runtime for Rust services
axum - Web framework (control-center, orchestrator, provisioning-daemon)
async-nats - NATS JetStream client (ops-keeper, ops-controller, audit-mirror, control-center)
surrealdb - State management and idempotency store
serde - Serialization/deserialization
ratatui - Terminal UI framework (installer)
git2 - Radicle git integration (audit-mirror)
jsonwebtoken - Ed25519 JWT signing/verification (ops-keeper, ops-controller)

Deployment Modes

1. Development Mode

# Docker Compose for local development
docker-compose -f infrastructure/docker/dev.yml up

2. Production Mode (Systemd)

# Install systemd units
sudo cp infrastructure/systemd/*.service /etc/infrastructure/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now provisioning-orchestrator
sudo systemctl enable --now provisioning-control-center

3. Kubernetes Deployment

# Deploy platform services to Kubernetes
kubectl apply -f k8s/

Security Features

Enterprise Security Stack

Authorization & Permissions (Control Center)
- Role-Based Access Control (RBAC)
- Fine-grained permissions
- Audit logging
Authentication
- API key management
- Session management
- Token-based auth (JWT)
Secrets Management
- Integration with SOPS/Age
- Cosmian KMS support
- Secure configuration storage
Policy Enforcement
- Cedar policy engine integration
- Compliance checking
- Anomaly detection

Getting Started

Prerequisites

Rust - Latest stable (for building platform services)
Nushell 0.107.1+ - For MCP server and scripts
Docker (optional) - For containerized deployment
Kubernetes (optional) - For K8s deployment

Building Platform Services

# Build all Rust services
cd orchestrator && cargo build --release
cd ../control-center && cargo build --release
cd ../installer && cargo build --release

Running Services

# Start orchestrator
cd orchestrator
./scripts/start-orchestrator.nu --background

# Start control center
cd control-center
cargo run --release

# Start MCP server
cd mcp-server
nu run.nu

Development

Project Structure

platform/
├── crates/
│   ├── orchestrator/       # Rust orchestrator service
│   ├── control-center/     # Rust control center backend
│   ├── control-center-ui/  # Web frontend
│   ├── mcp-server/         # Nushell MCP server
│   ├── ncl-sync/           # Nickel config sync daemon
│   └── ...
├── config/
│   ├── ncl-sync.ncl        # ncl-sync daemon configuration
│   └── external-services.ncl
├── infrastructure/
│   ├── api-gateway/        # Rust API gateway (planned)
│   ├── oci-registry/       # OCI registry (planned)
│   ├── docker/             # Docker Compose configs
│   ├── systemd/            # Systemd units
│   └── ...
└── docs/                   # Platform documentation

Adding New Services

Create service directory in platform/
Add README.md with service description
Implement service following architecture patterns
Add tests and documentation
Update platform/README.md (this file)
Add deployment configurations (docker-compose, k8s, systemd)

Integration with Provisioning

Platform services integrate seamlessly with the Provisioning system:

Core Engine (../core/) provides CLI and libraries
Extensions (../extensions/) provide providers, taskservs, clusters
Platform Services (this directory) provide execution and management
Configuration (../kcl/, ../config/) defines infrastructure

Documentation

Platform Documentation

Orchestrator: Orchestrator Endpoints
Installer: Getting Started Guide
System Overview: Component Architecture

API Documentation

REST API Reference: docs/api/ (when orchestrator is running)
MCP Tools Reference: mcp-server/docs/

Architecture Documentation

Main Documentation: Platform Documentation
Architecture Decisions: Architecture Decision Records

Contributing

When contributing to platform services:

Follow Rust Best Practices - Idiomatic Rust, proper error handling
Security First - Always consider security implications
Performance Matters - Platform services are performance-critical
Document APIs - All REST endpoints must be documented
Add Tests - Unit tests and integration tests required
Update Docs - Keep README and API docs current

Status Legend

✅ Production Ready - Fully implemented and tested
✅ Active Development - Working implementation, ongoing improvements
✅ Configuration Ready - Configuration files ready for deployment
🔄 Planned - Design phase, implementation pending
🔄 In Development - Early implementation stage

Support

For platform service issues:

Check service-specific README in service directory
Review logs: journalctl -u provisioning-* (systemd)
API documentation: http://localhost:8080/docs (when running)
See Provisioning project for general support

Maintained By: Platform Team Last Updated: 2026-05-12 Platform Version: 3.6.0

23 KiB Raw Blame History Unescape Escape

Platform Services

Overview

Core Platform Services

1. Orchestrator (orchestrator/)

2. Control Center (control-center/)

3. Control Center UI (control-center-ui/)

4. Installer (installer/)

5. MCP Server (mcp-server/)

6. OCI Registry (infrastructure/oci-registry/)

7. ops-keeper (crates/ops-keeper/)

8. ops-controller (crates/ops-controller/)

9. audit-mirror (crates/audit-mirror/)

10. API Gateway (infrastructure/api-gateway/)

11. Extension Registry (crates/extension-registry/)

12. contract-tests (crates/contract-tests/)

13. ncl-sync (crates/ncl-sync/)

Supporting Services

CoreDNS (config/coredns/)

Monitoring (infrastructure/monitoring/)

Nginx (infrastructure/nginx/)

Docker Compose (infrastructure/docker/)

Systemd (infrastructure/systemd/)

Architecture

Technology Stack

Primary Languages

Key Dependencies

Deployment Modes

1. Development Mode

2. Production Mode (Systemd)

3. Kubernetes Deployment

Security Features

Enterprise Security Stack

Getting Started

Prerequisites

Building Platform Services

Running Services

Development

Project Structure

Adding New Services

Integration with Provisioning

Documentation

Platform Documentation

API Documentation

Architecture Documentation

Contributing

Status Legend

Support

23 KiB

Raw Blame History

1. Orchestrator (`orchestrator/`)

2. Control Center (`control-center/`)

3. Control Center UI (`control-center-ui/`)

4. Installer (`installer/`)

5. MCP Server (`mcp-server/`)

6. OCI Registry (`infrastructure/oci-registry/`)

7. ops-keeper (`crates/ops-keeper/`)

8. ops-controller (`crates/ops-controller/`)

9. audit-mirror (`crates/audit-mirror/`)

10. API Gateway (`infrastructure/api-gateway/`)

11. Extension Registry (`crates/extension-registry/`)

12. contract-tests (`crates/contract-tests/`)

13. ncl-sync (`crates/ncl-sync/`)

CoreDNS (`config/coredns/`)

Monitoring (`infrastructure/monitoring/`)

Nginx (`infrastructure/nginx/`)

Docker Compose (`infrastructure/docker/`)

Systemd (`infrastructure/systemd/`)