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" >
< title > Customize Infrastructure - Provisioning Platform Documentation< / title >
<!-- Custom HTML head -->
2026-01-14 01:56:30 +00:00
< meta name = "description" content = "Complete documentation for the Provisioning Platform - Infrastructure automation with Nushell, Nickel, and Rust" >
2025-12-11 21:50:42 +00:00
< 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/customize-infrastructure.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 >
2026-01-08 09:55:37 +00:00
< h1 id = "customize-infrastructure" > < a class = "header" href = "#customize-infrastructure" > Customize Infrastructure< / a > < / h1 >
< p > < strong > Goal< / strong > : Customize infrastructure using layers, templates, and configuration patterns
< strong > Time< / strong > : 20-40 minutes
< strong > Difficulty< / strong > : Intermediate to Advanced< / p >
2025-12-11 21:50:42 +00:00
< h2 id = "overview" > < a class = "header" href = "#overview" > Overview< / a > < / h2 >
2026-01-08 09:55:37 +00:00
< p > This guide covers:< / p >
< ol >
< li > Understanding the layer system< / li >
< li > Using templates< / li >
< li > Creating custom modules< / li >
< li > Configuration inheritance< / li >
< li > Advanced customization patterns< / li >
< / ol >
< h2 id = "the-layer-system" > < a class = "header" href = "#the-layer-system" > The Layer System< / a > < / h2 >
< h3 id = "understanding-layers" > < a class = "header" href = "#understanding-layers" > Understanding Layers< / a > < / h3 >
< p > The provisioning system uses a < strong > 3-layer architecture< / strong > for configuration inheritance:< / p >
< pre > < code class = "language-plaintext" > ┌─────────────────────────────────────┐
│ Infrastructure Layer (Priority 300)│ ← Highest priority
│ workspace/infra/{name}/ │
│ • Project-specific configs │
│ • Environment customizations │
│ • Local overrides │
└─────────────────────────────────────┘
↓ overrides
┌─────────────────────────────────────┐
│ Workspace Layer (Priority 200) │
│ provisioning/workspace/templates/ │
│ • Reusable patterns │
│ • Organization standards │
│ • Team conventions │
└─────────────────────────────────────┘
↓ overrides
┌─────────────────────────────────────┐
│ Core Layer (Priority 100) │ ← Lowest priority
│ provisioning/extensions/ │
│ • System defaults │
│ • Provider implementations │
│ • Default taskserv configs │
└─────────────────────────────────────┘
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Resolution Order< / strong > : Infrastructure (300) → Workspace (200) → Core (100)< / p >
< p > Higher numbers override lower numbers.< / p >
< h3 id = "view-layer-resolution" > < a class = "header" href = "#view-layer-resolution" > View Layer Resolution< / a > < / h3 >
< pre > < code class = "language-bash" > # Explain layer concept
2026-01-08 09:55:37 +00:00
provisioning lyr explain
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 📚 LAYER SYSTEM EXPLAINED
2026-01-08 09:55:37 +00:00
The layer system provides configuration inheritance across 3 levels:
🔵 CORE LAYER (100) - System Defaults
Location: provisioning/extensions/
• Base taskserv configurations
• Default provider settings
• Standard cluster templates
• Built-in extensions
🟢 WORKSPACE LAYER (200) - Shared Templates
Location: provisioning/workspace/templates/
• Organization-wide patterns
• Reusable configurations
• Team standards
• Custom extensions
🔴 INFRASTRUCTURE LAYER (300) - Project Specific
Location: workspace/infra/{project}/
• Project-specific overrides
• Environment customizations
• Local modifications
• Runtime settings
Resolution: Infrastructure → Workspace → Core
Higher priority layers override lower ones.
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< pre > < code class = "language-bash" > # Show layer resolution for your project
2026-01-08 09:55:37 +00:00
provisioning lyr show my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 📊 Layer Resolution for my-production:
2026-01-08 09:55:37 +00:00
LAYER PRIORITY SOURCE FILES
Infrastructure 300 workspace/infra/my-production/ 4 files
2026-01-12 04:42:18 +00:00
• servers.ncl (overrides)
• taskservs.ncl (overrides)
• clusters.ncl (custom)
• providers.ncl (overrides)
2026-01-08 09:55:37 +00:00
Workspace 200 provisioning/workspace/templates/ 2 files
2026-01-12 04:42:18 +00:00
• production.ncl (used)
• kubernetes.ncl (used)
2026-01-08 09:55:37 +00:00
Core 100 provisioning/extensions/ 15 files
• taskservs/* (base configs)
• providers/* (default settings)
• clusters/* (templates)
Resolution Order: Infrastructure → Workspace → Core
Status: ✅ All layers resolved successfully
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "test-layer-resolution" > < a class = "header" href = "#test-layer-resolution" > Test Layer Resolution< / a > < / h3 >
< pre > < code class = "language-bash" > # Test how a specific module resolves
2026-01-08 09:55:37 +00:00
provisioning lyr test kubernetes my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 🔍 Layer Resolution Test: kubernetes → my-production
2026-01-08 09:55:37 +00:00
Resolving kubernetes configuration...
🔴 Infrastructure Layer (300):
2026-01-12 04:42:18 +00:00
✅ Found: workspace/infra/my-production/taskservs/kubernetes.ncl
2026-01-08 09:55:37 +00:00
Provides:
• version = "1.30.0" (overrides)
• control_plane_servers = ["web-01"] (overrides)
• worker_servers = ["web-02"] (overrides)
🟢 Workspace Layer (200):
2026-01-12 04:42:18 +00:00
✅ Found: provisioning/workspace/templates/production-kubernetes.ncl
2026-01-08 09:55:37 +00:00
Provides:
• security_policies (inherited)
• network_policies (inherited)
• resource_quotas (inherited)
🔵 Core Layer (100):
2026-01-12 04:42:18 +00:00
✅ Found: provisioning/extensions/taskservs/kubernetes/main.ncl
2026-01-08 09:55:37 +00:00
Provides:
• default_version = "1.29.0" (base)
• default_features (base)
• default_plugins (base)
Final Configuration (after merging all layers):
version: "1.30.0" (from Infrastructure)
control_plane_servers: ["web-01"] (from Infrastructure)
worker_servers: ["web-02"] (from Infrastructure)
security_policies: {...} (from Workspace)
network_policies: {...} (from Workspace)
resource_quotas: {...} (from Workspace)
default_features: {...} (from Core)
default_plugins: {...} (from Core)
Resolution: ✅ Success
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "using-templates" > < a class = "header" href = "#using-templates" > Using Templates< / a > < / h2 >
< h3 id = "list-available-templates" > < a class = "header" href = "#list-available-templates" > List Available Templates< / a > < / h3 >
< pre > < code class = "language-bash" > # List all templates
2026-01-08 09:55:37 +00:00
provisioning tpl list
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 📋 Available Templates:
2026-01-08 09:55:37 +00:00
TASKSERVS:
• production-kubernetes - Production-ready Kubernetes setup
• production-postgres - Production PostgreSQL with replication
• production-redis - Redis cluster with sentinel
• development-kubernetes - Development Kubernetes (minimal)
• ci-cd-pipeline - Complete CI/CD pipeline
PROVIDERS:
• upcloud-production - UpCloud production settings
• upcloud-development - UpCloud development settings
• aws-production - AWS production VPC setup
• aws-development - AWS development environment
• local-docker - Local Docker-based setup
CLUSTERS:
• buildkit-cluster - BuildKit for container builds
• monitoring-stack - Prometheus + Grafana + Loki
• security-stack - Security monitoring tools
Total: 13 templates
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< pre > < code class = "language-bash" > # List templates by type
2026-01-08 09:55:37 +00:00
provisioning tpl list --type taskservs
provisioning tpl list --type providers
provisioning tpl list --type clusters
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "view-template-details" > < a class = "header" href = "#view-template-details" > View Template Details< / a > < / h3 >
< pre > < code class = "language-bash" > # Show template details
2026-01-08 09:55:37 +00:00
provisioning tpl show production-kubernetes
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 📄 Template: production-kubernetes
2026-01-08 09:55:37 +00:00
Description: Production-ready Kubernetes configuration with
security hardening, network policies, and monitoring
Category: taskservs
Version: 1.0.0
Configuration Provided:
• Kubernetes version: 1.30.0
• Security policies: Pod Security Standards (restricted)
• Network policies: Default deny + allow rules
• Resource quotas: Per-namespace limits
• Monitoring: Prometheus integration
• Logging: Loki integration
• Backup: Velero configuration
Requirements:
• Minimum 2 servers
2026-01-12 04:42:18 +00:00
• 4 GB RAM per server
2026-01-08 09:55:37 +00:00
• Network plugin (Cilium recommended)
2026-01-12 04:42:18 +00:00
Location: provisioning/workspace/templates/production-kubernetes.ncl
2026-01-08 09:55:37 +00:00
Example Usage:
provisioning tpl apply production-kubernetes my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "apply-template" > < a class = "header" href = "#apply-template" > Apply Template< / a > < / h3 >
< pre > < code class = "language-bash" > # Apply template to your infrastructure
2026-01-08 09:55:37 +00:00
provisioning tpl apply production-kubernetes my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 🚀 Applying template: production-kubernetes → my-production
2026-01-08 09:55:37 +00:00
Checking compatibility... ⏳
✅ Infrastructure compatible with template
Merging configuration... ⏳
✅ Configuration merged
Files created/updated:
2026-01-12 04:42:18 +00:00
• workspace/infra/my-production/taskservs/kubernetes.ncl (updated)
• workspace/infra/my-production/policies/security.ncl (created)
• workspace/infra/my-production/policies/network.ncl (created)
• workspace/infra/my-production/monitoring/prometheus.ncl (created)
2026-01-08 09:55:37 +00:00
🎉 Template applied successfully!
Next steps:
1. Review generated configuration
2. Adjust as needed
3. Deploy: provisioning t create kubernetes --infra my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "validate-template-usage" > < a class = "header" href = "#validate-template-usage" > Validate Template Usage< / a > < / h3 >
< pre > < code class = "language-bash" > # Validate template was applied correctly
2026-01-08 09:55:37 +00:00
provisioning tpl validate my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > ✅ Template Validation: my-production
2026-01-08 09:55:37 +00:00
Templates Applied:
✅ production-kubernetes (v1.0.0)
✅ production-postgres (v1.0.0)
Configuration Status:
✅ All required fields present
✅ No conflicting settings
✅ Dependencies satisfied
Compliance:
✅ Security policies configured
✅ Network policies configured
✅ Resource quotas set
✅ Monitoring enabled
Status: ✅ Valid
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "creating-custom-templates" > < a class = "header" href = "#creating-custom-templates" > Creating Custom Templates< / a > < / h2 >
< h3 id = "step-1-create-template-structure" > < a class = "header" href = "#step-1-create-template-structure" > Step 1: Create Template Structure< / a > < / h3 >
< pre > < code class = "language-bash" > # Create custom template directory
2026-01-08 09:55:37 +00:00
mkdir -p provisioning/workspace/templates/my-custom-template
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "step-2-write-template-configuration" > < a class = "header" href = "#step-2-write-template-configuration" > Step 2: Write Template Configuration< / a > < / h3 >
< p > < strong > File: < code > provisioning/workspace/templates/my-custom-template/main.ncl< / code > < / strong > < / p >
< pre > < code class = "language-nickel" > # Custom Kubernetes template with specific settings
let kubernetes_config = {
# Version
version = "1.30.0",
# Custom feature gates
feature_gates = {
"GracefulNodeShutdown" = true,
"SeccompDefault" = true,
"StatefulSetAutoDeletePVC" = true,
},
# Custom kubelet configuration
kubelet_config = {
max_pods = 110,
pod_pids_limit = 4096,
container_log_max_size = "10Mi",
container_log_max_files = 5,
},
# Custom API server flags
apiserver_extra_args = {
"enable-admission-plugins" = "NodeRestriction,PodSecurity,LimitRanger",
"audit-log-maxage" = "30",
"audit-log-maxbackup" = "10",
},
# Custom scheduler configuration
scheduler_config = {
profiles = [
{
name = "high-availability",
plugins = {
score = {
enabled = [
{name = "NodeResourcesBalancedAllocation", weight = 2},
{name = "NodeResourcesLeastAllocated", weight = 1},
],
},
},
},
],
},
# Network configuration
network = {
service_cidr = "10.96.0.0/12",
pod_cidr = "10.244.0.0/16",
dns_domain = "cluster.local",
},
# Security configuration
security = {
pod_security_standard = "restricted",
encrypt_etcd = true,
rotate_certificates = true,
},
} in
kubernetes_config
< / code > < / pre >
< h3 id = "step-3-create-template-metadata" > < a class = "header" href = "#step-3-create-template-metadata" > Step 3: Create Template Metadata< / a > < / h3 >
< p > < strong > File: < code > provisioning/workspace/templates/my-custom-template/metadata.toml< / code > < / strong > < / p >
< pre > < code class = "language-toml" > [template]
2026-01-08 09:55:37 +00:00
name = "my-custom-template"
version = "1.0.0"
description = "Custom Kubernetes template with enhanced security"
category = "taskservs"
author = "Your Name"
[requirements]
min_servers = 2
min_memory_gb = 4
required_taskservs = ["containerd", "cilium"]
[tags]
environment = ["production", "staging"]
features = ["security", "monitoring", "high-availability"]
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "step-4-test-custom-template" > < a class = "header" href = "#step-4-test-custom-template" > Step 4: Test Custom Template< / a > < / h3 >
< pre > < code class = "language-bash" > # List templates (should include your custom template)
2026-01-08 09:55:37 +00:00
provisioning tpl list
# Show your template
provisioning tpl show my-custom-template
# Apply to test infrastructure
provisioning tpl apply my-custom-template my-test
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "configuration-inheritance-examples" > < a class = "header" href = "#configuration-inheritance-examples" > Configuration Inheritance Examples< / a > < / h2 >
< h3 id = "example-1-override-single-value" > < a class = "header" href = "#example-1-override-single-value" > Example 1: Override Single Value< / a > < / h3 >
< p > < strong > Core Layer< / strong > (< code > provisioning/extensions/taskservs/postgres/main.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let postgres_config = {
version = "15.5",
port = 5432,
max_connections = 100,
} in
postgres_config
< / code > < / pre >
< p > < strong > Infrastructure Layer< / strong > (< code > workspace/infra/my-production/taskservs/postgres.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let postgres_config = {
max_connections = 500, # Override only max_connections
} in
postgres_config
< / code > < / pre >
< p > < strong > Result< / strong > (after layer resolution):< / p >
< pre > < code class = "language-nickel" > let postgres_config = {
version = "15.5", # From Core
port = 5432, # From Core
max_connections = 500, # From Infrastructure (overridden)
} in
postgres_config
< / code > < / pre >
< h3 id = "example-2-add-custom-configuration" > < a class = "header" href = "#example-2-add-custom-configuration" > Example 2: Add Custom Configuration< / a > < / h3 >
< p > < strong > Workspace Layer< / strong > (< code > provisioning/workspace/templates/production-postgres.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let postgres_config = {
replication = {
enabled = true,
replicas = 2,
sync_mode = "async",
},
} in
postgres_config
< / code > < / pre >
< p > < strong > Infrastructure Layer< / strong > (< code > workspace/infra/my-production/taskservs/postgres.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let postgres_config = {
replication = {
sync_mode = "sync", # Override sync mode
},
custom_extensions = ["pgvector", "timescaledb"], # Add custom config
} in
postgres_config
< / code > < / pre >
< p > < strong > Result< / strong > :< / p >
< pre > < code class = "language-nickel" > let postgres_config = {
version = "15.5", # From Core
port = 5432, # From Core
max_connections = 100, # From Core
replication = {
enabled = true, # From Workspace
replicas = 2, # From Workspace
sync_mode = "sync", # From Infrastructure (overridden)
},
custom_extensions = ["pgvector", "timescaledb"], # From Infrastructure (added)
} in
postgres_config
< / code > < / pre >
< h3 id = "example-3-environment-specific-configuration" > < a class = "header" href = "#example-3-environment-specific-configuration" > Example 3: Environment-Specific Configuration< / a > < / h3 >
< p > < strong > Workspace Layer< / strong > (< code > provisioning/workspace/templates/base-kubernetes.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let kubernetes_config = {
version = "1.30.0",
control_plane_count = 3,
worker_count = 5,
resources = {
control_plane = {cpu = "4", memory = "8Gi"},
worker = {cpu = "8", memory = "16Gi"},
},
} in
kubernetes_config
< / code > < / pre >
< p > < strong > Development Infrastructure< / strong > (< code > workspace/infra/my-dev/taskservs/kubernetes.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let kubernetes_config = {
control_plane_count = 1, # Smaller for dev
worker_count = 2,
resources = {
control_plane = {cpu = "2", memory = "4Gi"},
worker = {cpu = "2", memory = "4Gi"},
},
} in
kubernetes_config
< / code > < / pre >
< p > < strong > Production Infrastructure< / strong > (< code > workspace/infra/my-prod/taskservs/kubernetes.ncl< / code > ):< / p >
< pre > < code class = "language-nickel" > let kubernetes_config = {
control_plane_count = 5, # Larger for prod
worker_count = 10,
resources = {
control_plane = {cpu = "8", memory = "16Gi"},
worker = {cpu = "16", memory = "32Gi"},
},
} in
kubernetes_config
< / code > < / pre >
< h2 id = "advanced-customization-patterns" > < a class = "header" href = "#advanced-customization-patterns" > Advanced Customization Patterns< / a > < / h2 >
< h3 id = "pattern-1-multi-environment-setup" > < a class = "header" href = "#pattern-1-multi-environment-setup" > Pattern 1: Multi-Environment Setup< / a > < / h3 >
< p > Create different configurations for each environment:< / p >
< pre > < code class = "language-bash" > # Create environments
2026-01-08 09:55:37 +00:00
provisioning ws init my-app-dev
provisioning ws init my-app-staging
provisioning ws init my-app-prod
# Apply environment-specific templates
provisioning tpl apply development-kubernetes my-app-dev
provisioning tpl apply staging-kubernetes my-app-staging
provisioning tpl apply production-kubernetes my-app-prod
# Customize each environment
# Edit: workspace/infra/my-app-dev/...
# Edit: workspace/infra/my-app-staging/...
# Edit: workspace/infra/my-app-prod/...
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "pattern-2-shared-configuration-library" > < a class = "header" href = "#pattern-2-shared-configuration-library" > Pattern 2: Shared Configuration Library< / a > < / h3 >
< p > Create reusable configuration fragments:< / p >
< p > < strong > File: < code > provisioning/workspace/templates/shared/security-policies.ncl< / code > < / strong > < / p >
< pre > < code class = "language-nickel" > let security_policies = {
pod_security = {
enforce = "restricted",
audit = "restricted",
warn = "restricted",
},
network_policies = [
{
name = "deny-all",
pod_selector = {},
policy_types = ["Ingress", "Egress"],
},
{
name = "allow-dns",
pod_selector = {},
egress = [
2026-01-08 09:55:37 +00:00
{
2026-01-12 04:42:18 +00:00
to = [{namespace_selector = {name = "kube-system"}}],
ports = [{protocol = "UDP", port = 53}],
2026-01-08 09:55:37 +00:00
},
2026-01-12 04:42:18 +00:00
],
},
],
} in
security_policies
< / code > < / pre >
< p > Import in your infrastructure:< / p >
< pre > < code class = "language-nickel" > let security_policies = (import "../../../provisioning/workspace/templates/shared/security-policies.ncl") in
let kubernetes_config = {
version = "1.30.0",
image_repo = "k8s.gcr.io",
security = security_policies, # Import shared policies
} in
kubernetes_config
< / code > < / pre >
< h3 id = "pattern-3-dynamic-configuration" > < a class = "header" href = "#pattern-3-dynamic-configuration" > Pattern 3: Dynamic Configuration< / a > < / h3 >
< p > Use Nickel features for dynamic configuration:< / p >
< pre > < code class = "language-nickel" > # Calculate resources based on server count
let server_count = 5 in
let replicas_per_server = 2 in
let total_replicas = server_count * replicas_per_server in
let postgres_config = {
version = "16.1",
max_connections = total_replicas * 50, # Dynamic calculation
shared_buffers = "1024 MB",
} in
postgres_config
< / code > < / pre >
< h3 id = "pattern-4-conditional-configuration" > < a class = "header" href = "#pattern-4-conditional-configuration" > Pattern 4: Conditional Configuration< / a > < / h3 >
< pre > < code class = "language-nickel" > let environment = "production" in # or "development"
let kubernetes_config = {
version = "1.30.0",
control_plane_count = if environment == "production" then 3 else 1,
worker_count = if environment == "production" then 5 else 2,
monitoring = {
enabled = environment == "production",
retention = if environment == "production" then "30d" else "7d",
},
} in
kubernetes_config
< / code > < / pre >
< h2 id = "layer-statistics" > < a class = "header" href = "#layer-statistics" > Layer Statistics< / a > < / h2 >
< pre > < code class = "language-bash" > # Show layer system statistics
2026-01-08 09:55:37 +00:00
provisioning lyr stats
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< p > < strong > Expected Output:< / strong > < / p >
< pre > < code class = "language-plaintext" > 📊 Layer System Statistics:
2026-01-08 09:55:37 +00:00
Infrastructure Layer:
• Projects: 3
• Total files: 15
• Average overrides per project: 5
Workspace Layer:
• Templates: 13
• Most used: production-kubernetes (5 projects)
• Custom templates: 2
Core Layer:
• Taskservs: 15
• Providers: 3
• Clusters: 3
Resolution Performance:
2026-01-12 04:42:18 +00:00
• Average resolution time: 45 ms
2026-01-08 09:55:37 +00:00
• Cache hit rate: 87%
• Total resolutions: 1,250
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "customization-workflow" > < a class = "header" href = "#customization-workflow" > Customization Workflow< / a > < / h2 >
< h3 id = "complete-customization-example" > < a class = "header" href = "#complete-customization-example" > Complete Customization Example< / a > < / h3 >
< pre > < code class = "language-bash" > # 1. Create new infrastructure
2026-01-08 09:55:37 +00:00
provisioning ws init my-custom-app
# 2. Understand layer system
provisioning lyr explain
# 3. Discover templates
provisioning tpl list --type taskservs
# 4. Apply base template
provisioning tpl apply production-kubernetes my-custom-app
# 5. View applied configuration
provisioning lyr show my-custom-app
# 6. Customize (edit files)
2026-01-12 04:42:18 +00:00
provisioning sops workspace/infra/my-custom-app/taskservs/kubernetes.ncl
2026-01-08 09:55:37 +00:00
# 7. Test layer resolution
provisioning lyr test kubernetes my-custom-app
# 8. Validate configuration
provisioning tpl validate my-custom-app
provisioning val config --infra my-custom-app
# 9. Deploy customized infrastructure
provisioning s create --infra my-custom-app --check
provisioning s create --infra my-custom-app
provisioning t create kubernetes --infra my-custom-app
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "best-practices" > < a class = "header" href = "#best-practices" > Best Practices< / a > < / h2 >
< h3 id = "1-use-layers-correctly" > < a class = "header" href = "#1-use-layers-correctly" > 1. Use Layers Correctly< / a > < / h3 >
< ul >
< li > < strong > Core Layer< / strong > : Only modify for system-wide changes< / li >
< li > < strong > Workspace Layer< / strong > : Use for organization-wide templates< / li >
< li > < strong > Infrastructure Layer< / strong > : Use for project-specific customizations< / li >
< / ul >
< h3 id = "2-template-organization" > < a class = "header" href = "#2-template-organization" > 2. Template Organization< / a > < / h3 >
< pre > < code class = "language-plaintext" > provisioning/workspace/templates/
2026-01-08 09:55:37 +00:00
├── shared/ # Shared configuration fragments
2026-01-12 04:42:18 +00:00
│ ├── security-policies.ncl
│ ├── network-policies.ncl
│ └── monitoring.ncl
2026-01-08 09:55:37 +00:00
├── production/ # Production templates
2026-01-12 04:42:18 +00:00
│ ├── kubernetes.ncl
│ ├── postgres.ncl
│ └── redis.ncl
2026-01-08 09:55:37 +00:00
└── development/ # Development templates
2026-01-12 04:42:18 +00:00
├── kubernetes.ncl
└── postgres.ncl
< / code > < / pre >
< h3 id = "3-documentation" > < a class = "header" href = "#3-documentation" > 3. Documentation< / a > < / h3 >
< p > Document your customizations:< / p >
< p > < strong > File: < code > workspace/infra/my-production/README.md< / code > < / strong > < / p >
< pre > < code class = "language-markdown" > # My Production Infrastructure
2026-01-08 09:55:37 +00:00
## Customizations
- Kubernetes: Using production template with 5 control plane nodes
- PostgreSQL: Configured with streaming replication
- Cilium: Native routing mode enabled
## Layer Overrides
2026-01-12 04:42:18 +00:00
- `taskservs/kubernetes.ncl`: Control plane count (3 → 5)
- `taskservs/postgres.ncl`: Replication mode (async → sync)
- `network/cilium.ncl`: Routing mode (tunnel → native)
< / code > < / pre >
< h3 id = "4-version-control" > < a class = "header" href = "#4-version-control" > 4. Version Control< / a > < / h3 >
< p > Keep templates and configurations in version control:< / p >
< pre > < code class = "language-bash" > cd provisioning/workspace/templates/
2026-01-08 09:55:37 +00:00
git add .
git commit -m "Add production Kubernetes template with enhanced security"
cd workspace/infra/my-production/
git add .
git commit -m "Configure production environment for my-production"
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "troubleshooting-customizations" > < a class = "header" href = "#troubleshooting-customizations" > Troubleshooting Customizations< / a > < / h2 >
< h3 id = "issue-configuration-not-applied" > < a class = "header" href = "#issue-configuration-not-applied" > Issue: Configuration not applied< / a > < / h3 >
< pre > < code class = "language-bash" > # Check layer resolution
2026-01-08 09:55:37 +00:00
provisioning lyr show my-production
# Verify file exists
ls -la workspace/infra/my-production/taskservs/
# Test specific resolution
provisioning lyr test kubernetes my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "issue-conflicting-configurations" > < a class = "header" href = "#issue-conflicting-configurations" > Issue: Conflicting configurations< / a > < / h3 >
< pre > < code class = "language-bash" > # Validate configuration
2026-01-08 09:55:37 +00:00
provisioning val config --infra my-production
# Show configuration merge result
provisioning show config kubernetes --infra my-production
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h3 id = "issue-template-not-found" > < a class = "header" href = "#issue-template-not-found" > Issue: Template not found< / a > < / h3 >
< pre > < code class = "language-bash" > # List available templates
2026-01-08 09:55:37 +00:00
provisioning tpl list
# Check template path
ls -la provisioning/workspace/templates/
# Refresh template cache
provisioning tpl refresh
2026-01-12 04:42:18 +00:00
< / code > < / pre >
< h2 id = "next-steps" > < a class = "header" href = "#next-steps" > Next Steps< / a > < / h2 >
< ul >
< li > < strong > < a href = "from-scratch.html" > From Scratch Guide< / a > < / strong > - Deploy new infrastructure< / li >
< li > < strong > < a href = "update-infrastructure.html" > Update Guide< / a > < / strong > - Update existing infrastructure< / li >
< li > < strong > < a href = "../development/workflow.html" > Workflow Guide< / a > < / strong > - Automate with workflows< / li >
< li > < strong > < a href = "../development/nickel-module-guide.html" > Nickel Guide< / a > < / strong > - Learn Nickel configuration language< / li >
< / ul >
< h2 id = "quick-reference" > < a class = "header" href = "#quick-reference" > Quick Reference< / a > < / h2 >
< pre > < code class = "language-bash" > # Layer system
2026-01-08 09:55:37 +00:00
provisioning lyr explain # Explain layers
provisioning lyr show < project> # Show layer resolution
provisioning lyr test < module> < project> # Test resolution
provisioning lyr stats # Layer statistics
# Templates
provisioning tpl list # List all templates
provisioning tpl list --type < type> # Filter by type
provisioning tpl show < template> # Show template details
provisioning tpl apply < template> < project> # Apply template
provisioning tpl validate < project> # Validate template usage
2025-12-11 21:50:42 +00:00
< / code > < / pre >
2026-01-12 04:42:18 +00:00
< hr / >
< p > < em > This guide is part of the provisioning project documentation. Last updated: 2025-09-30< / em > < / p >
2025-12-11 21:50:42 +00:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "../guides/update-infrastructure.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-12 04:42:18 +00:00
< a rel = "next prefetch" href = "../guides/infrastructure-setup.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< 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 = "../guides/update-infrastructure.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
2026-01-12 04:42:18 +00:00
< a rel = "next prefetch" href = "../guides/infrastructure-setup.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
2025-12-11 21:50:42 +00:00
< 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 >
