Jesús Pérez 6a59d34bb1
chore: update provisioning configuration and documentation
Update configuration files, templates, and internal documentation
for the provisioning repository system.

Configuration Updates:
- KMS configuration modernization
- Plugin system settings
- Service port mappings
- Test cluster topologies
- Installation configuration examples
- VM configuration defaults
- Cedar authorization policies

Documentation Updates:
- Library module documentation
- Extension API guides
- AI system documentation
- Service management guides
- Test environment setup
- Plugin usage guides
- Validator configuration documentation

All changes are backward compatible.
2025-12-11 21:50:42 +00:00

531 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE HTML>
<html lang="en" class="ayu sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Platform Overview - Provisioning Platform Documentation</title>
<!-- Custom HTML head -->
<meta name="description" content="Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, KCL, and Rust">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../favicon.svg">
<link rel="shortcut icon" href="../favicon.png">
<link rel="stylesheet" href="../css/variables.css">
<link rel="stylesheet" href="../css/general.css">
<link rel="stylesheet" href="../css/chrome.css">
<link rel="stylesheet" href="../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root and default themes to javascript -->
<script>
const path_to_root = "../";
const default_light_theme = "ayu";
const default_dark_theme = "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../toc.js"></script>
</head>
<body>
<div id="mdbook-help-container">
<div id="mdbook-help-popup">
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
<div>
<p>Press <kbd></kbd> or <kbd></kbd> to navigate between chapters</p>
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
<p>Press <kbd>?</kbd> to show this help</p>
<p>Press <kbd>Esc</kbd> to hide this help</p>
</div>
</div>
</div>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
let theme = localStorage.getItem('mdbook-theme');
let sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
let theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('ayu')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
let sidebar = null;
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Provisioning Platform Documentation</h1>
<div class="right-buttons">
<a href="../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/provisioning/provisioning-platform" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/provisioning/provisioning-platform/edit/main/provisioning/docs/src/platform/README.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<h1 id="platform-services"><a class="header" href="#platform-services">Platform Services</a></h1>
<p>The Provisioning Platform consists of several microservices that work together to provide a complete infrastructure automation solution.</p>
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
<p>All platform services are built with Rust for performance, safety, and reliability. They expose REST APIs and integrate seamlessly with the Nushell-based CLI.</p>
<h2 id="core-services"><a class="header" href="#core-services">Core Services</a></h2>
<h3 id="orchestrator"><a class="header" href="#orchestrator"><a href="orchestrator.html">Orchestrator</a></a></h3>
<p><strong>Purpose</strong>: Workflow coordination and task management</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Hybrid Rust/Nushell architecture</li>
<li>Multi-storage backends (Filesystem, SurrealDB)</li>
<li>REST API for workflow submission</li>
<li>Test environment service for automated testing</li>
</ul>
<p><strong>Port</strong>: 8080<br />
<strong>Status</strong>: Production-ready</p>
<hr />
<h3 id="control-center"><a class="header" href="#control-center"><a href="control-center.html">Control Center</a></a></h3>
<p><strong>Purpose</strong>: Policy engine and security management</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Cedar policy evaluation</li>
<li>JWT authentication</li>
<li>MFA support</li>
<li>Compliance framework (SOC2, HIPAA)</li>
<li>Anomaly detection</li>
</ul>
<p><strong>Port</strong>: 9090<br />
<strong>Status</strong>: Production-ready</p>
<hr />
<h3 id="kms-service"><a class="header" href="#kms-service"><a href="kms-service.html">KMS Service</a></a></h3>
<p><strong>Purpose</strong>: Key management and encryption</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Multiple backends (Age, RustyVault, Cosmian, AWS KMS, Vault)</li>
<li>REST API for encryption operations</li>
<li>Nushell CLI integration</li>
<li>Context-based encryption</li>
</ul>
<p><strong>Port</strong>: 8082<br />
<strong>Status</strong>: Production-ready</p>
<hr />
<h3 id="api-server"><a class="header" href="#api-server"><a href="provisioning-server.html">API Server</a></a></h3>
<p><strong>Purpose</strong>: REST API for remote provisioning operations</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Comprehensive REST API</li>
<li>JWT authentication</li>
<li>RBAC system (Admin, Operator, Developer, Viewer)</li>
<li>Async operations with status tracking</li>
<li>Audit logging</li>
</ul>
<p><strong>Port</strong>: 8083<br />
<strong>Status</strong>: Production-ready</p>
<hr />
<h3 id="extension-registry"><a class="header" href="#extension-registry"><a href="extension-registry.html">Extension Registry</a></a></h3>
<p><strong>Purpose</strong>: Extension discovery and download</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Multi-backend support (Gitea, OCI)</li>
<li>Smart caching (LRU with TTL)</li>
<li>Prometheus metrics</li>
<li>Search functionality</li>
</ul>
<p><strong>Port</strong>: 8084<br />
<strong>Status</strong>: Production-ready</p>
<hr />
<h3 id="oci-registry"><a class="header" href="#oci-registry"><a href="oci-registry.html">OCI Registry</a></a></h3>
<p><strong>Purpose</strong>: Artifact storage and distribution</p>
<p><strong>Supported Registries</strong>:</p>
<ul>
<li>Zot (recommended for development)</li>
<li>Harbor (recommended for production)</li>
<li>Distribution (OCI reference)</li>
</ul>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Namespace organization</li>
<li>Access control</li>
<li>Garbage collection</li>
<li>High availability</li>
</ul>
<p><strong>Port</strong>: 5000<br />
<strong>Status</strong>: Production-ready</p>
<hr />
<h3 id="platform-installer"><a class="header" href="#platform-installer"><a href="installer.html">Platform Installer</a></a></h3>
<p><strong>Purpose</strong>: Interactive platform deployment</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Interactive Ratatui TUI</li>
<li>Headless mode for automation</li>
<li>Multiple deployment modes (Solo, Multi-User, CI/CD, Enterprise)</li>
<li>Platform-agnostic (Docker, Podman, Kubernetes, OrbStack)</li>
</ul>
<p><strong>Status</strong>: Complete (1,480 lines, 7 screens)</p>
<hr />
<h3 id="mcp-server"><a class="header" href="#mcp-server"><a href="mcp-server.html">MCP Server</a></a></h3>
<p><strong>Purpose</strong>: Model Context Protocol for AI integration</p>
<p><strong>Key Features</strong>:</p>
<ul>
<li>Rust-native implementation</li>
<li>1000x faster than Python version</li>
<li>AI-powered server parsing</li>
<li>Multi-provider support</li>
</ul>
<p><strong>Status</strong>: Proof of concept complete</p>
<hr />
<h2 id="architecture"><a class="header" href="#architecture">Architecture</a></h2>
<pre><code>┌─────────────────────────────────────────────────────────────┐
│ Provisioning Platform │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Orchestrator │ │Control Center│ │ API Server │ │
│ │ :8080 │ │ :9090 │ │ :8083 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────┴──────────────────┴──────────────────┴───────┐ │
│ │ Service Mesh / API Gateway │ │
│ └──────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────────────────────┐ │
│ │ KMS Service Extension Registry OCI Registry │ │
│ │ :8082 :8084 :5000 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
</code></pre>
<h2 id="deployment"><a class="header" href="#deployment">Deployment</a></h2>
<h3 id="starting-all-services"><a class="header" href="#starting-all-services">Starting All Services</a></h3>
<pre><code class="language-bash"># 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
</code></pre>
<h3 id="checking-service-status"><a class="header" href="#checking-service-status">Checking Service Status</a></h3>
<pre><code class="language-bash"># Check all services
provisioning platform status
# Check specific service
provisioning platform status orchestrator
# View service logs
provisioning platform logs orchestrator --tail 100 --follow
</code></pre>
<h3 id="service-health-checks"><a class="header" href="#service-health-checks">Service Health Checks</a></h3>
<p>Each service exposes a health endpoint:</p>
<pre><code class="language-bash"># 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/
</code></pre>
<h2 id="service-dependencies"><a class="header" href="#service-dependencies">Service Dependencies</a></h2>
<pre><code>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
</code></pre>
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
<p>Each service uses TOML-based configuration:</p>
<pre><code>provisioning/
├── config/
│ ├── orchestrator.toml
│ ├── control-center.toml
│ ├── kms.toml
│ ├── api-server.toml
│ ├── extension-registry.toml
│ └── oci-registry.toml
</code></pre>
<h2 id="monitoring"><a class="header" href="#monitoring">Monitoring</a></h2>
<h3 id="metrics-collection"><a class="header" href="#metrics-collection">Metrics Collection</a></h3>
<p>Services expose Prometheus metrics:</p>
<pre><code class="language-yaml"># 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']
</code></pre>
<h3 id="logging"><a class="header" href="#logging">Logging</a></h3>
<p>All services use structured logging:</p>
<pre><code class="language-bash"># 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
</code></pre>
<h2 id="security"><a class="header" href="#security">Security</a></h2>
<h3 id="authentication"><a class="header" href="#authentication">Authentication</a></h3>
<ul>
<li><strong>JWT Tokens</strong>: Used by API Server and Control Center</li>
<li><strong>API Keys</strong>: Used by Extension Registry</li>
<li><strong>mTLS</strong>: Optional for service-to-service communication</li>
</ul>
<h3 id="encryption"><a class="header" href="#encryption">Encryption</a></h3>
<ul>
<li><strong>TLS/SSL</strong>: All HTTP endpoints support TLS</li>
<li><strong>At-Rest</strong>: KMS Service handles encryption keys</li>
<li><strong>In-Transit</strong>: Network traffic encrypted with TLS</li>
</ul>
<h3 id="access-control"><a class="header" href="#access-control">Access Control</a></h3>
<ul>
<li><strong>RBAC</strong>: Control Center provides role-based access</li>
<li><strong>Policies</strong>: Cedar policies enforce fine-grained permissions</li>
<li><strong>Audit Logging</strong>: All operations logged for compliance</li>
</ul>
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
<h3 id="service-wont-start"><a class="header" href="#service-wont-start">Service Wont Start</a></h3>
<pre><code class="language-bash"># Check logs
provisioning platform logs &lt;service&gt; --tail 100
# Verify configuration
provisioning validate config --service &lt;service&gt;
# Check port availability
lsof -i :&lt;port&gt;
</code></pre>
<h3 id="service-unhealthy"><a class="header" href="#service-unhealthy">Service Unhealthy</a></h3>
<pre><code class="language-bash"># Check dependencies
provisioning platform deps &lt;service&gt;
# Restart service
provisioning platform restart &lt;service&gt;
# Full service reset
provisioning platform restart &lt;service&gt; --clean
</code></pre>
<h3 id="high-resource-usage"><a class="header" href="#high-resource-usage">High Resource Usage</a></h3>
<pre><code class="language-bash"># Check resource usage
provisioning platform resources
# View detailed metrics
provisioning platform metrics &lt;service&gt;
</code></pre>
<h2 id="related-documentation"><a class="header" href="#related-documentation">Related Documentation</a></h2>
<ul>
<li><strong><a href="../architecture/ARCHITECTURE_OVERVIEW.html">Architecture Overview</a></strong></li>
<li><strong><a href="../architecture/integration-patterns.html">Integration Patterns</a></strong></li>
<li><strong><a href="../user/SERVICE_MANAGEMENT_GUIDE.html">Service Management Guide</a></strong></li>
<li><strong><a href="../api/rest-api.html">API Reference</a></strong></li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../architecture/orchestrator-auth-integration.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../platform/orchestrator.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../architecture/orchestrator-auth-integration.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../platform/orchestrator.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<!-- Livereload script (if served using the cli tool) -->
<script>
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
const socket = new WebSocket(wsAddress);
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload();
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
<script>
window.playground_copyable = true;
</script>
<script src="../elasticlunr.min.js"></script>
<script src="../mark.min.js"></script>
<script src="../searcher.js"></script>
<script src="../clipboard.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>