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.
760 lines
37 KiB
HTML
760 lines
37 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="ayu sidebar-visible" dir="ltr">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Target-Based Config Implementation - 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/configuration/TARGET_BASED_CONFIG_COMPLETE_IMPLEMENTATION.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="target-based-configuration-system---complete-implementation"><a class="header" href="#target-based-configuration-system---complete-implementation">Target-Based Configuration System - Complete Implementation</a></h1>
|
||
<p><strong>Version</strong>: 4.0.0
|
||
<strong>Date</strong>: 2025-10-06
|
||
<strong>Status</strong>: ✅ PRODUCTION READY</p>
|
||
<h2 id="executive-summary"><a class="header" href="#executive-summary">Executive Summary</a></h2>
|
||
<p>A comprehensive target-based configuration system has been successfully implemented, replacing the monolithic <code>config.defaults.toml</code> with a modular, workspace-centric architecture. Each provider, platform service, and KMS component now has independent configuration, and workspaces are fully self-contained with their own <code>config/provisioning.yaml</code>.</p>
|
||
<hr />
|
||
<h2 id="-objectives-achieved"><a class="header" href="#-objectives-achieved">🎯 Objectives Achieved</a></h2>
|
||
<p>✅ <strong>Independent Target Configs</strong>: Providers, platform services, and KMS have separate configs
|
||
✅ <strong>Workspace-Centric</strong>: Each workspace has complete, self-contained configuration
|
||
✅ <strong>User Context Priority</strong>: <code>ws_{name}.yaml</code> files provide high-priority overrides
|
||
✅ <strong>No Runtime config.defaults.toml</strong>: Template-only, never loaded at runtime
|
||
✅ <strong>Migration Automation</strong>: Safe migration scripts with dry-run and backup
|
||
✅ <strong>Schema Validation</strong>: Comprehensive validation for all config types
|
||
✅ <strong>CLI Integration</strong>: Complete command suite for config management
|
||
✅ <strong>Legacy Nomenclature</strong>: All <code>cn_provisioning</code>/<code>kloud</code> references updated</p>
|
||
<hr />
|
||
<h2 id="-architecture-overview"><a class="header" href="#-architecture-overview">📐 Architecture Overview</a></h2>
|
||
<h3 id="configuration-hierarchy-priority-low--high"><a class="header" href="#configuration-hierarchy-priority-low--high">Configuration Hierarchy (Priority: Low → High)</a></h3>
|
||
<pre><code>1. Workspace Config workspace/{name}/config/provisioning.yaml
|
||
2. Provider Configs workspace/{name}/config/providers/*.toml
|
||
3. Platform Configs workspace/{name}/config/platform/*.toml
|
||
4. User Context ~/Library/Application Support/provisioning/ws_{name}.yaml
|
||
5. Environment Variables PROVISIONING_*
|
||
</code></pre>
|
||
<h3 id="directory-structure"><a class="header" href="#directory-structure">Directory Structure</a></h3>
|
||
<pre><code>workspace/{name}/
|
||
├── config/
|
||
│ ├── provisioning.yaml # Main workspace config (YAML)
|
||
│ ├── providers/
|
||
│ │ ├── aws.toml # AWS provider config
|
||
│ │ ├── upcloud.toml # UpCloud provider config
|
||
│ │ └── local.toml # Local provider config
|
||
│ ├── platform/
|
||
│ │ ├── orchestrator.toml # Orchestrator service config
|
||
│ │ ├── control-center.toml # Control Center config
|
||
│ │ └── mcp-server.toml # MCP Server config
|
||
│ └── kms.toml # KMS configuration
|
||
├── infra/ # Infrastructure definitions
|
||
├── .cache/ # Cache directory
|
||
├── .runtime/ # Runtime data
|
||
├── .providers/ # Provider-specific runtime
|
||
├── .orchestrator/ # Orchestrator data
|
||
└── .kms/ # KMS keys and cache
|
||
</code></pre>
|
||
<hr />
|
||
<h2 id="-implementation-details"><a class="header" href="#-implementation-details">🚀 Implementation Details</a></h2>
|
||
<h3 id="phase-1-nomenclature-migration-"><a class="header" href="#phase-1-nomenclature-migration-">Phase 1: Nomenclature Migration ✅</a></h3>
|
||
<p><strong>Files Updated</strong>: 9 core files (29+ changes)</p>
|
||
<p><strong>Mappings</strong>:</p>
|
||
<ul>
|
||
<li><code>cn_provisioning</code> → <code>provisioning</code></li>
|
||
<li><code>kloud</code> → <code>workspace</code></li>
|
||
<li><code>kloud_path</code> → <code>workspace_path</code></li>
|
||
<li><code>kloud_list</code> → <code>workspace_list</code></li>
|
||
<li><code>dflt_set</code> → <code>default_settings</code></li>
|
||
<li><code>PROVISIONING_KLOUD_PATH</code> → <code>PROVISIONING_WORKSPACE_PATH</code></li>
|
||
</ul>
|
||
<p><strong>Files Modified</strong>:</p>
|
||
<ol>
|
||
<li><code>lib_provisioning/defs/lists.nu</code></li>
|
||
<li><code>lib_provisioning/sops/lib.nu</code></li>
|
||
<li><code>lib_provisioning/kms/lib.nu</code></li>
|
||
<li><code>lib_provisioning/cmd/lib.nu</code></li>
|
||
<li><code>lib_provisioning/config/migration.nu</code></li>
|
||
<li><code>lib_provisioning/config/loader.nu</code></li>
|
||
<li><code>lib_provisioning/config/accessor.nu</code></li>
|
||
<li><code>lib_provisioning/utils/settings.nu</code></li>
|
||
<li><code>templates/default_context.yaml</code></li>
|
||
</ol>
|
||
<hr />
|
||
<h3 id="phase-2-independent-target-configs-"><a class="header" href="#phase-2-independent-target-configs-">Phase 2: Independent Target Configs ✅</a></h3>
|
||
<h4 id="21-provider-configs"><a class="header" href="#21-provider-configs">2.1 Provider Configs</a></h4>
|
||
<p><strong>Files Created</strong>: 6 files (3 providers × 2 files each)</p>
|
||
<div class="table-wrapper"><table><thead><tr><th>Provider</th><th>Config</th><th>Schema</th><th>Features</th></tr></thead><tbody>
|
||
<tr><td>AWS</td><td><code>extensions/providers/aws/config.defaults.toml</code></td><td><code>config.schema.toml</code></td><td>CLI/API, multi-auth, cost tracking</td></tr>
|
||
<tr><td>UpCloud</td><td><code>extensions/providers/upcloud/config.defaults.toml</code></td><td><code>config.schema.toml</code></td><td>API-first, firewall, backups</td></tr>
|
||
<tr><td>Local</td><td><code>extensions/providers/local/config.defaults.toml</code></td><td><code>config.schema.toml</code></td><td>Multi-backend (libvirt/docker/podman)</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<p><strong>Interpolation Variables</strong>: <code>{{workspace.path}}</code>, <code>{{provider.paths.base}}</code></p>
|
||
<h4 id="22-platform-service-configs"><a class="header" href="#22-platform-service-configs">2.2 Platform Service Configs</a></h4>
|
||
<p><strong>Files Created</strong>: 10 files</p>
|
||
<div class="table-wrapper"><table><thead><tr><th>Service</th><th>Config</th><th>Schema</th><th>Integration</th></tr></thead><tbody>
|
||
<tr><td>Orchestrator</td><td><code>platform/orchestrator/config.defaults.toml</code></td><td><code>config.schema.toml</code></td><td>Rust config loader (<code>src/config.rs</code>)</td></tr>
|
||
<tr><td>Control Center</td><td><code>platform/control-center/config.defaults.toml</code></td><td><code>config.schema.toml</code></td><td>Enhanced with workspace paths</td></tr>
|
||
<tr><td>MCP Server</td><td><code>platform/mcp-server/config.defaults.toml</code></td><td><code>config.schema.toml</code></td><td>New configuration</td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<p><strong>Orchestrator Rust Integration</strong>:</p>
|
||
<ul>
|
||
<li>Added <code>toml</code> dependency to <code>Cargo.toml</code></li>
|
||
<li>Created <code>src/config.rs</code> (291 lines)</li>
|
||
<li>CLI args override config values</li>
|
||
</ul>
|
||
<h4 id="23-kms-config"><a class="header" href="#23-kms-config">2.3 KMS Config</a></h4>
|
||
<p><strong>Files Created</strong>: 6 files (2,510 lines total)</p>
|
||
<ul>
|
||
<li><code>core/services/kms/config.defaults.toml</code> (270 lines)</li>
|
||
<li><code>core/services/kms/config.schema.toml</code> (330 lines)</li>
|
||
<li><code>core/services/kms/config.remote.example.toml</code> (180 lines)</li>
|
||
<li><code>core/services/kms/config.local.example.toml</code> (290 lines)</li>
|
||
<li><code>core/services/kms/README.md</code> (500+ lines)</li>
|
||
<li><code>core/services/kms/MIGRATION.md</code> (800+ lines)</li>
|
||
</ul>
|
||
<p><strong>Key Features</strong>:</p>
|
||
<ul>
|
||
<li>Three modes: local, remote, hybrid</li>
|
||
<li>59 new accessor functions in <code>config/accessor.nu</code></li>
|
||
<li>Secure defaults (TLS 1.3, 0600 permissions)</li>
|
||
<li>Comprehensive security validation</li>
|
||
</ul>
|
||
<hr />
|
||
<h3 id="phase-3-workspace-structure-"><a class="header" href="#phase-3-workspace-structure-">Phase 3: Workspace Structure ✅</a></h3>
|
||
<h4 id="31-workspace-centric-architecture"><a class="header" href="#31-workspace-centric-architecture">3.1 Workspace-Centric Architecture</a></h4>
|
||
<p><strong>Template Files Created</strong>: 7 files</p>
|
||
<ul>
|
||
<li><code>config/templates/workspace-provisioning.yaml.template</code></li>
|
||
<li><code>config/templates/provider-aws.toml.template</code></li>
|
||
<li><code>config/templates/provider-local.toml.template</code></li>
|
||
<li><code>config/templates/provider-upcloud.toml.template</code></li>
|
||
<li><code>config/templates/kms.toml.template</code></li>
|
||
<li><code>config/templates/user-context.yaml.template</code></li>
|
||
<li><code>config/templates/README.md</code></li>
|
||
</ul>
|
||
<p><strong>Workspace Init Module</strong>: <code>lib_provisioning/workspace/init.nu</code></p>
|
||
<p>Functions:</p>
|
||
<ul>
|
||
<li><code>workspace-init</code> - Initialize complete workspace structure</li>
|
||
<li><code>workspace-init-interactive</code> - Interactive creation wizard</li>
|
||
<li><code>workspace-list</code> - List all workspaces</li>
|
||
<li><code>workspace-activate</code> - Activate a workspace</li>
|
||
<li><code>workspace-get-active</code> - Get currently active workspace</li>
|
||
</ul>
|
||
<h4 id="32-user-context-system"><a class="header" href="#32-user-context-system">3.2 User Context System</a></h4>
|
||
<p><strong>User Context Files</strong>: <code>~/Library/Application Support/provisioning/ws_{name}.yaml</code></p>
|
||
<p>Format:</p>
|
||
<pre><code class="language-yaml">workspace:
|
||
name: "production"
|
||
path: "/path/to/workspace"
|
||
active: true
|
||
|
||
overrides:
|
||
debug_enabled: false
|
||
log_level: "info"
|
||
kms_mode: "remote"
|
||
# ... 9 override fields total
|
||
</code></pre>
|
||
<p><strong>Functions Created</strong>:</p>
|
||
<ul>
|
||
<li><code>create-workspace-context</code> - Create ws_{name}.yaml</li>
|
||
<li><code>set-workspace-active</code> - Mark workspace as active</li>
|
||
<li><code>list-workspace-contexts</code> - List all contexts</li>
|
||
<li><code>get-active-workspace-context</code> - Get active workspace</li>
|
||
<li><code>update-workspace-last-used</code> - Update timestamp</li>
|
||
</ul>
|
||
<p><strong>Helper Functions</strong>: <code>lib_provisioning/workspace/helpers.nu</code></p>
|
||
<ul>
|
||
<li><code>apply-context-overrides</code> - Apply overrides to config</li>
|
||
<li><code>validate-workspace-context</code> - Validate context structure</li>
|
||
<li><code>has-workspace-context</code> - Check context existence</li>
|
||
</ul>
|
||
<h4 id="33-workspace-activation"><a class="header" href="#33-workspace-activation">3.3 Workspace Activation</a></h4>
|
||
<p><strong>CLI Flags Added</strong>:</p>
|
||
<ul>
|
||
<li><code>--activate (-a)</code> - Activate workspace on creation</li>
|
||
<li><code>--interactive (-I)</code> - Interactive creation wizard</li>
|
||
</ul>
|
||
<p><strong>Commands</strong>:</p>
|
||
<pre><code class="language-bash"># Create and activate
|
||
provisioning workspace init my-app ~/workspaces/my-app --activate
|
||
|
||
# Interactive mode
|
||
provisioning workspace init --interactive
|
||
|
||
# Activate existing
|
||
provisioning workspace activate my-app
|
||
</code></pre>
|
||
<hr />
|
||
<h3 id="phase-4-configuration-loading-"><a class="header" href="#phase-4-configuration-loading-">Phase 4: Configuration Loading ✅</a></h3>
|
||
<h4 id="41-config-loader-refactored"><a class="header" href="#41-config-loader-refactored">4.1 Config Loader Refactored</a></h4>
|
||
<p><strong>File</strong>: <code>lib_provisioning/config/loader.nu</code></p>
|
||
<p><strong>Critical Changes</strong>:</p>
|
||
<ul>
|
||
<li>❌ <strong>REMOVED</strong>: <code>get-defaults-config-path()</code> function</li>
|
||
<li>✅ <strong>ADDED</strong>: <code>get-active-workspace()</code> function</li>
|
||
<li>✅ <strong>ADDED</strong>: <code>apply-user-context-overrides()</code> function</li>
|
||
<li>✅ <strong>ADDED</strong>: YAML format support</li>
|
||
</ul>
|
||
<p><strong>New Loading Sequence</strong>:</p>
|
||
<ol>
|
||
<li>Get active workspace from user context</li>
|
||
<li>Load <code>workspace/{name}/config/provisioning.yaml</code></li>
|
||
<li>Load provider configs from <code>workspace/{name}/config/providers/*.toml</code></li>
|
||
<li>Load platform configs from <code>workspace/{name}/config/platform/*.toml</code></li>
|
||
<li>Load user context <code>ws_{name}.yaml</code> (stored separately)</li>
|
||
<li>Apply user context overrides (highest config priority)</li>
|
||
<li>Apply environment-specific overrides</li>
|
||
<li>Apply environment variable overrides (highest priority)</li>
|
||
<li>Interpolate paths</li>
|
||
<li>Validate configuration</li>
|
||
</ol>
|
||
<h4 id="42-path-interpolation"><a class="header" href="#42-path-interpolation">4.2 Path Interpolation</a></h4>
|
||
<p><strong>Variables Supported</strong>:</p>
|
||
<ul>
|
||
<li><code>{{workspace.path}}</code> - Active workspace base path</li>
|
||
<li><code>{{workspace.name}}</code> - Active workspace name</li>
|
||
<li><code>{{provider.paths.base}}</code> - Provider-specific paths</li>
|
||
<li><code>{{env.*}}</code> - Environment variables (safe list)</li>
|
||
<li><code>{{now.date}}</code>, <code>{{now.timestamp}}</code>, <code>{{now.iso}}</code> - Date/time</li>
|
||
<li><code>{{git.branch}}</code>, <code>{{git.commit}}</code> - Git info</li>
|
||
<li><code>{{path.join(...)}}</code> - Path joining function</li>
|
||
</ul>
|
||
<p><strong>Implementation</strong>: Already present in <code>loader.nu</code> (lines 698-1262)</p>
|
||
<hr />
|
||
<h3 id="phase-5-cli-commands-"><a class="header" href="#phase-5-cli-commands-">Phase 5: CLI Commands ✅</a></h3>
|
||
<p><strong>Module Created</strong>: <code>lib_provisioning/workspace/config_commands.nu</code> (380 lines)</p>
|
||
<p><strong>Commands Implemented</strong>:</p>
|
||
<pre><code class="language-bash"># Show configuration
|
||
provisioning workspace config show [name] [--format yaml|json|toml]
|
||
|
||
# Validate configuration
|
||
provisioning workspace config validate [name]
|
||
|
||
# Generate provider config
|
||
provisioning workspace config generate provider <name>
|
||
|
||
# Edit configuration
|
||
provisioning workspace config edit <type> [name]
|
||
# Types: main, provider, platform, kms
|
||
|
||
# Show hierarchy
|
||
provisioning workspace config hierarchy [name]
|
||
|
||
# List configs
|
||
provisioning workspace config list [name] [--type all|provider|platform|kms]
|
||
</code></pre>
|
||
<p><strong>Help System Updated</strong>: <code>main_provisioning/help_system.nu</code></p>
|
||
<hr />
|
||
<h3 id="phase-6-migration--validation-"><a class="header" href="#phase-6-migration--validation-">Phase 6: Migration & Validation ✅</a></h3>
|
||
<h4 id="61-migration-script"><a class="header" href="#61-migration-script">6.1 Migration Script</a></h4>
|
||
<p><strong>File</strong>: <code>scripts/migrate-to-target-configs.nu</code> (200+ lines)</p>
|
||
<p><strong>Features</strong>:</p>
|
||
<ul>
|
||
<li>Automatic detection of old <code>config.defaults.toml</code></li>
|
||
<li>Workspace structure creation</li>
|
||
<li>Config transformation (TOML → YAML)</li>
|
||
<li>Provider config generation from templates</li>
|
||
<li>User context creation</li>
|
||
<li>Safety features: <code>--dry-run</code>, <code>--backup</code>, confirmation prompts</li>
|
||
</ul>
|
||
<p><strong>Usage</strong>:</p>
|
||
<pre><code class="language-bash"># Dry run
|
||
./scripts/migrate-to-target-configs.nu --workspace-name "prod" --dry-run
|
||
|
||
# Execute with backup
|
||
./scripts/migrate-to-target-configs.nu --workspace-name "prod" --backup
|
||
</code></pre>
|
||
<h4 id="62-schema-validation"><a class="header" href="#62-schema-validation">6.2 Schema Validation</a></h4>
|
||
<p><strong>Module</strong>: <code>lib_provisioning/config/schema_validator.nu</code> (150+ lines)</p>
|
||
<p><strong>Validation Features</strong>:</p>
|
||
<ul>
|
||
<li>Required fields checking</li>
|
||
<li>Type validation (string, int, bool, record)</li>
|
||
<li>Enum value validation</li>
|
||
<li>Numeric range validation (min/max)</li>
|
||
<li>Pattern matching with regex</li>
|
||
<li>Deprecation warnings</li>
|
||
<li>Pretty-printed error messages</li>
|
||
</ul>
|
||
<p><strong>Functions</strong>:</p>
|
||
<pre><code class="language-nushell"># Generic validation
|
||
validate-config-with-schema $config $schema_file
|
||
|
||
# Domain-specific
|
||
validate-provider-config "aws" $config
|
||
validate-platform-config "orchestrator" $config
|
||
validate-kms-config $config
|
||
validate-workspace-config $config
|
||
</code></pre>
|
||
<p><strong>Test Suite</strong>: <code>tests/config_validation_tests.nu</code> (200+ lines)</p>
|
||
<hr />
|
||
<h2 id="-statistics"><a class="header" href="#-statistics">📊 Statistics</a></h2>
|
||
<h3 id="files-created"><a class="header" href="#files-created">Files Created</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Category</th><th>Count</th><th>Total Lines</th></tr></thead><tbody>
|
||
<tr><td>Provider Configs</td><td>6</td><td>22,900 bytes</td></tr>
|
||
<tr><td>Platform Configs</td><td>10</td><td>~1,500 lines</td></tr>
|
||
<tr><td>KMS Configs</td><td>6</td><td>2,510 lines</td></tr>
|
||
<tr><td>Workspace Templates</td><td>7</td><td>~800 lines</td></tr>
|
||
<tr><td>Migration Scripts</td><td>1</td><td>200+ lines</td></tr>
|
||
<tr><td>Validation System</td><td>2</td><td>350+ lines</td></tr>
|
||
<tr><td>CLI Commands</td><td>1</td><td>380 lines</td></tr>
|
||
<tr><td>Documentation</td><td>15+</td><td>8,000+ lines</td></tr>
|
||
<tr><td><strong>TOTAL</strong></td><td><strong>48+</strong></td><td><strong>~13,740 lines</strong></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<h3 id="files-modified"><a class="header" href="#files-modified">Files Modified</a></h3>
|
||
<div class="table-wrapper"><table><thead><tr><th>Category</th><th>Count</th><th>Changes</th></tr></thead><tbody>
|
||
<tr><td>Core Libraries</td><td>8</td><td>29+ occurrences</td></tr>
|
||
<tr><td>Config Loader</td><td>1</td><td>Major refactor</td></tr>
|
||
<tr><td>Context System</td><td>2</td><td>Enhanced</td></tr>
|
||
<tr><td>CLI Integration</td><td>5</td><td>Flags & commands</td></tr>
|
||
<tr><td><strong>TOTAL</strong></td><td><strong>16</strong></td><td><strong>Significant</strong></td></tr>
|
||
</tbody></table>
|
||
</div>
|
||
<hr />
|
||
<h2 id="-key-features"><a class="header" href="#-key-features">🎓 Key Features</a></h2>
|
||
<h3 id="1-independent-configuration"><a class="header" href="#1-independent-configuration">1. Independent Configuration</a></h3>
|
||
<p>✅ Each provider has own config
|
||
✅ Each platform service has own config
|
||
✅ KMS has independent config
|
||
✅ No shared monolithic config</p>
|
||
<h3 id="2-workspace-self-containment"><a class="header" href="#2-workspace-self-containment">2. Workspace Self-Containment</a></h3>
|
||
<p>✅ Each workspace has complete config
|
||
✅ No dependency on global config
|
||
✅ Portable workspace directories
|
||
✅ Easy backup/restore</p>
|
||
<h3 id="3-user-context-priority"><a class="header" href="#3-user-context-priority">3. User Context Priority</a></h3>
|
||
<p>✅ Per-workspace overrides
|
||
✅ Highest config file priority
|
||
✅ Active workspace tracking
|
||
✅ Last used timestamp</p>
|
||
<h3 id="4-migration-safety"><a class="header" href="#4-migration-safety">4. Migration Safety</a></h3>
|
||
<p>✅ Dry-run mode
|
||
✅ Automatic backups
|
||
✅ Confirmation prompts
|
||
✅ Rollback procedures</p>
|
||
<h3 id="5-comprehensive-validation"><a class="header" href="#5-comprehensive-validation">5. Comprehensive Validation</a></h3>
|
||
<p>✅ Schema-based validation
|
||
✅ Type checking
|
||
✅ Pattern matching
|
||
✅ Deprecation warnings</p>
|
||
<h3 id="6-cli-integration"><a class="header" href="#6-cli-integration">6. CLI Integration</a></h3>
|
||
<p>✅ Workspace creation with activation
|
||
✅ Interactive mode
|
||
✅ Config management commands
|
||
✅ Validation commands</p>
|
||
<hr />
|
||
<h2 id="-documentation"><a class="header" href="#-documentation">📖 Documentation</a></h2>
|
||
<h3 id="created-documentation"><a class="header" href="#created-documentation">Created Documentation</a></h3>
|
||
<ol>
|
||
<li><strong>Architecture</strong>: <code>docs/configuration/workspace-config-architecture.md</code></li>
|
||
<li><strong>Migration Guide</strong>: <code>docs/MIGRATION_GUIDE.md</code></li>
|
||
<li><strong>Validation Guide</strong>: <code>docs/CONFIG_VALIDATION.md</code></li>
|
||
<li><strong>Migration Example</strong>: <code>docs/MIGRATION_EXAMPLE.md</code></li>
|
||
<li><strong>CLI Commands</strong>: <code>docs/user/workspace-config-commands.md</code></li>
|
||
<li><strong>KMS README</strong>: <code>core/services/kms/README.md</code></li>
|
||
<li><strong>KMS Migration</strong>: <code>core/services/kms/MIGRATION.md</code></li>
|
||
<li><strong>Platform Summary</strong>: <code>platform/PLATFORM_CONFIG_SUMMARY.md</code></li>
|
||
<li><strong>Workspace Implementation</strong>: <code>docs/WORKSPACE_CONFIG_IMPLEMENTATION_SUMMARY.md</code></li>
|
||
<li><strong>Template Guide</strong>: <code>config/templates/README.md</code></li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="-testing"><a class="header" href="#-testing">🧪 Testing</a></h2>
|
||
<h3 id="test-suites-created"><a class="header" href="#test-suites-created">Test Suites Created</a></h3>
|
||
<ol>
|
||
<li>
|
||
<p><strong>Config Validation Tests</strong>: <code>tests/config_validation_tests.nu</code></p>
|
||
<ul>
|
||
<li>Required fields validation</li>
|
||
<li>Type validation</li>
|
||
<li>Enum validation</li>
|
||
<li>Range validation</li>
|
||
<li>Pattern validation</li>
|
||
<li>Deprecation warnings</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>Workspace Verification</strong>: <code>lib_provisioning/workspace/verify.nu</code></p>
|
||
<ul>
|
||
<li>Template directory checks</li>
|
||
<li>Template file existence</li>
|
||
<li>Module loading verification</li>
|
||
<li>Config loader validation</li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
<h3 id="running-tests"><a class="header" href="#running-tests">Running Tests</a></h3>
|
||
<pre><code class="language-bash"># Run validation tests
|
||
nu tests/config_validation_tests.nu
|
||
|
||
# Run workspace verification
|
||
nu lib_provisioning/workspace/verify.nu
|
||
|
||
# Validate specific workspace
|
||
provisioning workspace config validate my-app
|
||
</code></pre>
|
||
<hr />
|
||
<h2 id="-migration-path"><a class="header" href="#-migration-path">🔄 Migration Path</a></h2>
|
||
<h3 id="step-by-step-migration"><a class="header" href="#step-by-step-migration">Step-by-Step Migration</a></h3>
|
||
<ol>
|
||
<li>
|
||
<p><strong>Backup</strong></p>
|
||
<pre><code class="language-bash">cp -r provisioning/config provisioning/config.backup.$(date +%Y%m%d)
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Dry Run</strong></p>
|
||
<pre><code class="language-bash">./scripts/migrate-to-target-configs.nu --workspace-name "production" --dry-run
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Execute Migration</strong></p>
|
||
<pre><code class="language-bash">./scripts/migrate-to-target-configs.nu --workspace-name "production" --backup
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Validate</strong></p>
|
||
<pre><code class="language-bash">provisioning workspace config validate
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Test</strong></p>
|
||
<pre><code class="language-bash">provisioning --check server list
|
||
</code></pre>
|
||
</li>
|
||
<li>
|
||
<p><strong>Clean Up</strong></p>
|
||
<pre><code class="language-bash"># Only after verifying everything works
|
||
rm provisioning/config/config.defaults.toml
|
||
</code></pre>
|
||
</li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="-breaking-changes"><a class="header" href="#-breaking-changes">⚠️ Breaking Changes</a></h2>
|
||
<h3 id="version-400-changes"><a class="header" href="#version-400-changes">Version 4.0.0 Changes</a></h3>
|
||
<ol>
|
||
<li>
|
||
<p><strong>config.defaults.toml is template-only</strong></p>
|
||
<ul>
|
||
<li>Never loaded at runtime</li>
|
||
<li>Used only to generate workspace configs</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>Workspace required</strong></p>
|
||
<ul>
|
||
<li>Must have active workspace</li>
|
||
<li>Or be in workspace directory</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>Environment variables renamed</strong></p>
|
||
<ul>
|
||
<li><code>PROVISIONING_KLOUD_PATH</code> → <code>PROVISIONING_WORKSPACE_PATH</code></li>
|
||
<li><code>PROVISIONING_DFLT_SET</code> → <code>PROVISIONING_DEFAULT_SETTINGS</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p><strong>User context location</strong></p>
|
||
<ul>
|
||
<li><code>~/Library/Application Support/provisioning/ws_{name}.yaml</code></li>
|
||
<li>Not <code>default_context.yaml</code></li>
|
||
</ul>
|
||
</li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="-success-criteria"><a class="header" href="#-success-criteria">🎯 Success Criteria</a></h2>
|
||
<p>All success criteria <strong>MET</strong> ✅:</p>
|
||
<ol>
|
||
<li>✅ Zero occurrences of legacy nomenclature</li>
|
||
<li>✅ Each provider has independent config + schema</li>
|
||
<li>✅ Each platform service has independent config</li>
|
||
<li>✅ KMS has independent config (local/remote)</li>
|
||
<li>✅ Workspace creation generates complete config structure</li>
|
||
<li>✅ User context system <code>ws_{name}.yaml</code> functional</li>
|
||
<li>✅ <code>provisioning workspace create --activate</code> works</li>
|
||
<li>✅ Config hierarchy respected correctly</li>
|
||
<li>✅ <code>paths.base</code> adjusts dynamically per workspace</li>
|
||
<li>✅ Migration script tested and functional</li>
|
||
<li>✅ Documentation complete</li>
|
||
<li>✅ Tests passing</li>
|
||
</ol>
|
||
<hr />
|
||
<h2 id="-support"><a class="header" href="#-support">📞 Support</a></h2>
|
||
<h3 id="common-issues"><a class="header" href="#common-issues">Common Issues</a></h3>
|
||
<p><strong>Issue</strong>: “No active workspace found”
|
||
<strong>Solution</strong>: Initialize or activate a workspace</p>
|
||
<pre><code class="language-bash">provisioning workspace init my-app ~/workspaces/my-app --activate
|
||
</code></pre>
|
||
<p><strong>Issue</strong>: “Config file not found”
|
||
<strong>Solution</strong>: Ensure workspace is properly initialized</p>
|
||
<pre><code class="language-bash">provisioning workspace config validate
|
||
</code></pre>
|
||
<p><strong>Issue</strong>: “Old config still being loaded”
|
||
<strong>Solution</strong>: Verify config.defaults.toml is not in runtime path</p>
|
||
<pre><code class="language-bash"># Check loader.nu - get-defaults-config-path should be REMOVED
|
||
grep "get-defaults-config-path" lib_provisioning/config/loader.nu
|
||
# Should return: (empty)
|
||
</code></pre>
|
||
<h3 id="getting-help"><a class="header" href="#getting-help">Getting Help</a></h3>
|
||
<pre><code class="language-bash"># General help
|
||
provisioning help
|
||
|
||
# Workspace help
|
||
provisioning help workspace
|
||
|
||
# Config commands help
|
||
provisioning workspace config help
|
||
</code></pre>
|
||
<hr />
|
||
<h2 id="-conclusion"><a class="header" href="#-conclusion">🏁 Conclusion</a></h2>
|
||
<p>The target-based configuration system is <strong>complete, tested, and production-ready</strong>. It provides:</p>
|
||
<ul>
|
||
<li><strong>Modularity</strong>: Independent configs per target</li>
|
||
<li><strong>Flexibility</strong>: Workspace-centric with user overrides</li>
|
||
<li><strong>Safety</strong>: Migration scripts with dry-run and backups</li>
|
||
<li><strong>Validation</strong>: Comprehensive schema validation</li>
|
||
<li><strong>Usability</strong>: Complete CLI integration</li>
|
||
<li><strong>Documentation</strong>: Extensive guides and examples</li>
|
||
</ul>
|
||
<p>All objectives achieved. System ready for deployment.</p>
|
||
<hr />
|
||
<p><strong>Maintained By</strong>: Infrastructure Team
|
||
<strong>Version</strong>: 4.0.0
|
||
<strong>Status</strong>: ✅ Production Ready
|
||
<strong>Last Updated</strong>: 2025-10-06</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="../SECURITY_SYSTEM_IMPLEMENTATION_COMPLETE.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="../configuration/WORKSPACE_CONFIG_IMPLEMENTATION_SUMMARY.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="../SECURITY_SYSTEM_IMPLEMENTATION_COMPLETE.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="../configuration/WORKSPACE_CONFIG_IMPLEMENTATION_SUMMARY.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>
|