2026-01-14 03:09:18 +00:00
|
|
|
# Configuration Management\n\nThis document provides comprehensive guidance on provisioning's configuration architecture, environment-specific configurations, validation, error\nhandling, and migration strategies.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Configuration Architecture](#configuration-architecture)\n3. [Configuration Files](#configuration-files)\n4. [Environment-Specific Configuration](#environment-specific-configuration)\n5. [User Overrides and Customization](#user-overrides-and-customization)\n6. [Validation and Error Handling](#validation-and-error-handling)\n7. [Interpolation and Dynamic Values](#interpolation-and-dynamic-values)\n8. [Migration Strategies](#migration-strategies)\n9. [Troubleshooting](#troubleshooting)\n\n## Overview\n\nProvisioning implements a sophisticated configuration management system that has migrated from environment variable-based configuration to a\nhierarchical TOML configuration system with comprehensive validation and interpolation support.\n\n**Key Features**:\n\n- **Hierarchical Configuration**: Multi-layer configuration with clear precedence\n- **Environment-Specific**: Dedicated configurations for dev, test, and production\n- **Dynamic Interpolation**: Template-based value resolution\n- **Type Safety**: Comprehensive validation and error handling\n- **Migration Support**: Backward compatibility with existing ENV variables\n- **Workspace Integration**: Seamless integration with development workspaces\n\n**Migration Status**: ✅ **Complete** (2025-09-23)\n\n- **65+ files migrated** across entire codebase\n- **200+ ENV variables replaced** with 476 config accessors\n- **16 token-efficient agents** used for systematic migration\n- **92% token efficiency** achieved vs monolithic approach\n\n## Configuration Architecture\n\n### Hierarchical Loading Order\n\nThe configuration system implements a clear precedence hierarchy (lowest to highest precedence):\n\n```\nConfiguration Hierarchy (Low → High Precedence)\n┌─────────────────────────────────────────────────┐\n│ 1. config.defaults.toml │ ← System defaults\n│ (System-wide default values) │\n├─────────────────────────────────────────────────┤\n│ 2. ~/.config/provisioning/config.toml │ ← User configuration\n│ (User-specific preferences) │\n├─────────────────────────────────────────────────┤\n│ 3. ./provisioning.toml │ ← Project configuration\n│ (Project-specific settings) │\n├─────────────────────────────────────────────────┤\n│ 4. ./.provisioning.toml │ ← Infrastructure config\n│ (Infrastructure-specific settings) │\n├─────────────────────────────────────────────────┤\n│ 5. Environment-specific configs │ ← Environment overrides\n│ (config.{dev,test,prod}.toml) │\n├─────────────────────────────────────────────────┤\n│ 6. Runtime environment variables │ ← Runtime overrides\n│ (PROVISIONING_* variables) │\n└─────────────────────────────────────────────────┘\n```\n\n### Configuration Access Patterns\n\n**Configuration Accessor Functions**:\n\n```\n# Core configuration access\nuse core/nulib/lib_provisioning/config/accessor.nu\n\n# Get conf
|
