6a59d34bb1
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.
1084 lines
55 KiB
HTML
1084 lines
55 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Main Provisioning Document - 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/PROVISIONING.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>
|
||
<p align="center">
|
||
<img src="resources/provisioning_logo.svg" alt="Provisioning Logo" width="300"/>
|
||
</p>
|
||
<p align="center">
|
||
<img src="resources/logo-text.svg" alt="Provisioning" width="500"/>
|
||
</p>
|
||
<h1 id="provisioning---infrastructure-automation-platform"><a class="header" href="#provisioning---infrastructure-automation-platform">Provisioning - Infrastructure Automation Platform</a></h1>
|
||
<blockquote>
|
||
<p><strong>A modular, declarative Infrastructure as Code (IaC) platform for managing complete infrastructure lifecycles</strong></p>
|
||
</blockquote>
|
||
<h2 id="table-of-contents"><a class="header" href="#table-of-contents">Table of Contents</a></h2>
|
||
<ul>
|
||
<li><a href="#what-is-provisioning">What is Provisioning?</a></li>
|
||
<li><a href="#why-provisioning">Why Provisioning?</a></li>
|
||
<li><a href="#core-concepts">Core Concepts</a></li>
|
||
<li><a href="#architecture">Architecture</a></li>
|
||
<li><a href="#key-features">Key Features</a></li>
|
||
<li><a href="#technology-stack">Technology Stack</a></li>
|
||
<li><a href="#how-it-works">How It Works</a></li>
|
||
<li><a href="#use-cases">Use Cases</a></li>
|
||
<li><a href="#getting-started">Getting Started</a></li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="what-is-provisioning"><a class="header" href="#what-is-provisioning">What is Provisioning?</a></h2>
|
||
<p><strong>Provisioning</strong> is a comprehensive <strong>Infrastructure as Code (IaC)</strong> platform designed to manage complete infrastructure lifecycles: cloud providers, infrastructure services, clusters, and isolated workspaces across multiple cloud/local environments.</p>
|
||
<p>Extensible and customizable by design, it delivers type-safe, configuration-driven workflows with enterprise security (encrypted configuration, Cosmian KMS integration, Cedar policy engine, secrets management, authorization and permissions control, compliance checking, anomaly detection) and adaptable deployment modes (interactive UI, CLI automation, unattended CI/CD) suitable for any scale from development to production.</p>
|
||
<h3 id="technical-definition"><a class="header" href="#technical-definition">Technical Definition</a></h3>
|
||
<p>Declarative Infrastructure as Code (IaC) platform providing:</p>
|
||
<ul>
|
||
<li><strong>Type-safe, configuration-driven workflows</strong> with schema validation and constraint checking</li>
|
||
<li><strong>Modular, extensible architecture</strong>: cloud providers, task services, clusters, workspaces</li>
|
||
<li><strong>Multi-cloud abstraction layer</strong> with unified API (UpCloud, AWS, local infrastructure)</li>
|
||
<li><strong>High-performance state management</strong>:
|
||
<ul>
|
||
<li>Graph database backend for complex relationships</li>
|
||
<li>Real-time state tracking and queries</li>
|
||
<li>Multi-model data storage (document, graph, relational)</li>
|
||
</ul>
|
||
</li>
|
||
<li><strong>Enterprise security stack</strong>:
|
||
<ul>
|
||
<li>Encrypted configuration and secrets management</li>
|
||
<li>Cosmian KMS integration for confidential key management</li>
|
||
<li>Cedar policy engine for fine-grained access control</li>
|
||
<li>Authorization and permissions control via platform services</li>
|
||
<li>Compliance checking and policy enforcement</li>
|
||
<li>Anomaly detection for security monitoring</li>
|
||
<li>Audit logging and compliance tracking</li>
|
||
</ul>
|
||
</li>
|
||
<li><strong>Hybrid orchestration</strong>: Rust-based performance layer + scripting flexibility</li>
|
||
<li><strong>Production-ready features</strong>:
|
||
<ul>
|
||
<li>Batch workflows with dependency resolution</li>
|
||
<li>Checkpoint recovery and automatic rollback</li>
|
||
<li>Parallel execution with state management</li>
|
||
</ul>
|
||
</li>
|
||
<li><strong>Adaptable deployment modes</strong>:
|
||
<ul>
|
||
<li>Interactive TUI for guided setup</li>
|
||
<li>Headless CLI for scripted automation</li>
|
||
<li>Unattended mode for CI/CD pipelines</li>
|
||
</ul>
|
||
</li>
|
||
<li><strong>Hierarchical configuration system</strong> with inheritance and overrides</li>
|
||
</ul>
|
||
<h3 id="what-it-does"><a class="header" href="#what-it-does">What It Does</a></h3>
|
||
<ul>
|
||
<li><strong>Provisions Infrastructure</strong> - Create servers, networks, storage across multiple cloud providers</li>
|
||
<li><strong>Installs Services</strong> - Deploy Kubernetes, containerd, databases, monitoring, and 50+ infrastructure components</li>
|
||
<li><strong>Manages Clusters</strong> - Orchestrate complete cluster deployments with dependency management</li>
|
||
<li><strong>Handles Configuration</strong> - Hierarchical configuration system with inheritance and overrides</li>
|
||
<li><strong>Orchestrates Workflows</strong> - Batch operations with parallel execution and checkpoint recovery</li>
|
||
<li><strong>Manages Secrets</strong> - SOPS/Age integration for encrypted configuration</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="why-provisioning"><a class="header" href="#why-provisioning">Why Provisioning?</a></h2>
|
||
<h3 id="the-problems-it-solves"><a class="header" href="#the-problems-it-solves">The Problems It Solves</a></h3>
|
||
<h4 id="1-multi-cloud-complexity"><a class="header" href="#1-multi-cloud-complexity">1. <strong>Multi-Cloud Complexity</strong></a></h4>
|
||
<p><strong>Problem</strong>: Each cloud provider has different APIs, tools, and workflows.</p>
|
||
<p><strong>Solution</strong>: Unified abstraction layer with provider-agnostic interfaces. Write configuration once, deploy anywhere.</p>
|
||
<pre><code class="language-kcl"># Same configuration works on UpCloud, AWS, or local infrastructure
|
||
server: Server {
|
||
name = "web-01"
|
||
plan = "medium" # Abstract size, provider-specific translation
|
||
provider = "upcloud" # Switch to "aws" or "local" as needed
|
||
}
|
||
</code></pre>
|
||
<h4 id="2-dependency-hell"><a class="header" href="#2-dependency-hell">2. <strong>Dependency Hell</strong></a></h4>
|
||
<p><strong>Problem</strong>: Infrastructure components have complex dependencies (Kubernetes needs containerd, Cilium needs Kubernetes, etc.).</p>
|
||
<p><strong>Solution</strong>: Automatic dependency resolution with topological sorting and health checks.</p>
|
||
<pre><code class="language-kcl"># Provisioning resolves: containerd → etcd → kubernetes → cilium
|
||
taskservs = ["cilium"] # Automatically installs all dependencies
|
||
</code></pre>
|
||
<h4 id="3-configuration-sprawl"><a class="header" href="#3-configuration-sprawl">3. <strong>Configuration Sprawl</strong></a></h4>
|
||
<p><strong>Problem</strong>: Environment variables, hardcoded values, scattered configuration files.</p>
|
||
<p><strong>Solution</strong>: Hierarchical configuration system with 476+ config accessors replacing 200+ ENV variables.</p>
|
||
<pre><code>Defaults → User → Project → Infrastructure → Environment → Runtime
|
||
</code></pre>
|
||
<h4 id="4-imperative-scripts"><a class="header" href="#4-imperative-scripts">4. <strong>Imperative Scripts</strong></a></h4>
|
||
<p><strong>Problem</strong>: Brittle shell scripts that don’t handle failures, don’t support rollback, hard to maintain.</p>
|
||
<p><strong>Solution</strong>: Declarative KCL configurations with validation, type safety, and automatic rollback.</p>
|
||
<h4 id="5-lack-of-visibility"><a class="header" href="#5-lack-of-visibility">5. <strong>Lack of Visibility</strong></a></h4>
|
||
<p><strong>Problem</strong>: No insight into what’s happening during deployment, hard to debug failures.</p>
|
||
<p><strong>Solution</strong>:</p>
|
||
<ul>
|
||
<li>Real-time workflow monitoring</li>
|
||
<li>Comprehensive logging system</li>
|
||
<li>Web-based control center</li>
|
||
<li>REST API for integration</li>
|
||
</ul>
|
||
<h4 id="6-no-standardization"><a class="header" href="#6-no-standardization">6. <strong>No Standardization</strong></a></h4>
|
||
<p><strong>Problem</strong>: Each team builds their own deployment tools, no shared patterns.</p>
|
||
<p><strong>Solution</strong>: Reusable task services, cluster templates, and workflow patterns.</p>
|
||
<hr />
|
||
<h2 id="core-concepts"><a class="header" href="#core-concepts">Core Concepts</a></h2>
|
||
<h3 id="1-providers"><a class="header" href="#1-providers">1. <strong>Providers</strong></a></h3>
|
||
<p>Cloud infrastructure backends that handle resource provisioning.</p>
|
||
<ul>
|
||
<li><strong>UpCloud</strong> - Primary cloud provider</li>
|
||
<li><strong>AWS</strong> - Amazon Web Services integration</li>
|
||
<li><strong>Local</strong> - Local infrastructure (VMs, Docker, bare metal)</li>
|
||
</ul>
|
||
<p>Providers implement a common interface, making infrastructure code portable.</p>
|
||
<h3 id="2-task-services-taskservs"><a class="header" href="#2-task-services-taskservs">2. <strong>Task Services (TaskServs)</strong></a></h3>
|
||
<p>Reusable infrastructure components that can be installed on servers.</p>
|
||
<p><strong>Categories</strong>:</p>
|
||
<ul>
|
||
<li><strong>Container Runtimes</strong> - containerd, Docker, Podman, crun, runc, youki</li>
|
||
<li><strong>Orchestration</strong> - Kubernetes, etcd, CoreDNS</li>
|
||
<li><strong>Networking</strong> - Cilium, Flannel, Calico, ip-aliases</li>
|
||
<li><strong>Storage</strong> - Rook-Ceph, local storage</li>
|
||
<li><strong>Databases</strong> - PostgreSQL, Redis, SurrealDB</li>
|
||
<li><strong>Observability</strong> - Prometheus, Grafana, Loki</li>
|
||
<li><strong>Security</strong> - Webhook, KMS, Vault</li>
|
||
<li><strong>Development</strong> - Gitea, Radicle, ORAS</li>
|
||
</ul>
|
||
<p>Each task service includes:</p>
|
||
<ul>
|
||
<li>Version management</li>
|
||
<li>Dependency declarations</li>
|
||
<li>Health checks</li>
|
||
<li>Installation/uninstallation logic</li>
|
||
<li>Configuration schemas</li>
|
||
</ul>
|
||
<h3 id="3-clusters"><a class="header" href="#3-clusters">3. <strong>Clusters</strong></a></h3>
|
||
<p>Complete infrastructure deployments combining servers and task services.</p>
|
||
<p><strong>Examples</strong>:</p>
|
||
<ul>
|
||
<li><strong>Kubernetes Cluster</strong> - HA control plane + worker nodes + CNI + storage</li>
|
||
<li><strong>Database Cluster</strong> - Replicated PostgreSQL with backup</li>
|
||
<li><strong>Build Infrastructure</strong> - BuildKit + container registry + CI/CD</li>
|
||
</ul>
|
||
<p>Clusters handle:</p>
|
||
<ul>
|
||
<li>Multi-node coordination</li>
|
||
<li>Service distribution</li>
|
||
<li>High availability</li>
|
||
<li>Rolling updates</li>
|
||
</ul>
|
||
<h3 id="4-workspaces"><a class="header" href="#4-workspaces">4. <strong>Workspaces</strong></a></h3>
|
||
<p>Isolated environments for different projects or deployment stages.</p>
|
||
<pre><code>workspace_librecloud/ # Production workspace
|
||
├── infra/ # Infrastructure definitions
|
||
├── config/ # Workspace configuration
|
||
├── extensions/ # Custom modules
|
||
└── runtime/ # State and runtime data
|
||
|
||
workspace_dev/ # Development workspace
|
||
├── infra/
|
||
└── config/
|
||
</code></pre>
|
||
<p>Switch between workspaces with single command:</p>
|
||
<pre><code class="language-bash">provisioning workspace switch librecloud
|
||
</code></pre>
|
||
<h3 id="5-workflows"><a class="header" href="#5-workflows">5. <strong>Workflows</strong></a></h3>
|
||
<p>Coordinated sequences of operations with dependency management.</p>
|
||
<p><strong>Types</strong>:</p>
|
||
<ul>
|
||
<li><strong>Server Workflows</strong> - Create/delete/update servers</li>
|
||
<li><strong>TaskServ Workflows</strong> - Install/remove infrastructure services</li>
|
||
<li><strong>Cluster Workflows</strong> - Deploy/scale complete clusters</li>
|
||
<li><strong>Batch Workflows</strong> - Multi-cloud parallel operations</li>
|
||
</ul>
|
||
<p><strong>Features</strong>:</p>
|
||
<ul>
|
||
<li>Dependency resolution</li>
|
||
<li>Parallel execution</li>
|
||
<li>Checkpoint recovery</li>
|
||
<li>Automatic rollback</li>
|
||
<li>Progress monitoring</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="architecture"><a class="header" href="#architecture">Architecture</a></h2>
|
||
<h3 id="system-components"><a class="header" href="#system-components">System Components</a></h3>
|
||
<pre><code>┌─────────────────────────────────────────────────────────────────┐
|
||
│ User Interface Layer │
|
||
│ • CLI (provisioning command) │
|
||
│ • Web Control Center (UI) │
|
||
│ • REST API │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Core Engine Layer │
|
||
│ • Command Routing & Dispatch │
|
||
│ • Configuration Management │
|
||
│ • Provider Abstraction │
|
||
│ • Utility Libraries │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Orchestration Layer │
|
||
│ • Workflow Orchestrator (Rust/Nushell hybrid) │
|
||
│ • Dependency Resolver │
|
||
│ • State Manager │
|
||
│ • Task Scheduler │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Extension Layer │
|
||
│ • Providers (Cloud APIs) │
|
||
│ • Task Services (Infrastructure Components) │
|
||
│ • Clusters (Complete Deployments) │
|
||
│ • Workflows (Automation Templates) │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Infrastructure Layer │
|
||
│ • Cloud Resources (Servers, Networks, Storage) │
|
||
│ • Kubernetes Clusters │
|
||
│ • Running Services │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
</code></pre>
|
||
<h3 id="directory-structure"><a class="header" href="#directory-structure">Directory Structure</a></h3>
|
||
<pre><code>project-provisioning/
|
||
├── provisioning/ # Core provisioning system
|
||
│ ├── core/ # Core engine and libraries
|
||
│ │ ├── cli/ # Command-line interface
|
||
│ │ ├── nulib/ # Core Nushell libraries
|
||
│ │ ├── plugins/ # System plugins
|
||
│ │ └── scripts/ # Utility scripts
|
||
│ │
|
||
│ ├── extensions/ # Extensible components
|
||
│ │ ├── providers/ # Cloud provider implementations
|
||
│ │ ├── taskservs/ # Infrastructure service definitions
|
||
│ │ ├── clusters/ # Complete cluster configurations
|
||
│ │ └── workflows/ # Core workflow templates
|
||
│ │
|
||
│ ├── platform/ # Platform services
|
||
│ │ ├── orchestrator/ # Rust orchestrator service
|
||
│ │ ├── control-center/ # Web control center
|
||
│ │ ├── mcp-server/ # Model Context Protocol server
|
||
│ │ ├── api-gateway/ # REST API gateway
|
||
│ │ ├── oci-registry/ # OCI registry for extensions
|
||
│ │ └── installer/ # Platform installer (TUI + CLI)
|
||
│ │
|
||
│ ├── kcl/ # KCL configuration schemas
|
||
│ ├── config/ # Configuration files
|
||
│ ├── templates/ # Template files
|
||
│ └── tools/ # Build and distribution tools
|
||
│
|
||
├── workspace/ # User workspaces and data
|
||
│ ├── infra/ # Infrastructure definitions
|
||
│ ├── config/ # User configuration
|
||
│ ├── extensions/ # User extensions
|
||
│ └── runtime/ # Runtime data and state
|
||
│
|
||
└── docs/ # Documentation
|
||
├── user/ # User guides
|
||
├── api/ # API documentation
|
||
├── architecture/ # Architecture docs
|
||
└── development/ # Development guides
|
||
</code></pre>
|
||
<h3 id="platform-services"><a class="header" href="#platform-services">Platform Services</a></h3>
|
||
<h4 id="1-orchestrator-platformorchestrator"><a class="header" href="#1-orchestrator-platformorchestrator">1. <strong>Orchestrator</strong> (<code>platform/orchestrator/</code>)</a></h4>
|
||
<ul>
|
||
<li><strong>Language</strong>: Rust + Nushell</li>
|
||
<li><strong>Purpose</strong>: Workflow execution, task scheduling, state management</li>
|
||
<li><strong>Features</strong>:
|
||
<ul>
|
||
<li>File-based persistence</li>
|
||
<li>Priority processing</li>
|
||
<li>Retry logic with exponential backoff</li>
|
||
<li>Checkpoint-based recovery</li>
|
||
<li>REST API endpoints</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="2-control-center-platformcontrol-center"><a class="header" href="#2-control-center-platformcontrol-center">2. <strong>Control Center</strong> (<code>platform/control-center/</code>)</a></h4>
|
||
<ul>
|
||
<li><strong>Language</strong>: Web UI + Backend API</li>
|
||
<li><strong>Purpose</strong>: Web-based infrastructure management</li>
|
||
<li><strong>Features</strong>:
|
||
<ul>
|
||
<li>Dashboard views</li>
|
||
<li>Real-time monitoring</li>
|
||
<li>Interactive deployments</li>
|
||
<li>Log viewing</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="3-mcp-server-platformmcp-server"><a class="header" href="#3-mcp-server-platformmcp-server">3. <strong>MCP Server</strong> (<code>platform/mcp-server/</code>)</a></h4>
|
||
<ul>
|
||
<li><strong>Language</strong>: Nushell</li>
|
||
<li><strong>Purpose</strong>: Model Context Protocol integration for AI assistance</li>
|
||
<li><strong>Features</strong>:
|
||
<ul>
|
||
<li>7 AI-powered settings tools</li>
|
||
<li>Intelligent config completion</li>
|
||
<li>Natural language infrastructure queries</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="4-oci-registry-platformoci-registry"><a class="header" href="#4-oci-registry-platformoci-registry">4. <strong>OCI Registry</strong> (<code>platform/oci-registry/</code>)</a></h4>
|
||
<ul>
|
||
<li><strong>Purpose</strong>: Extension distribution and versioning</li>
|
||
<li><strong>Features</strong>:
|
||
<ul>
|
||
<li>Task service packages</li>
|
||
<li>Provider packages</li>
|
||
<li>Cluster templates</li>
|
||
<li>Workflow definitions</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="5-installer-platforminstaller"><a class="header" href="#5-installer-platforminstaller">5. <strong>Installer</strong> (<code>platform/installer/</code>)</a></h4>
|
||
<ul>
|
||
<li><strong>Language</strong>: Rust (Ratatui TUI) + Nushell</li>
|
||
<li><strong>Purpose</strong>: Platform installation and setup</li>
|
||
<li><strong>Features</strong>:
|
||
<ul>
|
||
<li>Interactive TUI mode</li>
|
||
<li>Headless CLI mode</li>
|
||
<li>Unattended CI/CD mode</li>
|
||
<li>Configuration generation</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="key-features"><a class="header" href="#key-features">Key Features</a></h2>
|
||
<h3 id="1-modular-cli-architecture-v320"><a class="header" href="#1-modular-cli-architecture-v320">1. <strong>Modular CLI Architecture</strong> (v3.2.0)</a></h3>
|
||
<p>84% code reduction with domain-driven design.</p>
|
||
<ul>
|
||
<li><strong>Main CLI</strong>: 211 lines (from 1,329 lines)</li>
|
||
<li><strong>80+ shortcuts</strong>: <code>s</code> → <code>server</code>, <code>t</code> → <code>taskserv</code>, etc.</li>
|
||
<li><strong>Bi-directional help</strong>: <code>provisioning help ws</code> = <code>provisioning ws help</code></li>
|
||
<li><strong>7 domain modules</strong>: infrastructure, orchestration, development, workspace, configuration, utilities, generation</li>
|
||
</ul>
|
||
<h3 id="2-configuration-system-v200"><a class="header" href="#2-configuration-system-v200">2. <strong>Configuration System</strong> (v2.0.0)</a></h3>
|
||
<p>Hierarchical, config-driven architecture.</p>
|
||
<ul>
|
||
<li><strong>476+ config accessors</strong> replacing 200+ ENV variables</li>
|
||
<li><strong>Hierarchical loading</strong>: defaults → user → project → infra → env → runtime</li>
|
||
<li><strong>Variable interpolation</strong>: <code>{{paths.base}}</code>, <code>{{env.HOME}}</code>, <code>{{now.date}}</code></li>
|
||
<li><strong>Multi-format support</strong>: TOML, YAML, KCL</li>
|
||
</ul>
|
||
<h3 id="3-batch-workflow-system-v310"><a class="header" href="#3-batch-workflow-system-v310">3. <strong>Batch Workflow System</strong> (v3.1.0)</a></h3>
|
||
<p>Provider-agnostic batch operations with 85-90% token efficiency.</p>
|
||
<ul>
|
||
<li><strong>Multi-cloud support</strong>: Mixed UpCloud + AWS + local in single workflow</li>
|
||
<li><strong>KCL schema integration</strong>: Type-safe workflow definitions</li>
|
||
<li><strong>Dependency resolution</strong>: Topological sorting with soft/hard dependencies</li>
|
||
<li><strong>State management</strong>: Checkpoint-based recovery with rollback</li>
|
||
<li><strong>Real-time monitoring</strong>: Live progress tracking</li>
|
||
</ul>
|
||
<h3 id="4-hybrid-orchestrator-v300"><a class="header" href="#4-hybrid-orchestrator-v300">4. <strong>Hybrid Orchestrator</strong> (v3.0.0)</a></h3>
|
||
<p>Rust/Nushell architecture solving deep call stack limitations.</p>
|
||
<ul>
|
||
<li><strong>High-performance coordination layer</strong></li>
|
||
<li><strong>File-based persistence</strong></li>
|
||
<li><strong>Priority processing with retry logic</strong></li>
|
||
<li><strong>REST API for external integration</strong></li>
|
||
<li><strong>Comprehensive workflow system</strong></li>
|
||
</ul>
|
||
<h3 id="5-workspace-switching-v205"><a class="header" href="#5-workspace-switching-v205">5. <strong>Workspace Switching</strong> (v2.0.5)</a></h3>
|
||
<p>Centralized workspace management.</p>
|
||
<ul>
|
||
<li><strong>Single-command switching</strong>: <code>provisioning workspace switch <name></code></li>
|
||
<li><strong>Automatic tracking</strong>: Last-used timestamps, active workspace markers</li>
|
||
<li><strong>User preferences</strong>: Global settings across all workspaces</li>
|
||
<li><strong>Workspace registry</strong>: Centralized configuration in <code>user_config.yaml</code></li>
|
||
</ul>
|
||
<h3 id="6-interactive-guides-v330"><a class="header" href="#6-interactive-guides-v330">6. <strong>Interactive Guides</strong> (v3.3.0)</a></h3>
|
||
<p>Step-by-step walkthroughs and quick references.</p>
|
||
<ul>
|
||
<li><strong>Quick reference</strong>: <code>provisioning sc</code> (fastest)</li>
|
||
<li><strong>Complete guides</strong>: from-scratch, update, customize</li>
|
||
<li><strong>Copy-paste ready</strong>: All commands include placeholders</li>
|
||
<li><strong>Beautiful rendering</strong>: Uses glow, bat, or less</li>
|
||
</ul>
|
||
<h3 id="7-test-environment-service-v340"><a class="header" href="#7-test-environment-service-v340">7. <strong>Test Environment Service</strong> (v3.4.0)</a></h3>
|
||
<p>Automated container-based testing.</p>
|
||
<ul>
|
||
<li><strong>Three test types</strong>: Single taskserv, server simulation, multi-node clusters</li>
|
||
<li><strong>Topology templates</strong>: Kubernetes HA, etcd clusters, etc.</li>
|
||
<li><strong>Auto-cleanup</strong>: Optional automatic cleanup after tests</li>
|
||
<li><strong>CI/CD integration</strong>: Easy integration into pipelines</li>
|
||
</ul>
|
||
<h3 id="8-platform-installer-v350"><a class="header" href="#8-platform-installer-v350">8. <strong>Platform Installer</strong> (v3.5.0)</a></h3>
|
||
<p>Multi-mode installation system with TUI, CLI, and unattended modes.</p>
|
||
<ul>
|
||
<li><strong>Interactive TUI</strong>: Beautiful Ratatui terminal UI with 7 screens</li>
|
||
<li><strong>Headless Mode</strong>: CLI automation for scripted installations</li>
|
||
<li><strong>Unattended Mode</strong>: Zero-interaction CI/CD deployments</li>
|
||
<li><strong>Deployment Modes</strong>: Solo (2 CPU/4GB), MultiUser (4 CPU/8GB), CICD (8 CPU/16GB), Enterprise (16 CPU/32GB)</li>
|
||
<li><strong>MCP Integration</strong>: 7 AI-powered settings tools for intelligent configuration</li>
|
||
</ul>
|
||
<h3 id="9-version-management"><a class="header" href="#9-version-management">9. <strong>Version Management</strong></a></h3>
|
||
<p>Comprehensive version tracking and updates.</p>
|
||
<ul>
|
||
<li><strong>Automatic updates</strong>: Check for taskserv updates</li>
|
||
<li><strong>Version constraints</strong>: Semantic versioning support</li>
|
||
<li><strong>Grace periods</strong>: Cached version checks</li>
|
||
<li><strong>Update strategies</strong>: major, minor, patch, none</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="technology-stack"><a class="header" href="#technology-stack">Technology Stack</a></h2>
|
||
<h3 id="core-technologies"><a class="header" href="#core-technologies">Core Technologies</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Technology</th><th>Version</th><th>Purpose</th><th>Why</th></tr></thead><tbody>
|
||
<tr><td><strong>Nushell</strong></td><td>0.107.1+</td><td>Primary shell and scripting language</td><td>Structured data pipelines, cross-platform, modern built-in parsers (JSON/YAML/TOML)</td></tr>
|
||
<tr><td><strong>KCL</strong></td><td>0.11.3+</td><td>Configuration language</td><td>Type safety, schema validation, immutability, constraint checking</td></tr>
|
||
<tr><td><strong>Rust</strong></td><td>Latest</td><td>Platform services (orchestrator, control-center, installer)</td><td>Performance, memory safety, concurrency, reliability</td></tr>
|
||
<tr><td><strong>Tera</strong></td><td>Latest</td><td>Template engine</td><td>Jinja2-like syntax, configuration file rendering, variable interpolation, filters and functions</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h3 id="data--state-management"><a class="header" href="#data--state-management">Data & State Management</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Technology</th><th>Version</th><th>Purpose</th><th>Features</th></tr></thead><tbody>
|
||
<tr><td><strong>SurrealDB</strong></td><td>Latest</td><td>High-performance graph database backend</td><td>Multi-model (document, graph, relational), real-time queries, distributed architecture, complex relationship tracking</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h3 id="platform-services-rust-based"><a class="header" href="#platform-services-rust-based">Platform Services (Rust-based)</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Service</th><th>Purpose</th><th>Security Features</th></tr></thead><tbody>
|
||
<tr><td><strong>Orchestrator</strong></td><td>Workflow execution, task scheduling, state management</td><td>File-based persistence, retry logic, checkpoint recovery</td></tr>
|
||
<tr><td><strong>Control Center</strong></td><td>Web-based infrastructure management</td><td><strong>Authorization and permissions control</strong>, RBAC, audit logging</td></tr>
|
||
<tr><td><strong>Installer</strong></td><td>Platform installation (TUI + CLI modes)</td><td>Secure configuration generation, validation</td></tr>
|
||
<tr><td><strong>API Gateway</strong></td><td>REST API for external integration</td><td>Authentication, rate limiting, request validation</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h3 id="security--secrets"><a class="header" href="#security--secrets">Security & Secrets</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Technology</th><th>Version</th><th>Purpose</th><th>Enterprise Features</th></tr></thead><tbody>
|
||
<tr><td><strong>SOPS</strong></td><td>3.10.2+</td><td>Secrets management</td><td>Encrypted configuration files</td></tr>
|
||
<tr><td><strong>Age</strong></td><td>1.2.1+</td><td>Encryption</td><td>Secure key-based encryption</td></tr>
|
||
<tr><td><strong>Cosmian KMS</strong></td><td>Latest</td><td>Key Management System</td><td>Confidential computing, secure key storage, cloud-native KMS</td></tr>
|
||
<tr><td><strong>Cedar</strong></td><td>Latest</td><td>Policy engine</td><td>Fine-grained access control, policy-as-code, compliance checking, anomaly detection</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h3 id="optional-tools"><a class="header" href="#optional-tools">Optional Tools</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Tool</th><th>Purpose</th></tr></thead><tbody>
|
||
<tr><td><strong>K9s</strong></td><td>Kubernetes management interface</td></tr>
|
||
<tr><td><strong>nu_plugin_tera</strong></td><td>Nushell plugin for Tera template rendering</td></tr>
|
||
<tr><td><strong>nu_plugin_kcl</strong></td><td>Nushell plugin for KCL integration (CLI required, plugin optional)</td></tr>
|
||
<tr><td><strong>glow</strong></td><td>Markdown rendering for interactive guides</td></tr>
|
||
<tr><td><strong>bat</strong></td><td>Syntax highlighting for file viewing and guides</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<hr />
|
||
<h2 id="how-it-works"><a class="header" href="#how-it-works">How It Works</a></h2>
|
||
<h3 id="data-flow"><a class="header" href="#data-flow">Data Flow</a></h3>
|
||
<pre><code>1. User defines infrastructure in KCL
|
||
↓
|
||
2. CLI loads configuration (hierarchical)
|
||
↓
|
||
3. Configuration validated against schemas
|
||
↓
|
||
4. Workflow created with operations
|
||
↓
|
||
5. Orchestrator receives workflow
|
||
↓
|
||
6. Dependencies resolved (topological sort)
|
||
↓
|
||
7. Operations executed in order
|
||
↓
|
||
8. Providers handle cloud operations
|
||
↓
|
||
9. Task services installed on servers
|
||
↓
|
||
10. State persisted and monitored
|
||
</code></pre>
|
||
<h3 id="example-workflow-deploy-kubernetes-cluster"><a class="header" href="#example-workflow-deploy-kubernetes-cluster">Example Workflow: Deploy Kubernetes Cluster</a></h3>
|
||
<p><strong>Step 1</strong>: Define infrastructure in KCL</p>
|
||
<pre><code class="language-kcl"># infra/my-cluster.k
|
||
import provisioning.settings as cfg
|
||
|
||
settings: cfg.Settings = {
|
||
infra = {
|
||
name = "my-cluster"
|
||
provider = "upcloud"
|
||
}
|
||
|
||
servers = [
|
||
{name = "control-01", plan = "medium", role = "control"}
|
||
{name = "worker-01", plan = "large", role = "worker"}
|
||
{name = "worker-02", plan = "large", role = "worker"}
|
||
]
|
||
|
||
taskservs = ["kubernetes", "cilium", "rook-ceph"]
|
||
}
|
||
</code></pre>
|
||
<p><strong>Step 2</strong>: Submit to Provisioning</p>
|
||
<pre><code class="language-bash">provisioning server create --infra my-cluster
|
||
</code></pre>
|
||
<p><strong>Step 3</strong>: Provisioning executes workflow</p>
|
||
<pre><code>1. Create workflow: "deploy-my-cluster"
|
||
2. Resolve dependencies:
|
||
- containerd (required by kubernetes)
|
||
- etcd (required by kubernetes)
|
||
- kubernetes (explicitly requested)
|
||
- cilium (explicitly requested, requires kubernetes)
|
||
- rook-ceph (explicitly requested, requires kubernetes)
|
||
|
||
3. Execution order:
|
||
a. Provision servers (parallel)
|
||
b. Install containerd on all nodes
|
||
c. Install etcd on control nodes
|
||
d. Install kubernetes control plane
|
||
e. Join worker nodes
|
||
f. Install Cilium CNI
|
||
g. Install Rook-Ceph storage
|
||
|
||
4. Checkpoint after each step
|
||
5. Monitor health checks
|
||
6. Report completion
|
||
</code></pre>
|
||
<p><strong>Step 4</strong>: Verify deployment</p>
|
||
<pre><code class="language-bash">provisioning cluster status my-cluster
|
||
</code></pre>
|
||
<h3 id="configuration-hierarchy"><a class="header" href="#configuration-hierarchy">Configuration Hierarchy</a></h3>
|
||
<p>Configuration values are resolved through a hierarchy:</p>
|
||
<pre><code>1. System Defaults (provisioning/config/config.defaults.toml)
|
||
↓ (overridden by)
|
||
2. User Preferences (~/.config/provisioning/user_config.yaml)
|
||
↓ (overridden by)
|
||
3. Workspace Config (workspace/config/provisioning.yaml)
|
||
↓ (overridden by)
|
||
4. Infrastructure Config (workspace/infra/<name>/config.toml)
|
||
↓ (overridden by)
|
||
5. Environment Config (workspace/config/prod-defaults.toml)
|
||
↓ (overridden by)
|
||
6. Runtime Flags (--flag value)
|
||
</code></pre>
|
||
<p><strong>Example</strong>:</p>
|
||
<pre><code class="language-toml"># System default
|
||
[servers]
|
||
default_plan = "small"
|
||
|
||
# User preference
|
||
[servers]
|
||
default_plan = "medium" # Overrides system default
|
||
|
||
# Infrastructure config
|
||
[servers]
|
||
default_plan = "large" # Overrides user preference
|
||
|
||
# Runtime
|
||
provisioning server create --plan xlarge # Overrides everything
|
||
</code></pre>
|
||
<hr />
|
||
<h2 id="use-cases"><a class="header" href="#use-cases">Use Cases</a></h2>
|
||
<h3 id="1-multi-cloud-kubernetes-deployment"><a class="header" href="#1-multi-cloud-kubernetes-deployment">1. <strong>Multi-Cloud Kubernetes Deployment</strong></a></h3>
|
||
<p>Deploy Kubernetes clusters across different cloud providers with identical configuration.</p>
|
||
<pre><code class="language-bash"># UpCloud cluster
|
||
provisioning cluster create k8s-prod --provider upcloud
|
||
|
||
# AWS cluster (same config)
|
||
provisioning cluster create k8s-prod --provider aws
|
||
</code></pre>
|
||
<h3 id="2-development--staging--production-pipeline"><a class="header" href="#2-development--staging--production-pipeline">2. <strong>Development → Staging → Production Pipeline</strong></a></h3>
|
||
<p>Manage multiple environments with workspace switching.</p>
|
||
<pre><code class="language-bash"># Development
|
||
provisioning workspace switch dev
|
||
provisioning cluster create app-stack
|
||
|
||
# Staging (same config, different resources)
|
||
provisioning workspace switch staging
|
||
provisioning cluster create app-stack
|
||
|
||
# Production (HA, larger resources)
|
||
provisioning workspace switch prod
|
||
provisioning cluster create app-stack
|
||
</code></pre>
|
||
<h3 id="3-infrastructure-as-code-testing"><a class="header" href="#3-infrastructure-as-code-testing">3. <strong>Infrastructure as Code Testing</strong></a></h3>
|
||
<p>Test infrastructure changes before deploying to production.</p>
|
||
<pre><code class="language-bash"># Test Kubernetes upgrade locally
|
||
provisioning test topology load kubernetes_3node | \
|
||
test env cluster kubernetes --version 1.29.0
|
||
|
||
# Verify functionality
|
||
provisioning test env run <env-id>
|
||
|
||
# Cleanup
|
||
provisioning test env cleanup <env-id>
|
||
</code></pre>
|
||
<h3 id="4-batch-multi-region-deployment"><a class="header" href="#4-batch-multi-region-deployment">4. <strong>Batch Multi-Region Deployment</strong></a></h3>
|
||
<p>Deploy to multiple regions in parallel.</p>
|
||
<pre><code class="language-kcl"># workflows/multi-region.k
|
||
batch_workflow: BatchWorkflow = {
|
||
operations = [
|
||
{
|
||
id = "eu-cluster"
|
||
type = "cluster"
|
||
region = "eu-west-1"
|
||
cluster = "app-stack"
|
||
}
|
||
{
|
||
id = "us-cluster"
|
||
type = "cluster"
|
||
region = "us-east-1"
|
||
cluster = "app-stack"
|
||
}
|
||
{
|
||
id = "asia-cluster"
|
||
type = "cluster"
|
||
region = "ap-south-1"
|
||
cluster = "app-stack"
|
||
}
|
||
]
|
||
parallel_limit = 3 # All at once
|
||
}
|
||
</code></pre>
|
||
<pre><code class="language-bash">provisioning batch submit workflows/multi-region.k
|
||
provisioning batch monitor <workflow-id>
|
||
</code></pre>
|
||
<h3 id="5-automated-disaster-recovery"><a class="header" href="#5-automated-disaster-recovery">5. <strong>Automated Disaster Recovery</strong></a></h3>
|
||
<p>Recreate infrastructure from configuration.</p>
|
||
<pre><code class="language-bash"># Infrastructure destroyed
|
||
provisioning workspace switch prod
|
||
|
||
# Recreate from config
|
||
provisioning cluster create --infra backup-restore --wait
|
||
|
||
# All services restored with same configuration
|
||
</code></pre>
|
||
<h3 id="6-cicd-integration"><a class="header" href="#6-cicd-integration">6. <strong>CI/CD Integration</strong></a></h3>
|
||
<p>Automated testing and deployment pipelines.</p>
|
||
<pre><code class="language-yaml"># .gitlab-ci.yml
|
||
test-infrastructure:
|
||
script:
|
||
- provisioning test quick kubernetes
|
||
- provisioning test quick postgres
|
||
|
||
deploy-staging:
|
||
script:
|
||
- provisioning workspace switch staging
|
||
- provisioning cluster create app-stack --check
|
||
- provisioning cluster create app-stack --yes
|
||
|
||
deploy-production:
|
||
when: manual
|
||
script:
|
||
- provisioning workspace switch prod
|
||
- provisioning cluster create app-stack --yes
|
||
</code></pre>
|
||
<hr />
|
||
<h2 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h2>
|
||
<h3 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h3>
|
||
<ol>
|
||
<li>
|
||
<p><strong>Install Prerequisites</strong></p>
|
||
<pre><code class="language-bash"># Install Nushell
|
||
brew install nushell # macOS
|
||
|
||
# Install KCL
|
||
brew install kcl-lang/tap/kcl # macOS
|
||
|
||
# Install SOPS (optional, for secrets)
|
||
brew install sops
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Add CLI to PATH</strong></p>
|
||
<pre><code class="language-bash">ln -sf "$(pwd)/provisioning/core/cli/provisioning" /usr/local/bin/provisioning
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Initialize Workspace</strong></p>
|
||
<pre><code class="language-bash">provisioning workspace init my-project
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Configure Provider</strong></p>
|
||
<pre><code class="language-bash"># Edit workspace config
|
||
provisioning sops workspace/config/provisioning.yaml
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Deploy Infrastructure</strong></p>
|
||
<pre><code class="language-bash"># Check what will be created
|
||
provisioning server create --check
|
||
|
||
# Create servers
|
||
provisioning server create --yes
|
||
|
||
# Install Kubernetes
|
||
provisioning taskserv create kubernetes
|
||
</code></pre>
|
||
</li>
|
||
</ol>
|
||
<h3 id="learning-path"><a class="header" href="#learning-path">Learning Path</a></h3>
|
||
<ol>
|
||
<li>
|
||
<p><strong>Start with Guides</strong></p>
|
||
<pre><code class="language-bash">provisioning sc # Quick reference
|
||
provisioning guide from-scratch # Complete walkthrough
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Explore Examples</strong></p>
|
||
<pre><code class="language-bash">ls provisioning/examples/
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Read Architecture Docs</strong></p>
|
||
<ul>
|
||
<li><a href="architecture/ARCHITECTURE_OVERVIEW.html">Architecture Overview</a></li>
|
||
<li><a href="architecture/multi-repo-strategy.html">Multi-Repo Strategy</a></li>
|
||
<li><a href="architecture/integration-patterns.html">Integration Patterns</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>Try Test Environments</strong></p>
|
||
<pre><code class="language-bash">provisioning test quick kubernetes
|
||
provisioning test quick postgres
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Build Custom Extensions</strong></p>
|
||
<ul>
|
||
<li>Create custom task services</li>
|
||
<li>Define cluster templates</li>
|
||
<li>Write workflow automation</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="documentation-index"><a class="header" href="#documentation-index">Documentation Index</a></h2>
|
||
<h3 id="user-documentation"><a class="header" href="#user-documentation">User Documentation</a></h3>
|
||
<ul>
|
||
<li><strong><a href="quickstart/01-prerequisites.html">Quick Start Guide</a></strong> - Get started in 10 minutes</li>
|
||
<li><strong><a href="user/SERVICE_MANAGEMENT_GUIDE.html">Service Management Guide</a></strong> - Complete service reference</li>
|
||
<li><strong><a href="user/AUTHENTICATION_LAYER_GUIDE.html">Authentication Guide</a></strong> - Authentication and security</li>
|
||
<li><strong><a href="user/WORKSPACE_SWITCHING_GUIDE.html">Workspace Switching Guide</a></strong> - Workspace management</li>
|
||
<li><strong><a href="user/test-environment-guide.html">Test Environment Guide</a></strong> - Testing infrastructure</li>
|
||
</ul>
|
||
<h3 id="architecture-documentation"><a class="header" href="#architecture-documentation">Architecture Documentation</a></h3>
|
||
<ul>
|
||
<li><strong><a href="architecture/ARCHITECTURE_OVERVIEW.html">Architecture Overview</a></strong> - System architecture</li>
|
||
<li><strong><a href="architecture/multi-repo-strategy.html">Multi-Repo Strategy</a></strong> - Repository organization</li>
|
||
<li><strong><a href="architecture/integration-patterns.html">Integration Patterns</a></strong> - Integration design</li>
|
||
<li><strong><a href="architecture/orchestrator-integration-model.html">Orchestrator Integration</a></strong> - Workflow execution</li>
|
||
<li><strong><a href="architecture/adr/README.html">ADR Index</a></strong> - Architecture Decision Records</li>
|
||
<li><strong><a href="architecture/DATABASE_AND_CONFIG_ARCHITECTURE.html">Database Architecture</a></strong> - Data layer design</li>
|
||
</ul>
|
||
<h3 id="development-documentation"><a class="header" href="#development-documentation">Development Documentation</a></h3>
|
||
<ul>
|
||
<li><strong><a href="development/workflow.html">Development Workflow</a></strong> - Development process</li>
|
||
<li><strong><a href="development/integration.html">Integration Guide</a></strong> - Integration patterns</li>
|
||
<li><strong><a href="development/COMMAND_HANDLER_GUIDE.html">Command Handler Guide</a></strong> - CLI development</li>
|
||
</ul>
|
||
<h3 id="api-documentation"><a class="header" href="#api-documentation">API Documentation</a></h3>
|
||
<ul>
|
||
<li><strong><a href="api/rest-api.html">REST API</a></strong> - HTTP endpoints</li>
|
||
<li><strong><a href="api/websocket.html">WebSocket API</a></strong> - Real-time communication</li>
|
||
<li><strong><a href="api/extensions.html">Extensions API</a></strong> - Extension interface</li>
|
||
<li><strong><a href="api/integration-examples.html">Integration Examples</a></strong> - API usage examples</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="project-status"><a class="header" href="#project-status">Project Status</a></h2>
|
||
<p><strong>Current Version</strong>: Active Development (2025-10-07)</p>
|
||
<h3 id="recent-milestones"><a class="header" href="#recent-milestones">Recent Milestones</a></h3>
|
||
<ul>
|
||
<li>✅ <strong>v2.0.5</strong> (2025-10-06) - Platform Installer with TUI and CI/CD modes</li>
|
||
<li>✅ <strong>v2.0.4</strong> (2025-10-06) - Test Environment Service with container management</li>
|
||
<li>✅ <strong>v2.0.3</strong> (2025-09-30) - Interactive Guides system</li>
|
||
<li>✅ <strong>v2.0.2</strong> (2025-09-30) - Modular CLI Architecture (84% code reduction)</li>
|
||
<li>✅ <strong>v2.0.2</strong> (2025-09-25) - Batch Workflow System (85-90% token efficiency)</li>
|
||
<li>✅ <strong>v2.0.1</strong> (2025-09-25) - Hybrid Orchestrator (Rust/Nushell)</li>
|
||
<li>✅ <strong>v2.0.1</strong> (2025-10-02) - Workspace Switching system</li>
|
||
<li>✅ <strong>v2.0.0</strong> (2025-09-23) - Configuration System (476+ accessors)</li>
|
||
</ul>
|
||
<h3 id="roadmap"><a class="header" href="#roadmap">Roadmap</a></h3>
|
||
<ul>
|
||
<li>
|
||
<p><strong>Platform Services</strong></p>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Web Control Center UI completion</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
API Gateway implementation</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Enhanced MCP server capabilities</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>Extension Ecosystem</strong></p>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
OCI registry for extension distribution</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Community task service marketplace</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Cluster template library</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>Enterprise Features</strong></p>
|
||
<ul>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Multi-tenancy support</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
RBAC and audit logging</li>
|
||
<li><input disabled="" type="checkbox"/>
|
||
Cost tracking and optimization</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="support-and-community"><a class="header" href="#support-and-community">Support and Community</a></h2>
|
||
<h3 id="getting-help"><a class="header" href="#getting-help">Getting Help</a></h3>
|
||
<ul>
|
||
<li><strong>Documentation</strong>: Start with <code>provisioning help</code> or <code>provisioning guide from-scratch</code></li>
|
||
<li><strong>Issues</strong>: Report bugs and request features on the issue tracker</li>
|
||
<li><strong>Discussions</strong>: Join community discussions for questions and ideas</li>
|
||
</ul>
|
||
<h3 id="contributing"><a class="header" href="#contributing">Contributing</a></h3>
|
||
<p>Contributions are welcome! See <a href="docs/development/CONTRIBUTING.html">CONTRIBUTING.md</a> for guidelines.</p>
|
||
<p><strong>Key areas for contribution</strong>:</p>
|
||
<ul>
|
||
<li>New task service definitions</li>
|
||
<li>Cloud provider implementations</li>
|
||
<li>Cluster templates</li>
|
||
<li>Documentation improvements</li>
|
||
<li>Bug fixes and testing</li>
|
||
</ul>
|
||
<hr />
|
||
<h2 id="license"><a class="header" href="#license">License</a></h2>
|
||
<p>See <a href="LICENSE">LICENSE</a> file in project root.</p>
|
||
<hr />
|
||
<p><strong>Maintained By</strong>: Architecture Team
|
||
<strong>Last Updated</strong>: 2025-10-07
|
||
<strong>Project Home</strong>: <a href="provisioning/">provisioning/</a></p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="operations/backup-recovery.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="quick-reference/SUDO_PASSWORD_HANDLING.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="operations/backup-recovery.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="quick-reference/SUDO_PASSWORD_HANDLING.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>
|