provisioning/config/templates

Configuration Templates

Purpose: Template files for generating workspace configurations

Important

These files are TEMPLATES ONLY. They are NEVER loaded at runtime.

The provisioning system generates workspace configurations from these templates during workspace initialization. Once generated, the workspace uses its own config/provisioning.yaml and related configs.

Available Templates

1. workspace-provisioning.yaml.template

Main workspace configuration template. Generates: {workspace}/config/provisioning.yaml

Variables:

• {{workspace.name}} - Workspace name
• {{workspace.path}} - Absolute workspace path
• {{now.iso}} - Timestamp

Sections:

• workspace - Workspace metadata
• paths - All system paths
• core - Core settings
• debug - Debug configuration
• output - Output preferences
• providers - Provider settings
• platform - Platform services
• secrets - Secret management
• kms - Key management
• sops - SOPS configuration
• taskservs - Task service paths
• clusters - Cluster paths
• cache - Cache settings

2. provider-aws.toml.template

AWS provider configuration template. Generates: {workspace}/config/providers/aws.toml

Variables:

• {{workspace.name}} - Workspace name
• {{workspace.path}} - Absolute workspace path
• {{now.iso}} - Timestamp

Sections:

• provider - Provider metadata
• provider.auth - AWS authentication
• provider.paths - Provider-specific paths
• provider.api - API settings

3. provider-local.toml.template

Local provider configuration template. Generates: {workspace}/config/providers/local.toml

Variables:

• {{workspace.name}} - Workspace name
• {{workspace.path}} - Absolute workspace path
• {{now.iso}} - Timestamp

Sections:

• provider - Provider metadata
• provider.auth - Local auth (minimal)
• provider.paths - Provider-specific paths

4. provider-upcloud.toml.template

UpCloud provider configuration template. Generates: {workspace}/config/providers/upcloud.toml

Variables:

• {{workspace.name}} - Workspace name
• {{workspace.path}} - Absolute workspace path
• {{now.iso}} - Timestamp

Sections:

• provider - Provider metadata
• provider.auth - UpCloud authentication
• provider.paths - Provider-specific paths
• provider.api - API settings (UpCloud API URL)

5. kms.toml.template

Key Management Service configuration template. Generates: {workspace}/config/kms.toml

Variables:

• {{workspace.name}} - Workspace name
• {{workspace.path}} - Absolute workspace path
• {{now.iso}} - Timestamp

Sections:

• kms - KMS mode and settings
• kms.local - Local KMS (Age)
• kms.remote - Remote KMS server

6. user-context.yaml.template

User context configuration template. Generates: ~/Library/Application Support/provisioning/ws_{name}.yaml

Variables:

• {{workspace.name}} - Workspace name
• {{workspace.path}} - Absolute workspace path
• {{now.iso}} - Timestamp

Sections:

• workspace - Workspace reference
• debug - User debug overrides
• output - User output preferences
• providers - User provider preferences
• paths - User path overrides

Template Variable Syntax

Templates use {{variable}} syntax for interpolation:

# Example
workspace:
  name: "{{workspace.name}}"
  path: "{{workspace.path}}"
  created: "{{now.iso}}"

Supported Variables

Core Variables

• {{workspace.name}} - Workspace name (string)
• {{workspace.path}} - Absolute workspace path (string)

Timestamp Variables

• {{now.iso}} - ISO 8601 timestamp (YYYY-MM-DDTHH:MM:SSZ)
• {{now.date}} - Date only (YYYY-MM-DD)
• {{now.timestamp}} - Unix timestamp

Environment Variables (safe list)

• {{env.HOME}} - User home directory
• {{env.USER}} - Current user
• {{env.HOSTNAME}} - System hostname

Usage

Generate Workspace from Template

use provisioning/core/nulib/lib_provisioning/workspace/init.nu *

# Initialize workspace with AWS and Local providers
workspace-init "my-workspace" "/path/to/workspace" \
  --providers ["aws" "local"] \
  --activate

What Happens

1. Templates are read from this directory
2. Variables are interpolated with actual values
3. Generated configs are saved to workspace
4. User context (if --activate) is created

Generated Structure

/path/to/workspace/
├── config/
│   ├── provisioning.yaml      # From workspace-provisioning.yaml.template
│   ├── kms.toml               # From kms.toml.template
│   └── providers/
│       ├── aws.toml           # From provider-aws.toml.template
│       └── local.toml         # From provider-local.toml.template

~/Library/Application Support/provisioning/
└── ws_my-workspace.yaml        # From user-context.yaml.template

Adding New Templates

1. Create Template File

# Example: New provider template
touch provider-gcp.toml.template

2. Add Template Content

# GCP Provider Configuration for Workspace: {{workspace.name}}
# Generated: {{now.iso}}

[provider]
name = "gcp"
enabled = true
workspace = "{{workspace.name}}"

[provider.auth]
project = "default"
region = "us-central1"

[provider.paths]
base = "{{workspace.path}}/.providers/gcp"
cache = "{{workspace.path}}/.providers/gcp/cache"

3. Update Workspace Init

Add GCP template handling to workspace/init.nu:

def generate-provider-config [
  workspace_path: string
  workspace_name: string
  provider_name: string
] {
  let template_path = $"/path/to/templates/provider-($provider_name).toml.template"

  if not ($template_path | path exists) {
    print $"⚠️  No template for provider '($provider_name)'"
    return
  }

  # Generate config...
}

Template Best Practices

1. Always Include Metadata

# Configuration for Workspace: {{workspace.name}}
# Generated: {{now.iso}}
# DO NOT EDIT - Regenerate from template

2. Use Absolute Paths

paths:
  base: "{{workspace.path}}"           # ✅ Absolute
  cache: "{{workspace.path}}/.cache"   # ✅ Absolute

  # NOT relative:
  # cache: ".cache"                    # ❌ Relative

3. Provide Sensible Defaults

debug:
  enabled: false          # Safe default
  log_level: "info"       # Reasonable default

providers:
  default: "local"        # Safe default

4. Document Sections

# Debug settings (can be overridden by user context)
debug:
  enabled: false
  log_level: "info"

5. Group Related Settings

[kms]
mode = "local"

[kms.local]
provider = "age"
key_path = "{{workspace.path}}/.kms/keys/age.txt"

[kms.remote]
server = ""

Validation

Templates should be validated before use:

1. Syntax Valid: YAML/TOML parseable
2. Variables Complete: All {{variables}} have values
3. Paths Absolute: All paths use {{workspace.path}}
4. Sensible Defaults: Safe, secure defaults

Troubleshooting

Template Not Found

⚠️  Warning: No template found for provider 'xyz'

Solution: Create template or check provider name spelling.

Variable Not Interpolated

Config shows {{workspace.name}} instead of actual name.

Solution: Check variable exists in interpolation list, update workspace/init.nu.

Invalid YAML/TOML

Generated config fails to parse.

Solution: Validate template syntax, ensure proper escaping.

Related Files

• Workspace Init: provisioning/core/nulib/lib_provisioning/workspace/init.nu
• Config Loader: provisioning/core/nulib/lib_provisioning/config/loader.nu
• Documentation: docs/configuration/workspace-config-architecture.md

Summary

• Templates are source files only, never loaded at runtime
• Used to generate workspace configs during initialization
• Support variable interpolation with {{variable}} syntax
• Each template creates specific config file in workspace
• Modify templates to change default workspace structure