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 -->
< 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 >
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 │
└─────────────────────────────────────┘
```plaintext
2025-12-11 21:50:42 +00:00
2026-01-08 09:55:37 +00:00
**Resolution Order**: Infrastructure (300) → Workspace (200) → Core (100)
2025-12-11 21:50:42 +00:00
2026-01-08 09:55:37 +00:00
Higher numbers override lower numbers.
### View Layer Resolution
```bash
# Explain layer concept
provisioning lyr explain
```plaintext
**Expected Output:**
```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.
```plaintext
```bash
# Show layer resolution for your project
provisioning lyr show my-production
```plaintext
**Expected Output:**
```plaintext
📊 Layer Resolution for my-production:
LAYER PRIORITY SOURCE FILES
Infrastructure 300 workspace/infra/my-production/ 4 files
• servers.k (overrides)
• taskservs.k (overrides)
• clusters.k (custom)
• providers.k (overrides)
Workspace 200 provisioning/workspace/templates/ 2 files
• production.k (used)
• kubernetes.k (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
```plaintext
### Test Layer Resolution
```bash
# Test how a specific module resolves
provisioning lyr test kubernetes my-production
```plaintext
**Expected Output:**
```plaintext
🔍 Layer Resolution Test: kubernetes → my-production
Resolving kubernetes configuration...
🔴 Infrastructure Layer (300):
✅ Found: workspace/infra/my-production/taskservs/kubernetes.k
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.k
Provides:
• security_policies (inherited)
• network_policies (inherited)
• resource_quotas (inherited)
🔵 Core Layer (100):
✅ Found: provisioning/extensions/taskservs/kubernetes/config.k
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
```plaintext
## Using Templates
### List Available Templates
```bash
# List all templates
provisioning tpl list
```plaintext
**Expected Output:**
```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
```plaintext
```bash
# List templates by type
provisioning tpl list --type taskservs
provisioning tpl list --type providers
provisioning tpl list --type clusters
```plaintext
### View Template Details
```bash
# Show template details
provisioning tpl show production-kubernetes
```plaintext
**Expected Output:**
```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
• 4GB RAM per server
• Network plugin (Cilium recommended)
Location: provisioning/workspace/templates/production-kubernetes.k
Example Usage:
provisioning tpl apply production-kubernetes my-production
```plaintext
### Apply Template
```bash
# Apply template to your infrastructure
provisioning tpl apply production-kubernetes my-production
```plaintext
**Expected Output:**
```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.k (updated)
• workspace/infra/my-production/policies/security.k (created)
• workspace/infra/my-production/policies/network.k (created)
• workspace/infra/my-production/monitoring/prometheus.k (created)
🎉 Template applied successfully!
Next steps:
1. Review generated configuration
2. Adjust as needed
3. Deploy: provisioning t create kubernetes --infra my-production
```plaintext
### Validate Template Usage
```bash
# Validate template was applied correctly
provisioning tpl validate my-production
```plaintext
**Expected Output:**
```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
```plaintext
## Creating Custom Templates
### Step 1: Create Template Structure
```bash
# Create custom template directory
mkdir -p provisioning/workspace/templates/my-custom-template
```plaintext
### Step 2: Write Template Configuration
**File: `provisioning/workspace/templates/my-custom-template/config.k`**
```kcl
# Custom Kubernetes template with specific settings
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
}
}
```plaintext
### Step 3: Create Template Metadata
**File: `provisioning/workspace/templates/my-custom-template/metadata.toml`**
```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"]
```plaintext
### Step 4: Test Custom Template
```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
```plaintext
## Configuration Inheritance Examples
### Example 1: Override Single Value
**Core Layer** (`provisioning/extensions/taskservs/postgres/config.k`):
```kcl
postgres_config = {
version = "15.5"
port = 5432
max_connections = 100
}
```plaintext
**Infrastructure Layer** (`workspace/infra/my-production/taskservs/postgres.k`):
```kcl
postgres_config = {
max_connections = 500 # Override only max_connections
}
```plaintext
**Result** (after layer resolution):
```kcl
postgres_config = {
version = "15.5" # From Core
port = 5432 # From Core
max_connections = 500 # From Infrastructure (overridden)
}
```plaintext
### Example 2: Add Custom Configuration
**Workspace Layer** (`provisioning/workspace/templates/production-postgres.k`):
```kcl
postgres_config = {
replication = {
enabled = True
replicas = 2
sync_mode = "async"
}
}
```plaintext
**Infrastructure Layer** (`workspace/infra/my-production/taskservs/postgres.k`):
```kcl
postgres_config = {
replication = {
sync_mode = "sync" # Override sync mode
}
custom_extensions = ["pgvector", "timescaledb"] # Add custom config
}
```plaintext
**Result**:
```kcl
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)
}
```plaintext
### Example 3: Environment-Specific Configuration
**Workspace Layer** (`provisioning/workspace/templates/base-kubernetes.k`):
```kcl
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"}
}
}
```plaintext
**Development Infrastructure** (`workspace/infra/my-dev/taskservs/kubernetes.k`):
```kcl
kubernetes_config = {
control_plane_count = 1 # Smaller for dev
worker_count = 2
resources = {
control_plane = {cpu = "2", memory = "4Gi"}
worker = {cpu = "2", memory = "4Gi"}
}
}
```plaintext
**Production Infrastructure** (`workspace/infra/my-prod/taskservs/kubernetes.k`):
```kcl
kubernetes_config = {
control_plane_count = 5 # Larger for prod
worker_count = 10
resources = {
control_plane = {cpu = "8", memory = "16Gi"}
worker = {cpu = "16", memory = "32Gi"}
}
}
```plaintext
## Advanced Customization Patterns
### Pattern 1: Multi-Environment Setup
Create different configurations for each environment:
```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/...
```plaintext
### Pattern 2: Shared Configuration Library
Create reusable configuration fragments:
**File: `provisioning/workspace/templates/shared/security-policies.k`**
```kcl
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}]
}
]
}
2025-12-11 21:50:42 +00:00
]
}
2026-01-08 09:55:37 +00:00
```plaintext
Import in your infrastructure:
```kcl
import "../../../provisioning/workspace/templates/shared/security-policies.k"
kubernetes_config = {
version = "1.30.0"
# ... other config
security = security_policies # Import shared policies
}
```plaintext
### Pattern 3: Dynamic Configuration
Use KCL features for dynamic configuration:
```kcl
# Calculate resources based on server count
server_count = 5
replicas_per_server = 2
total_replicas = server_count * replicas_per_server
postgres_config = {
version = "16.1"
max_connections = total_replicas * 50 # Dynamic calculation
shared_buffers = "${total_replicas * 128}MB"
}
```plaintext
### Pattern 4: Conditional Configuration
```kcl
environment = "production" # or "development"
kubernetes_config = {
version = "1.30.0"
control_plane_count = if environment == "production" { 3 } else { 1 }
worker_count = if environment == "production" { 5 } else { 2 }
monitoring = {
enabled = environment == "production"
retention = if environment == "production" { "30d" } else { "7d" }
2025-12-11 21:50:42 +00:00
}
}
2026-01-08 09:55:37 +00:00
```plaintext
## Layer Statistics
```bash
# Show layer system statistics
provisioning lyr stats
```plaintext
**Expected Output:**
```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: 45ms
• Cache hit rate: 87%
• Total resolutions: 1,250
```plaintext
## Customization Workflow
### Complete Customization Example
```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.k
# 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
```plaintext
## Best Practices
### 1. Use Layers Correctly
- **Core Layer**: Only modify for system-wide changes
- **Workspace Layer**: Use for organization-wide templates
- **Infrastructure Layer**: Use for project-specific customizations
### 2. Template Organization
```plaintext
provisioning/workspace/templates/
├── shared/ # Shared configuration fragments
│ ├── security-policies.k
│ ├── network-policies.k
│ └── monitoring.k
├── production/ # Production templates
│ ├── kubernetes.k
│ ├── postgres.k
│ └── redis.k
└── development/ # Development templates
├── kubernetes.k
└── postgres.k
```plaintext
### 3. Documentation
Document your customizations:
**File: `workspace/infra/my-production/README.md`**
```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.k`: Control plane count (3 → 5)
- `taskservs/postgres.k`: Replication mode (async → sync)
- `network/cilium.k`: Routing mode (tunnel → native)
```plaintext
### 4. Version Control
Keep templates and configurations in version control:
```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"
```plaintext
## Troubleshooting Customizations
### Issue: Configuration not applied
```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
```plaintext
### Issue: Conflicting configurations
```bash
# Validate configuration
provisioning val config --infra my-production
# Show configuration merge result
provisioning show config kubernetes --infra my-production
```plaintext
### Issue: Template not found
```bash
# List available templates
provisioning tpl list
# Check template path
ls -la provisioning/workspace/templates/
# Refresh template cache
provisioning tpl refresh
```plaintext
## Next Steps
- **[From Scratch Guide](from-scratch.md)** - Deploy new infrastructure
- **[Update Guide](update-infrastructure.md)** - Update existing infrastructure
- **[Workflow Guide](../development/workflow.md)** - Automate with workflows
- **[KCL Guide](../development/KCL_MODULE_GUIDE.md)** - Learn KCL configuration language
## Quick Reference
```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
```plaintext
---
*This guide is part of the provisioning project documentation. Last updated: 2025-09-30*
2025-12-11 21:50:42 +00:00
< / code > < / pre >
< / 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-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../guides/extension-development-quickstart.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-08 09:55:37 +00:00
< a rel = "next prefetch" href = "../guides/extension-development-quickstart.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 >
