provisioning/docs/src/infrastructure/configuration-system.md

Configuration System

The Provisioning platform uses a hierarchical configuration system with Nickel as the source of truth for infrastructure definitions and TOML/YAML for application settings.

Configuration Hierarchy

Configuration is loaded in order of precedence (highest to lowest):

1. Runtime Arguments    - CLI flags (--config, --workspace, etc.)
2. Environment Variables - PROVISIONING_* environment variables
3. User Configuration   - ~/.config/provisioning/user_config.yaml
4. Infrastructure Config - Nickel schemas in workspace/provisioning
5. System Defaults      - provisioning/config/config.defaults.toml

Later sources override earlier ones, allowing flexible configuration management across environments.

Configuration Files

System Defaults

Located at provisioning/config/config.defaults.toml:

[general]
log_level = "info"
workspace_root = "./workspaces"

[providers]
default_provider = "local"

[orchestrator]
max_parallel_tasks = 4
checkpoint_enabled = true

User Configuration

Located at ~/.config/provisioning/user_config.yaml:

general:
  preferred_editor: nvim
  default_workspace: production

providers:
  upcloud:
    default_zone: fi-hel1
  aws:
    default_region: eu-west-1

Workspace Configuration

Nickel-based infrastructure configuration in workspace directories:

workspace/
├── config/
│   ├── main.ncl           # Workspace configuration
│   ├── providers.ncl      # Provider definitions
│   └── variables.ncl      # Workspace variables
├── infra/
│   └── servers.ncl        # Infrastructure definitions
└── .workspace/
    └── metadata.toml      # Workspace metadata

Environment Variables

All configuration can be overridden via environment variables:

export PROVISIONING_LOG_LEVEL=debug
export PROVISIONING_WORKSPACE=production
export PROVISIONING_PROVIDER=upcloud
export PROVISIONING_DRY_RUN=true

Variable naming: PROVISIONING_<SECTION>_<KEY> (uppercase with underscores).

Configuration Accessors

The platform provides 476+ configuration accessors for programmatic access:

# Get configuration value
provisioning config get general.log_level

# Set configuration value (workspace-scoped)
provisioning config set providers.default_provider upcloud

# List all configuration
provisioning config list

# Validate configuration
provisioning config validate

Profiles

Configuration supports profiles for different environments:

[profiles.development]
log_level = "debug"
dry_run = true

[profiles.production]
log_level = "warn"
dry_run = false
checkpoint_enabled = true

Activate profile:

provisioning --profile production deploy

Inheritance and Overrides

Workspace configurations inherit from system defaults:

# workspace/config/main.ncl
let parent = import "../../provisioning/schemas/defaults.ncl" in
parent & {
  # Override specific values
  general.log_level = "debug",
  providers.default_provider = "aws",
}

Secrets Management

Sensitive configuration is encrypted using SOPS/Age:

# Encrypt configuration
sops --encrypt --age <public-key> secrets.yaml > secrets.enc.yaml

# Decrypt and use
provisioning deploy --secrets secrets.enc.yaml

Integration with SecretumVault for enterprise secrets management (see Secrets Management).

Configuration Validation

All Nickel-based configuration is validated before use:

# Validate workspace configuration
provisioning config validate

# Check schema compliance
nickel export --format json workspace/config/main.ncl

Type-safety is mandatory - invalid configuration is rejected at load time.

Best Practices

1. Use Nickel for infrastructure - Type-safe, validated infrastructure definitions
2. Use TOML for application settings - Simple key-value configuration
3. Encrypt secrets - Never commit unencrypted credentials
4. Document overrides - Comment why values differ from defaults
5. Validate before deploy - Always run config validate before deployment
6. Version control - Track configuration changes in Git
7. Profile separation - Isolate development/staging/production configs

Troubleshooting

Configuration Not Loading

Check precedence order:

# Show effective configuration
provisioning config show --debug

# Trace configuration loading
PROVISIONING_LOG_LEVEL=trace provisioning config list

Schema Validation Failures

# Check Nickel syntax
nickel typecheck workspace/config/main.ncl

# Export and inspect
nickel export workspace/config/main.ncl

Environment Variable Issues

# List all PROVISIONING_* variables
env | grep PROVISIONING_

# Clear all provisioning env vars
unset $(env | grep PROVISIONING_ | cut -d= -f1 | xargs)

References

• Nickel Guide - Infrastructure configuration
• Schemas Reference - Schema structure
• Secrets Management - SecretumVault integration