916 lines
38 KiB
HTML
916 lines
38 KiB
HTML
<!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 -->
|
|
|
|
<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/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>
|
|
<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>
|
|
<h2 id="overview"><a class="header" href="#overview">Overview</a></h2>
|
|
<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 │
|
|
└─────────────────────────────────────┘
|
|
</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
|
|
provisioning lyr explain
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">📚 LAYER SYSTEM EXPLAINED
|
|
|
|
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.
|
|
</code></pre>
|
|
<pre><code class="language-bash"># Show layer resolution for your project
|
|
provisioning lyr show my-production
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">📊 Layer Resolution for my-production:
|
|
|
|
LAYER PRIORITY SOURCE FILES
|
|
Infrastructure 300 workspace/infra/my-production/ 4 files
|
|
• servers.ncl (overrides)
|
|
• taskservs.ncl (overrides)
|
|
• clusters.ncl (custom)
|
|
• providers.ncl (overrides)
|
|
|
|
Workspace 200 provisioning/workspace/templates/ 2 files
|
|
• production.ncl (used)
|
|
• kubernetes.ncl (used)
|
|
|
|
Core 100 provisioning/extensions/ 15 files
|
|
• taskservs/* (base configs)
|
|
• providers/* (default settings)
|
|
• clusters/* (templates)
|
|
|
|
Resolution Order: Infrastructure → Workspace → Core
|
|
Status: ✅ All layers resolved successfully
|
|
</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
|
|
provisioning lyr test kubernetes my-production
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">🔍 Layer Resolution Test: kubernetes → my-production
|
|
|
|
Resolving kubernetes configuration...
|
|
|
|
🔴 Infrastructure Layer (300):
|
|
✅ Found: workspace/infra/my-production/taskservs/kubernetes.ncl
|
|
Provides:
|
|
• version = "1.30.0" (overrides)
|
|
• control_plane_servers = ["web-01"] (overrides)
|
|
• worker_servers = ["web-02"] (overrides)
|
|
|
|
🟢 Workspace Layer (200):
|
|
✅ Found: provisioning/workspace/templates/production-kubernetes.ncl
|
|
Provides:
|
|
• security_policies (inherited)
|
|
• network_policies (inherited)
|
|
• resource_quotas (inherited)
|
|
|
|
🔵 Core Layer (100):
|
|
✅ Found: provisioning/extensions/taskservs/kubernetes/main.ncl
|
|
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
|
|
</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
|
|
provisioning tpl list
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">📋 Available Templates:
|
|
|
|
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
|
|
</code></pre>
|
|
<pre><code class="language-bash"># List templates by type
|
|
provisioning tpl list --type taskservs
|
|
provisioning tpl list --type providers
|
|
provisioning tpl list --type clusters
|
|
</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
|
|
provisioning tpl show production-kubernetes
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">📄 Template: production-kubernetes
|
|
|
|
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
|
|
• 4 GB RAM per server
|
|
• Network plugin (Cilium recommended)
|
|
|
|
Location: provisioning/workspace/templates/production-kubernetes.ncl
|
|
|
|
Example Usage:
|
|
provisioning tpl apply production-kubernetes my-production
|
|
</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
|
|
provisioning tpl apply production-kubernetes my-production
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">🚀 Applying template: production-kubernetes → my-production
|
|
|
|
Checking compatibility... ⏳
|
|
✅ Infrastructure compatible with template
|
|
|
|
Merging configuration... ⏳
|
|
✅ Configuration merged
|
|
|
|
Files created/updated:
|
|
• 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)
|
|
|
|
🎉 Template applied successfully!
|
|
|
|
Next steps:
|
|
1. Review generated configuration
|
|
2. Adjust as needed
|
|
3. Deploy: provisioning t create kubernetes --infra my-production
|
|
</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
|
|
provisioning tpl validate my-production
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">✅ Template Validation: my-production
|
|
|
|
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
|
|
</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
|
|
mkdir -p provisioning/workspace/templates/my-custom-template
|
|
</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]
|
|
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"]
|
|
</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)
|
|
provisioning tpl list
|
|
|
|
# Show your template
|
|
provisioning tpl show my-custom-template
|
|
|
|
# Apply to test infrastructure
|
|
provisioning tpl apply my-custom-template my-test
|
|
</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
|
|
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/...
|
|
</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 = [
|
|
{
|
|
to = [{namespace_selector = {name = "kube-system"}}],
|
|
ports = [{protocol = "UDP", port = 53}],
|
|
},
|
|
],
|
|
},
|
|
],
|
|
} 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
|
|
provisioning lyr stats
|
|
</code></pre>
|
|
<p><strong>Expected Output:</strong></p>
|
|
<pre><code class="language-plaintext">📊 Layer System Statistics:
|
|
|
|
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:
|
|
• Average resolution time: 45 ms
|
|
• Cache hit rate: 87%
|
|
• Total resolutions: 1,250
|
|
</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
|
|
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)
|
|
provisioning sops workspace/infra/my-custom-app/taskservs/kubernetes.ncl
|
|
|
|
# 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
|
|
</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/
|
|
├── shared/ # Shared configuration fragments
|
|
│ ├── security-policies.ncl
|
|
│ ├── network-policies.ncl
|
|
│ └── monitoring.ncl
|
|
├── production/ # Production templates
|
|
│ ├── kubernetes.ncl
|
|
│ ├── postgres.ncl
|
|
│ └── redis.ncl
|
|
└── development/ # Development templates
|
|
├── 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
|
|
|
|
## Customizations
|
|
|
|
- Kubernetes: Using production template with 5 control plane nodes
|
|
- PostgreSQL: Configured with streaming replication
|
|
- Cilium: Native routing mode enabled
|
|
|
|
## Layer Overrides
|
|
|
|
- `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/
|
|
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"
|
|
</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
|
|
provisioning lyr show my-production
|
|
|
|
# Verify file exists
|
|
ls -la workspace/infra/my-production/taskservs/
|
|
|
|
# Test specific resolution
|
|
provisioning lyr test kubernetes my-production
|
|
</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
|
|
provisioning val config --infra my-production
|
|
|
|
# Show configuration merge result
|
|
provisioning show config kubernetes --infra my-production
|
|
</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
|
|
provisioning tpl list
|
|
|
|
# Check template path
|
|
ls -la provisioning/workspace/templates/
|
|
|
|
# Refresh template cache
|
|
provisioning tpl refresh
|
|
</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
|
|
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
|
|
</code></pre>
|
|
<hr />
|
|
<p><em>This guide is part of the provisioning project documentation. Last updated: 2025-09-30</em></p>
|
|
|
|
</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>
|
|
|
|
<a rel="next prefetch" href="../guides/infrastructure-setup.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="../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>
|
|
|
|
<a rel="next prefetch" href="../guides/infrastructure-setup.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>
|