2025-12-11 21:50:42 +00:00
<!DOCTYPE HTML>
< html lang = "en" class = "ayu sidebar-visible" dir = "ltr" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
2026-01-08 09:55:37 +00:00
< title > From Scratch - Provisioning Platform Documentation< / title >
2025-12-11 21:50:42 +00:00
<!-- 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/guides/from-scratch.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 = "complete-deployment-guide-from-scratch-to-production" > < a class = "header" href = "#complete-deployment-guide-from-scratch-to-production" > Complete Deployment Guide: From Scratch to Production< / a > < / h1 >
< p > < strong > Version< / strong > : 3.5.0
< strong > Last Updated< / strong > : 2025-10-09
< strong > Estimated Time< / strong > : 30-60 minutes
< strong > Difficulty< / strong > : Beginner to Intermediate< / p >
< hr / >
< h2 id = "table-of-contents" > < a class = "header" href = "#table-of-contents" > Table of Contents< / a > < / h2 >
< ol >
< li > < a href = "#prerequisites" > Prerequisites< / a > < / li >
< li > < a href = "#step-1-install-nushell" > Step 1: Install Nushell< / a > < / li >
< li > < a href = "#step-2-install-nushell-plugins-recommended" > Step 2: Install Nushell Plugins (Recommended)< / a > < / li >
< li > < a href = "#step-3-install-required-tools" > Step 3: Install Required Tools< / a > < / li >
< li > < a href = "#step-4-clone-and-setup-project" > Step 4: Clone and Setup Project< / a > < / li >
< li > < a href = "#step-5-initialize-workspace" > Step 5: Initialize Workspace< / a > < / li >
< li > < a href = "#step-6-configure-environment" > Step 6: Configure Environment< / a > < / li >
< li > < a href = "#step-7-discover-and-load-modules" > Step 7: Discover and Load Modules< / a > < / li >
< li > < a href = "#step-8-validate-configuration" > Step 8: Validate Configuration< / a > < / li >
< li > < a href = "#step-9-deploy-servers" > Step 9: Deploy Servers< / a > < / li >
< li > < a href = "#step-10-install-task-services" > Step 10: Install Task Services< / a > < / li >
< li > < a href = "#step-11-create-clusters" > Step 11: Create Clusters< / a > < / li >
< li > < a href = "#step-12-verify-deployment" > Step 12: Verify Deployment< / a > < / li >
< li > < a href = "#step-13-post-deployment" > Step 13: Post-Deployment< / a > < / li >
< li > < a href = "#troubleshooting" > Troubleshooting< / a > < / li >
< li > < a href = "#next-steps" > Next Steps< / a > < / li >
< / ol >
< hr / >
< h2 id = "prerequisites" > < a class = "header" href = "#prerequisites" > Prerequisites< / a > < / h2 >
< p > Before starting, ensure you have:< / p >
< ul >
< li > ✅ < strong > Operating System< / strong > : macOS, Linux, or Windows (WSL2 recommended)< / li >
< li > ✅ < strong > Administrator Access< / strong > : Ability to install software and configure system< / li >
< li > ✅ < strong > Internet Connection< / strong > : For downloading dependencies and accessing cloud providers< / li >
< li > ✅ < strong > Cloud Provider Credentials< / strong > : UpCloud, AWS, or local development environment< / li >
< li > ✅ < strong > Basic Terminal Knowledge< / strong > : Comfortable running shell commands< / li >
< li > ✅ < strong > Text Editor< / strong > : vim, nano, VSCode, or your preferred editor< / li >
< / ul >
< h3 id = "recommended-hardware" > < a class = "header" href = "#recommended-hardware" > Recommended Hardware< / a > < / h3 >
< ul >
< li > < strong > CPU< / strong > : 2+ cores< / li >
< li > < strong > RAM< / strong > : 8GB minimum, 16GB recommended< / li >
< li > < strong > Disk< / strong > : 20GB free space minimum< / li >
< / ul >
< hr / >
< h2 id = "step-1-install-nushell" > < a class = "header" href = "#step-1-install-nushell" > Step 1: Install Nushell< / a > < / h2 >
< p > Nushell 0.107.1+ is the primary shell and scripting language for the provisioning platform.< / p >
< h3 id = "macos-via-homebrew" > < a class = "header" href = "#macos-via-homebrew" > macOS (via Homebrew)< / a > < / h3 >
< pre > < code class = "language-bash" > # Install Nushell
brew install nushell
# Verify installation
nu --version
# Expected: 0.107.1 or higher
2026-01-08 09:55:37 +00:00
```plaintext
### Linux (via Package Manager)
**Ubuntu/Debian:**
```bash
# Add Nushell repository
2025-12-11 21:50:42 +00:00
curl -fsSL https://starship.rs/install.sh | bash
# Install Nushell
sudo apt update
sudo apt install nushell
# Verify installation
nu --version
2026-01-08 09:55:37 +00:00
```plaintext
**Fedora:**
```bash
sudo dnf install nushell
2025-12-11 21:50:42 +00:00
nu --version
2026-01-08 09:55:37 +00:00
```plaintext
**Arch Linux:**
```bash
sudo pacman -S nushell
2025-12-11 21:50:42 +00:00
nu --version
2026-01-08 09:55:37 +00:00
```plaintext
### Linux/macOS (via Cargo)
```bash
# Install Rust (if not already installed)
2025-12-11 21:50:42 +00:00
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
# Install Nushell
cargo install nu --locked
# Verify installation
nu --version
2026-01-08 09:55:37 +00:00
```plaintext
### Windows (via Winget)
```powershell
# Install Nushell
2025-12-11 21:50:42 +00:00
winget install nushell
# Verify installation
nu --version
2026-01-08 09:55:37 +00:00
```plaintext
### Configure Nushell
```bash
# Start Nushell
2025-12-11 21:50:42 +00:00
nu
# Configure (creates default config if not exists)
config nu
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 2: Install Nushell Plugins (Recommended)
Native plugins provide **10-50x performance improvement** for authentication, KMS, and orchestrator operations.
### Why Install Plugins?
**Performance Gains:**
- 🚀 **KMS operations**: ~5ms vs ~50ms (10x faster)
- 🚀 **Orchestrator queries**: ~1ms vs ~30ms (30x faster)
- 🚀 **Batch encryption**: 100 files in 0.5s vs 5s (10x faster)
**Benefits:**
- ✅ Native Nushell integration (pipelines, data structures)
- ✅ OS keyring for secure token storage
- ✅ Offline capability (Age encryption, local orchestrator)
- ✅ Graceful fallback to HTTP if not installed
### Prerequisites for Building Plugins
```bash
# Install Rust toolchain (if not already installed)
2025-12-11 21:50:42 +00:00
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustc --version
# Expected: rustc 1.75+ or higher
# Linux only: Install development packages
sudo apt install libssl-dev pkg-config # Ubuntu/Debian
sudo dnf install openssl-devel # Fedora
# Linux only: Install keyring service (required for auth plugin)
sudo apt install gnome-keyring # Ubuntu/Debian (GNOME)
sudo apt install kwalletmanager # Ubuntu/Debian (KDE)
2026-01-08 09:55:37 +00:00
```plaintext
### Build Plugins
```bash
# Navigate to plugins directory
2025-12-11 21:50:42 +00:00
cd provisioning/core/plugins/nushell-plugins
# Build all three plugins in release mode (optimized)
cargo build --release --all
# Expected output:
# Compiling nu_plugin_auth v0.1.0
# Compiling nu_plugin_kms v0.1.0
# Compiling nu_plugin_orchestrator v0.1.0
# Finished release [optimized] target(s) in 2m 15s
2026-01-08 09:55:37 +00:00
```plaintext
**Build time**: ~2-5 minutes depending on hardware
### Register Plugins with Nushell
```bash
# Register all three plugins (full paths recommended)
2025-12-11 21:50:42 +00:00
plugin add $PWD/target/release/nu_plugin_auth
plugin add $PWD/target/release/nu_plugin_kms
plugin add $PWD/target/release/nu_plugin_orchestrator
# Alternative (from plugins directory)
plugin add target/release/nu_plugin_auth
plugin add target/release/nu_plugin_kms
plugin add target/release/nu_plugin_orchestrator
2026-01-08 09:55:37 +00:00
```plaintext
### Verify Plugin Installation
```bash
# List registered plugins
2025-12-11 21:50:42 +00:00
plugin list | where name =~ "auth|kms|orch"
# Expected output:
# ╭───┬─────────────────────────┬─────────┬───────────────────────────────────╮
# │ # │ name │ version │ filename │
# ├───┼─────────────────────────┼─────────┼───────────────────────────────────┤
# │ 0 │ nu_plugin_auth │ 0.1.0 │ .../nu_plugin_auth │
# │ 1 │ nu_plugin_kms │ 0.1.0 │ .../nu_plugin_kms │
# │ 2 │ nu_plugin_orchestrator │ 0.1.0 │ .../nu_plugin_orchestrator │
# ╰───┴─────────────────────────┴─────────┴───────────────────────────────────╯
# Test each plugin
auth --help # Should show auth commands
kms --help # Should show kms commands
orch --help # Should show orch commands
2026-01-08 09:55:37 +00:00
```plaintext
### Configure Plugin Environments
```bash
# Add to ~/.config/nushell/env.nu
2025-12-11 21:50:42 +00:00
$env.CONTROL_CENTER_URL = "http://localhost:3000"
$env.RUSTYVAULT_ADDR = "http://localhost:8200"
$env.RUSTYVAULT_TOKEN = "your-vault-token-here"
$env.ORCHESTRATOR_DATA_DIR = "provisioning/platform/orchestrator/data"
# For Age encryption (local development)
$env.AGE_IDENTITY = $"($env.HOME)/.age/key.txt"
$env.AGE_RECIPIENT = "age1xxxxxxxxx" # Replace with your public key
2026-01-08 09:55:37 +00:00
```plaintext
### Test Plugins (Quick Smoke Test)
```bash
# Test KMS plugin (requires backend configured)
2025-12-11 21:50:42 +00:00
kms status
# Expected: { backend: "rustyvault", status: "healthy", ... }
# Or: Error if backend not configured (OK for now)
# Test orchestrator plugin (reads local files)
orch status
# Expected: { active_tasks: 0, completed_tasks: 0, health: "healthy" }
# Or: Error if orchestrator not started yet (OK for now)
# Test auth plugin (requires control center)
auth verify
# Expected: { active: false }
# Or: Error if control center not running (OK for now)
2026-01-08 09:55:37 +00:00
```plaintext
**Note**: It's OK if plugins show errors at this stage. We'll configure backends and services later.
### Skip Plugins? (Not Recommended)
If you want to skip plugin installation for now:
- ✅ All features work via HTTP API (slower but functional)
- ⚠️ You'll miss 10-50x performance improvements
- ⚠️ No offline capability for KMS/orchestrator
- ℹ ️
To use HTTP fallback:
```bash
# System automatically uses HTTP if plugins not available
2025-12-11 21:50:42 +00:00
# No configuration changes needed
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 3: Install Required Tools
### Essential Tools
**KCL (Configuration Language)**
```bash
# macOS
2025-12-11 21:50:42 +00:00
brew install kcl
# Linux
curl -fsSL https://kcl-lang.io/script/install.sh | /bin/bash
# Verify
kcl version
# Expected: 0.11.2 or higher
2026-01-08 09:55:37 +00:00
```plaintext
**SOPS (Secrets Management)**
```bash
# macOS
2025-12-11 21:50:42 +00:00
brew install sops
# Linux
wget https://github.com/mozilla/sops/releases/download/v3.10.2/sops-v3.10.2.linux.amd64
sudo mv sops-v3.10.2.linux.amd64 /usr/local/bin/sops
sudo chmod +x /usr/local/bin/sops
# Verify
sops --version
# Expected: 3.10.2 or higher
2026-01-08 09:55:37 +00:00
```plaintext
**Age (Encryption Tool)**
```bash
# macOS
2025-12-11 21:50:42 +00:00
brew install age
# Linux
sudo apt install age # Ubuntu/Debian
sudo dnf install age # Fedora
# Or from source
go install filippo.io/age/cmd/...@latest
# Verify
age --version
# Expected: 1.2.1 or higher
# Generate Age key (for local encryption)
age-keygen -o ~/.age/key.txt
cat ~/.age/key.txt
# Save the public key (age1...) for later
2026-01-08 09:55:37 +00:00
```plaintext
### Optional but Recommended Tools
**K9s (Kubernetes Management)**
```bash
# macOS
2025-12-11 21:50:42 +00:00
brew install k9s
# Linux
curl -sS https://webinstall.dev/k9s | bash
# Verify
k9s version
# Expected: 0.50.6 or higher
2026-01-08 09:55:37 +00:00
```plaintext
**glow (Markdown Renderer)**
```bash
# macOS
2025-12-11 21:50:42 +00:00
brew install glow
# Linux
sudo apt install glow # Ubuntu/Debian
sudo dnf install glow # Fedora
# Verify
glow --version
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 4: Clone and Setup Project
### Clone Repository
```bash
# Clone project
2025-12-11 21:50:42 +00:00
git clone https://github.com/your-org/project-provisioning.git
cd project-provisioning
# Or if already cloned, update to latest
git pull origin main
2026-01-08 09:55:37 +00:00
```plaintext
### Add CLI to PATH (Optional)
```bash
# Add to ~/.bashrc or ~/.zshrc
2025-12-11 21:50:42 +00:00
export PATH="$PATH:/Users/Akasha/project-provisioning/provisioning/core/cli"
# Or create symlink
sudo ln -s /Users/Akasha/project-provisioning/provisioning/core/cli/provisioning /usr/local/bin/provisioning
# Verify
provisioning version
# Expected: 3.5.0
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 5: Initialize Workspace
A workspace is a self-contained environment for managing infrastructure.
### Create New Workspace
```bash
# Initialize new workspace
2025-12-11 21:50:42 +00:00
provisioning workspace init --name production
# Or use interactive mode
provisioning workspace init
# Name: production
# Description: Production infrastructure
# Provider: upcloud
2026-01-08 09:55:37 +00:00
```plaintext
**What this creates:**
The new workspace initialization now generates **KCL (Kusion Configuration Language) configuration files** for type-safe, schema-validated infrastructure definitions:
```plaintext
workspace/
2025-12-11 21:50:42 +00:00
├── config/
2026-01-08 09:55:37 +00:00
│ ├── provisioning.k # Main KCL configuration (schema-validated)
│ ├── providers/
│ │ └── upcloud.toml # Provider-specific settings
│ ├── platform/ # Platform service configs
│ └── kms.toml # Key management settings
2025-12-11 21:50:42 +00:00
├── infra/ # Infrastructure definitions
├── extensions/ # Custom modules
└── runtime/ # Runtime data and state
2026-01-08 09:55:37 +00:00
```plaintext
### Workspace Configuration Format
The workspace configuration now uses **KCL (type-safe)** instead of YAML. This provides:
- ✅ **Type Safety**: Schema validation catches errors at load time
- ✅ **Immutability**: Enforces configuration immutability by default
- ✅ **Validation**: Semantic versioning, required fields, value constraints
- ✅ **Documentation**: Self-documenting with schema descriptions
**Example KCL config** (`provisioning.k`):
```kcl
import provisioning.workspace_config as ws
workspace_config = ws.WorkspaceConfig {
workspace: {
name: "production"
version: "1.0.0"
created: "2025-12-03T14:30:00Z"
}
paths: {
base: "/opt/workspaces/production"
infra: "/opt/workspaces/production/infra"
cache: "/opt/workspaces/production/.cache"
# ... other paths
}
providers: {
active: ["upcloud"]
default: "upcloud"
}
# ... other sections
}
```plaintext
**Backward Compatibility**: If you have existing YAML workspace configs (`provisioning.yaml`), they continue to work. The config loader checks for KCL files first, then falls back to YAML.
### Verify Workspace
```bash
# Show workspace info
2025-12-11 21:50:42 +00:00
provisioning workspace info
# List all workspaces
provisioning workspace list
# Show active workspace
provisioning workspace active
# Expected: production
2026-01-08 09:55:37 +00:00
```plaintext
### View and Validate Workspace Configuration
Now you can inspect and validate your KCL workspace configuration:
```bash
# View complete workspace configuration
provisioning workspace config show
# Show specific workspace
provisioning workspace config show production
# View configuration in different formats
provisioning workspace config show --format=json
provisioning workspace config show --format=yaml
provisioning workspace config show --format=kcl # Raw KCL file
# Validate workspace configuration
provisioning workspace config validate
# Output: ✅ Validation complete - all configs are valid
# Show configuration hierarchy (priority order)
provisioning workspace config hierarchy
```plaintext
**Configuration Validation**: The KCL schema automatically validates:
- ✅ Semantic versioning format (e.g., "1.0.0")
- ✅ Required sections present (workspace, paths, provisioning, etc.)
- ✅ Valid file paths and types
- ✅ Provider configuration exists for active providers
- ✅ KMS and SOPS settings properly configured
---
## Step 6: Configure Environment
### Set Provider Credentials
**UpCloud Provider:**
```bash
# Create provider config
2025-12-11 21:50:42 +00:00
vim workspace/config/providers/upcloud.toml
2026-01-08 09:55:37 +00:00
```plaintext
```toml
[upcloud]
2025-12-11 21:50:42 +00:00
username = "your-upcloud-username"
password = "your-upcloud-password" # Will be encrypted
# Default settings
default_zone = "de-fra1"
default_plan = "2xCPU-4GB"
2026-01-08 09:55:37 +00:00
```plaintext
**AWS Provider:**
```bash
# Create AWS config
2025-12-11 21:50:42 +00:00
vim workspace/config/providers/aws.toml
2026-01-08 09:55:37 +00:00
```plaintext
```toml
[aws]
2025-12-11 21:50:42 +00:00
region = "us-east-1"
access_key_id = "AKIAXXXXX"
secret_access_key = "xxxxx" # Will be encrypted
# Default settings
default_instance_type = "t3.medium"
default_region = "us-east-1"
2026-01-08 09:55:37 +00:00
```plaintext
### Encrypt Sensitive Data
```bash
# Generate Age key if not done already
2025-12-11 21:50:42 +00:00
age-keygen -o ~/.age/key.txt
# Encrypt provider configs
kms encrypt (open workspace/config/providers/upcloud.toml) --backend age \
| save workspace/config/providers/upcloud.toml.enc
# Or use SOPS
sops --encrypt --age $(cat ~/.age/key.txt | grep "public key:" | cut -d: -f2) \
workspace/config/providers/upcloud.toml > workspace/config/providers/upcloud.toml.enc
# Remove plaintext
rm workspace/config/providers/upcloud.toml
2026-01-08 09:55:37 +00:00
```plaintext
### Configure Local Overrides
```bash
# Edit user-specific settings
2025-12-11 21:50:42 +00:00
vim workspace/config/local-overrides.toml
2026-01-08 09:55:37 +00:00
```plaintext
```toml
[user]
2025-12-11 21:50:42 +00:00
name = "admin"
email = "admin@example.com"
[preferences]
editor = "vim"
output_format = "yaml"
confirm_delete = true
confirm_deploy = true
[http]
use_curl = true # Use curl instead of ureq
[paths]
ssh_key = "~/.ssh/id_ed25519"
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 7: Discover and Load Modules
### Discover Available Modules
```bash
# Discover task services
2025-12-11 21:50:42 +00:00
provisioning module discover taskserv
# Shows: kubernetes, containerd, etcd, cilium, helm, etc.
# Discover providers
provisioning module discover provider
# Shows: upcloud, aws, local
# Discover clusters
provisioning module discover cluster
# Shows: buildkit, registry, monitoring, etc.
2026-01-08 09:55:37 +00:00
```plaintext
### Load Modules into Workspace
```bash
# Load Kubernetes taskserv
2025-12-11 21:50:42 +00:00
provisioning module load taskserv production kubernetes
# Load multiple modules
provisioning module load taskserv production kubernetes containerd cilium
# Load cluster configuration
provisioning module load cluster production buildkit
# Verify loaded modules
provisioning module list taskserv production
provisioning module list cluster production
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 8: Validate Configuration
Before deploying, validate all configuration:
```bash
# Validate workspace configuration
2025-12-11 21:50:42 +00:00
provisioning workspace validate
# Validate infrastructure configuration
provisioning validate config
# Validate specific infrastructure
provisioning infra validate --infra production
# Check environment variables
provisioning env
# Show all configuration and environment
provisioning allenv
2026-01-08 09:55:37 +00:00
```plaintext
**Expected output:**
```plaintext
✓ Configuration valid
2025-12-11 21:50:42 +00:00
✓ Provider credentials configured
✓ Workspace initialized
✓ Modules loaded: 3 taskservs, 1 cluster
✓ SSH key configured
✓ Age encryption key available
2026-01-08 09:55:37 +00:00
```plaintext
**Fix any errors** before proceeding to deployment.
---
## Step 9: Deploy Servers
### Preview Server Creation (Dry Run)
```bash
# Check what would be created (no actual changes)
2025-12-11 21:50:42 +00:00
provisioning server create --infra production --check
# With debug output for details
provisioning server create --infra production --check --debug
2026-01-08 09:55:37 +00:00
```plaintext
**Review the output:**
- Server names and configurations
- Zones and regions
- CPU, memory, disk specifications
- Estimated costs
- Network settings
### Create Servers
```bash
# Create servers (with confirmation prompt)
2025-12-11 21:50:42 +00:00
provisioning server create --infra production
# Or auto-confirm (skip prompt)
provisioning server create --infra production --yes
# Wait for completion
provisioning server create --infra production --wait
2026-01-08 09:55:37 +00:00
```plaintext
**Expected output:**
```plaintext
Creating servers for infrastructure: production
2025-12-11 21:50:42 +00:00
● Creating server: k8s-master-01 (de-fra1, 4xCPU-8GB)
● Creating server: k8s-worker-01 (de-fra1, 4xCPU-8GB)
● Creating server: k8s-worker-02 (de-fra1, 4xCPU-8GB)
✓ Created 3 servers in 120 seconds
Servers:
• k8s-master-01: 192.168.1.10 (Running)
• k8s-worker-01: 192.168.1.11 (Running)
• k8s-worker-02: 192.168.1.12 (Running)
2026-01-08 09:55:37 +00:00
```plaintext
### Verify Server Creation
```bash
# List all servers
2025-12-11 21:50:42 +00:00
provisioning server list --infra production
# Show detailed server info
provisioning server list --infra production --out yaml
# SSH to server (test connectivity)
provisioning server ssh k8s-master-01
# Type 'exit' to return
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 10: Install Task Services
Task services are infrastructure components like Kubernetes, databases, monitoring, etc.
### Install Kubernetes (Check Mode First)
```bash
# Preview Kubernetes installation
2025-12-11 21:50:42 +00:00
provisioning taskserv create kubernetes --infra production --check
# Shows:
# - Dependencies required (containerd, etcd)
# - Configuration to be applied
# - Resources needed
# - Estimated installation time
2026-01-08 09:55:37 +00:00
```plaintext
### Install Kubernetes
```bash
# Install Kubernetes (with dependencies)
2025-12-11 21:50:42 +00:00
provisioning taskserv create kubernetes --infra production
# Or install dependencies first
provisioning taskserv create containerd --infra production
provisioning taskserv create etcd --infra production
provisioning taskserv create kubernetes --infra production
# Monitor progress
provisioning workflow monitor < task_id>
2026-01-08 09:55:37 +00:00
```plaintext
**Expected output:**
```plaintext
Installing taskserv: kubernetes
2025-12-11 21:50:42 +00:00
● Installing containerd on k8s-master-01
● Installing containerd on k8s-worker-01
● Installing containerd on k8s-worker-02
✓ Containerd installed (30s)
● Installing etcd on k8s-master-01
✓ etcd installed (20s)
● Installing Kubernetes control plane on k8s-master-01
✓ Kubernetes control plane ready (45s)
● Joining worker nodes
✓ k8s-worker-01 joined (15s)
✓ k8s-worker-02 joined (15s)
✓ Kubernetes installation complete (125 seconds)
Cluster Info:
• Version: 1.28.0
• Nodes: 3 (1 control-plane, 2 workers)
• API Server: https://192.168.1.10:6443
2026-01-08 09:55:37 +00:00
```plaintext
### Install Additional Services
```bash
# Install Cilium (CNI)
2025-12-11 21:50:42 +00:00
provisioning taskserv create cilium --infra production
# Install Helm
provisioning taskserv create helm --infra production
# Verify all taskservs
provisioning taskserv list --infra production
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 11: Create Clusters
Clusters are complete application stacks (e.g., BuildKit, OCI Registry, Monitoring).
### Create BuildKit Cluster (Check Mode)
```bash
# Preview cluster creation
2025-12-11 21:50:42 +00:00
provisioning cluster create buildkit --infra production --check
# Shows:
# - Components to be deployed
# - Dependencies required
# - Configuration values
# - Resource requirements
2026-01-08 09:55:37 +00:00
```plaintext
### Create BuildKit Cluster
```bash
# Create BuildKit cluster
2025-12-11 21:50:42 +00:00
provisioning cluster create buildkit --infra production
# Monitor deployment
provisioning workflow monitor < task_id>
# Or use plugin for faster monitoring
orch tasks --status running
2026-01-08 09:55:37 +00:00
```plaintext
**Expected output:**
```plaintext
Creating cluster: buildkit
2025-12-11 21:50:42 +00:00
● Deploying BuildKit daemon
● Deploying BuildKit worker
● Configuring BuildKit cache
● Setting up BuildKit registry integration
✓ BuildKit cluster ready (60 seconds)
Cluster Info:
• BuildKit version: 0.12.0
• Workers: 2
• Cache: 50GB
• Registry: registry.production.local
2026-01-08 09:55:37 +00:00
```plaintext
### Verify Cluster
```bash
# List all clusters
2025-12-11 21:50:42 +00:00
provisioning cluster list --infra production
# Show cluster details
provisioning cluster list --infra production --out yaml
# Check cluster health
kubectl get pods -n buildkit
2026-01-08 09:55:37 +00:00
```plaintext
---
## Step 12: Verify Deployment
### Comprehensive Health Check
```bash
# Check orchestrator status
2025-12-11 21:50:42 +00:00
orch status
# or
provisioning orchestrator status
# Check all servers
provisioning server list --infra production
# Check all taskservs
provisioning taskserv list --infra production
# Check all clusters
provisioning cluster list --infra production
# Verify Kubernetes cluster
kubectl get nodes
kubectl get pods --all-namespaces
2026-01-08 09:55:37 +00:00
```plaintext
### Run Validation Tests
```bash
# Validate infrastructure
2025-12-11 21:50:42 +00:00
provisioning infra validate --infra production
# Test connectivity
provisioning server ssh k8s-master-01 "kubectl get nodes"
# Test BuildKit
kubectl exec -it -n buildkit buildkit-0 -- buildctl --version
2026-01-08 09:55:37 +00:00
```plaintext
### Expected Results
All checks should show:
- ✅ Servers: Running
- ✅ Taskservs: Installed and healthy
- ✅ Clusters: Deployed and operational
- ✅ Kubernetes: 3/3 nodes ready
- ✅ BuildKit: 2/2 workers ready
---
## Step 13: Post-Deployment
### Configure kubectl Access
```bash
# Get kubeconfig from master node
2025-12-11 21:50:42 +00:00
provisioning server ssh k8s-master-01 "cat ~/.kube/config" > ~/.kube/config-production
# Set KUBECONFIG
export KUBECONFIG=~/.kube/config-production
# Verify access
kubectl get nodes
kubectl get pods --all-namespaces
2026-01-08 09:55:37 +00:00
```plaintext
### Set Up Monitoring (Optional)
```bash
# Deploy monitoring stack
2025-12-11 21:50:42 +00:00
provisioning cluster create monitoring --infra production
# Access Grafana
kubectl port-forward -n monitoring svc/grafana 3000:80
# Open: http://localhost:3000
2026-01-08 09:55:37 +00:00
```plaintext
### Configure CI/CD Integration (Optional)
```bash
# Generate CI/CD credentials
2025-12-11 21:50:42 +00:00
provisioning secrets generate aws --ttl 12h
# Create CI/CD kubeconfig
kubectl create serviceaccount ci-cd -n default
kubectl create clusterrolebinding ci-cd --clusterrole=admin --serviceaccount=default:ci-cd
2026-01-08 09:55:37 +00:00
```plaintext
### Backup Configuration
```bash
# Backup workspace configuration
2025-12-11 21:50:42 +00:00
tar -czf workspace-production-backup.tar.gz workspace/
# Encrypt backup
kms encrypt (open workspace-production-backup.tar.gz | encode base64) --backend age \
| save workspace-production-backup.tar.gz.enc
# Store securely (S3, Vault, etc.)
2026-01-08 09:55:37 +00:00
```plaintext
---
## Troubleshooting
### Server Creation Fails
**Problem**: Server creation times out or fails
```bash
# Check provider credentials
2025-12-11 21:50:42 +00:00
provisioning validate config
# Check provider API status
curl -u username:password https://api.upcloud.com/1.3/account
# Try with debug mode
provisioning server create --infra production --check --debug
2026-01-08 09:55:37 +00:00
```plaintext
### Taskserv Installation Fails
**Problem**: Kubernetes installation fails
```bash
# Check server connectivity
2025-12-11 21:50:42 +00:00
provisioning server ssh k8s-master-01
# Check logs
provisioning orchestrator logs | grep kubernetes
# Check dependencies
provisioning taskserv list --infra production | where status == "failed"
# Retry installation
provisioning taskserv delete kubernetes --infra production
provisioning taskserv create kubernetes --infra production
2026-01-08 09:55:37 +00:00
```plaintext
### Plugin Commands Don't Work
**Problem**: `auth`, `kms`, or `orch` commands not found
```bash
# Check plugin registration
2025-12-11 21:50:42 +00:00
plugin list | where name =~ "auth|kms|orch"
# Re-register if missing
cd provisioning/core/plugins/nushell-plugins
plugin add target/release/nu_plugin_auth
plugin add target/release/nu_plugin_kms
plugin add target/release/nu_plugin_orchestrator
# Restart Nushell
exit
nu
2026-01-08 09:55:37 +00:00
```plaintext
### KMS Encryption Fails
**Problem**: `kms encrypt` returns error
```bash
# Check backend status
2025-12-11 21:50:42 +00:00
kms status
# Check RustyVault running
curl http://localhost:8200/v1/sys/health
# Use Age backend instead (local)
kms encrypt "data" --backend age --key age1xxxxxxxxx
# Check Age key
cat ~/.age/key.txt
2026-01-08 09:55:37 +00:00
```plaintext
### Orchestrator Not Running
**Problem**: `orch status` returns error
```bash
# Check orchestrator status
2025-12-11 21:50:42 +00:00
ps aux | grep orchestrator
# Start orchestrator
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background
# Check logs
tail -f provisioning/platform/orchestrator/data/orchestrator.log
2026-01-08 09:55:37 +00:00
```plaintext
### Configuration Validation Errors
**Problem**: `provisioning validate config` shows errors
```bash
# Show detailed errors
2025-12-11 21:50:42 +00:00
provisioning validate config --debug
# Check configuration files
provisioning allenv
# Fix missing settings
vim workspace/config/local-overrides.toml
2026-01-08 09:55:37 +00:00
```plaintext
---
## Next Steps
### Explore Advanced Features
1. **Multi-Environment Deployment**
```bash
# Create dev and staging workspaces
provisioning workspace create dev
provisioning workspace create staging
provisioning workspace switch dev
2025-12-11 21:50:42 +00:00
< / code > < / pre >
< ol >
< li >
< p > < strong > Batch Operations< / strong > < / p >
< pre > < code class = "language-bash" > # Deploy to multiple clouds
provisioning batch submit workflows/multi-cloud-deploy.k
< / code > < / pre >
< / li >
< li >
< p > < strong > Security Features< / strong > < / p >
< pre > < code class = "language-bash" > # Enable MFA
auth mfa enroll totp
# Set up break-glass
provisioning break-glass request "Emergency access"
< / code > < / pre >
< / li >
< li >
< p > < strong > Compliance and Audit< / strong > < / p >
< pre > < code class = "language-bash" > # Generate compliance report
provisioning compliance report --standard soc2
< / code > < / pre >
< / li >
< / ol >
< h3 id = "learn-more" > < a class = "header" href = "#learn-more" > Learn More< / a > < / h3 >
< ul >
< li > < strong > Quick Reference< / strong > : < code > provisioning sc< / code > or < code > docs/guides/quickstart-cheatsheet.md< / code > < / li >
< li > < strong > Update Guide< / strong > : < code > docs/guides/update-infrastructure.md< / code > < / li >
< li > < strong > Customize Guide< / strong > : < code > docs/guides/customize-infrastructure.md< / code > < / li >
< li > < strong > Plugin Guide< / strong > : < code > docs/user/PLUGIN_INTEGRATION_GUIDE.md< / code > < / li >
< li > < strong > Security System< / strong > : < code > docs/architecture/ADR-009-security-system-complete.md< / code > < / li >
< / ul >
< h3 id = "get-help" > < a class = "header" href = "#get-help" > Get Help< / a > < / h3 >
< pre > < code class = "language-bash" > # Show help for any command
provisioning help
provisioning help server
provisioning help taskserv
# Check version
provisioning version
# Start Nushell session with provisioning library
provisioning nu
2026-01-08 09:55:37 +00:00
```plaintext
---
## Summary
You've successfully:
✅ Installed Nushell and essential tools
2025-12-11 21:50:42 +00:00
✅ Built and registered native plugins (10-50x faster operations)
✅ Cloned and configured the project
✅ Initialized a production workspace
✅ Configured provider credentials
✅ Deployed servers
✅ Installed Kubernetes and task services
✅ Created application clusters
2026-01-08 09:55:37 +00:00
✅ Verified complete deployment
**Your infrastructure is now ready for production use!**
---
**Estimated Total Time**: 30-60 minutes
**Next Guide**: [Update Infrastructure](update-infrastructure.md)
**Questions?**: Open an issue or contact < platform-team@example.com>
**Last Updated**: 2025-10-09
**Version**: 3.5.0
< / code > < / pre >
2025-12-11 21:50:42 +00:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../troubleshooting/troubleshooting-guide.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next prefetch" href = "../guides/update-infrastructure.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" >
2026-01-08 09:55:37 +00:00
< a rel = "prev" href = "../troubleshooting/troubleshooting-guide.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
2025-12-11 21:50:42 +00:00
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next prefetch" href = "../guides/update-infrastructure.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 >
< 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 >
