provisioning/config/templates/WORKSPACE_CONFIG_TEMPLATES.md

Workspace Configuration Templates

This directory contains templates for creating new workspace configurations using the KCL SST (Single Source of Truth) pattern.

Files

Workspace Root

• kcl.mod.template → {workspace}/kcl.mod
  • Top-level KCL package definition
  • Declares dependency on .provisioning package

.provisioning/ Directory

• workspace-config-schema.k.template → {workspace}/.provisioning/workspace_config.k

  • Schema definitions (SST - Single Source of Truth)
  • Type-safe WorkspaceConfig schema
  • Validation rules
  • Do not modify per-workspace - update the template to change all workspaces

• workspace-config-defaults.k.template → {workspace}/.provisioning/workspace_config_defaults.k

  • Default values for all configuration sections
  • Base configuration that all workspaces inherit
  • Do not modify per-workspace - update the template to change all workspaces

• .provisioning-kcl.mod.template → {workspace}/.provisioning/kcl.mod

  • KCL package definition for .provisioning package
  • Package name is "provisioning"

config/ Directory

• config-kcl.mod.template → {workspace}/config/kcl.mod

  • KCL package definition for workspace config
  • Declares dependency on provisioning package (from .provisioning/)

• workspace-config.k.template → {workspace}/config/provisioning.k

  • Workspace-specific configuration overrides
  • Imports defaults from .provisioning/workspace_config_defaults.k
  • Only contains values that differ from defaults
  • This is the only file that changes per-workspace

SST Pattern Architecture

.provisioning/
├── workspace_config.k              (Schema definitions)
├── workspace_config_defaults.k     (Default values - inherited by all)
└── kcl.mod                         (Package definition)

config/
├── provisioning.k                  (Workspace overrides - ONLY THIS CHANGES)
└── kcl.mod                         (Config package definition)

kcl.mod                             (Workspace package definition)

How New Workspaces Are Created

1. Generate from Templates

When creating a new workspace, the provisioning system:

1. Creates {workspace}/kcl.mod from kcl.mod.template

   • Replace {{WORKSPACE_NAME}} with actual workspace name

2. Creates .provisioning/ directory with:

   • workspace_config.k from workspace-config-schema.k.template
   • workspace_config_defaults.k from workspace-config-defaults.k.template
   • kcl.mod from .provisioning-kcl.mod.template

3. Creates config/ directory with:

   • kcl.mod from config-kcl.mod.template
   • provisioning.k from workspace-config.k.template
     • Replace {{WORKSPACE_NAME}} with actual workspace name
     • Replace {{WORKSPACE_PATH}} with actual path
     • Replace {{PROVISIONING_PATH}} with actual provisioning path
     • Replace {{CREATED_TIMESTAMP}} with ISO 8601 timestamp

2. Verification

After generation, verify with:

cd {workspace}/config
kcl run provisioning.k

Output should be valid YAML with all configuration sections populated.

Maintenance

Updating All Workspaces

To change defaults or schema for all workspaces:

1. Update schema: Edit workspace-config-schema.k.template
2. Update defaults: Edit workspace-config-defaults.k.template
3. Regenerate all workspaces: Run provisioning sync command
   • This copies the templates to each workspace's .provisioning/

Existing workspace overrides in config/provisioning.k are not affected.

Adding New Configuration Sections

1. Add schema to workspace-config-schema.k.template
2. Add defaults to workspace-config-defaults.k.template
3. New workspaces automatically inherit the new section
4. Existing workspaces get the new defaults (no action needed)

Template Variables

• {{WORKSPACE_NAME}} - Name of the workspace (e.g., "librecloud")
• {{WORKSPACE_PATH}} - Absolute path to workspace
• {{PROVISIONING_PATH}} - Absolute path to provisioning system
• {{CREATED_TIMESTAMP}} - ISO 8601 timestamp of creation
• {{INFRA_NAME}} - Infrastructure name (e.g., "default")

Example: Creating a New Workspace

# Step 1: Create workspace structure
mkdir -p my-workspace/.provisioning my-workspace/config

# Step 2: Generate from templates
provisioning workspace init my-workspace \
  --from-templates \
  --workspace-path /path/to/my-workspace \
  --provisioning-path /path/to/provisioning

# Step 3: Verify configuration
cd my-workspace/config
kcl run provisioning.k

# Step 4: Make workspace-specific overrides if needed
# Edit config/provisioning.k to override any defaults

Template Extension Convention: .template

These workspace initialization templates use the .template extension for specific reasons:

Why .template (Not .j2)?

• Simple substitution only: Just {{variable}} replacement, no complex logic
• No plugin dependency: Works without nu_plugin_tera, more portable
• Semantic clarity: Extension signals "initialization" vs "runtime rendering"
• Appropriate complexity: Simple initialization doesn't need Jinja2 power

Note: Runtime configuration templates use .j2 (Jinja2). See README.md for complete conventions.

Benefits of SST Pattern

✅ DRY - Schema and defaults defined once ✅ Maintainable - Update templates to change all workspaces ✅ Type-safe - Full validation against schema ✅ Clear intent - See exactly what's customized per-workspace ✅ Inheritance - New workspaces automatically get new defaults ✅ Mergeable - KCL | operator for clean overrides