[INFRA] Standardize variable management (issue #15)

.github/workflows/validate-config.yml

@@ -0,0 +1,72 @@
+# =============================================================================
+# validate-config.yml — Validate config files against schema
+# =============================================================================
+# Triggered on PRs and pushes that touch config/ or this workflow.
+# Validates YAML syntax and JSON Schema compliance.
+# =============================================================================
+
+name: Validate Configuration
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'config/**'
+      - '.github/workflows/validate-config.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'config/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install pyyaml jsonschema
+
+      - name: Validate infrastructure.yml against schema
+        run: |
+          python3 -c "
+          import yaml, json, sys
+          from jsonschema import validate, ValidationError
+
+          with open('config/infrastructure.yml') as f:
+              data = yaml.safe_load(f)
+
+          with open('config/schema/variables.schema.json') as f:
+              schema = json.load(f)
+
+          try:
+              validate(instance=data, schema=schema)
+              print('✅ config/infrastructure.yml passes schema validation')
+          except ValidationError as e:
+              print(f'❌ Schema validation failed: {e.message}')
+              print(f'   Path: {\" > \".join(str(p) for p in e.absolute_path)}')
+              sys.exit(1)
+          "
+
+      - name: Validate variables.example.yml syntax
+        run: |
+          python3 -c "
+          import yaml, sys
+          with open('config/variables.example.yml') as f:
+              data = yaml.safe_load(f)
+          if data is None:
+              print('❌ variables.example.yml is empty')
+              sys.exit(1)
+          print('✅ config/variables.example.yml is valid YAML')
+          "

.gitignore

@@ -34,9 +34,10 @@ ansible/.vault_pass
 !.env.example
 
 # Central config (actual values — never commit)
-configs/infrastructure-*.yml
-!configs/infrastructure.yml
-configs/credentials/
+config/infrastructure-*.yml
+!config/infrastructure.yml
+config/variables.yml
+config/credentials/
 
 # Log files (keep the directory via .gitkeep)
 logs/**

README.md

@@ -12,7 +12,7 @@ Platform automation toolkit for **Azure Local** — deployment scripts, validati
 | Directory | Description |
 |-----------|-------------|
 | **[scripts/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/scripts)** | 200+ PowerShell scripts organized by deployment stage (02–08), plus common modules, validation, handover, lifecycle, and tools |
-| **[configs/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/configs)** | Master infrastructure config template, ARM templates, and variable registry |
+| **[config/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/configs)** | Master infrastructure config template, ARM templates, and variable registry |
 | **[tools/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/tools)** | Planning utilities (S2D capacity calculator) |
 | **[tests/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/tests)** | Test infrastructure (future Pester suites) |
 
@@ -34,8 +34,8 @@ The toolkit follows a structured deployment lifecycle:
 
 The toolkit uses a config-driven approach:
 
-- **`configs/infrastructure.yml`** — Master configuration template with 14 sections covering Azure tenant, networking, compute, storage, security, and more
-- **`configs/variables.template.yml`** — Azure Local-specific variables for deployment
+- **`config/infrastructure.yml`** — Master configuration template with 14 sections covering Azure tenant, networking, compute, storage, security, and more
+- **`config/variables.example.yml`** — Azure Local-specific variables for deployment
 
 ## Related Repositories
 

configs/Generate-AzureLocal-Parameters.ps1 → config/Generate-AzureLocal-Parameters.ps1

@@ -20,7 +20,7 @@
       - storageNetworkList     (from network_intents with storage_networks)
 
 .PARAMETER ConfigPath
-    Path to the infrastructure YAML file. Defaults to configs/infrastructure.yml
+    Path to the infrastructure YAML file. Defaults to config/infrastructure.yml
     relative to the repository root.
 
 .PARAMETER AuthType
@@ -35,11 +35,11 @@
     Show what would be generated without writing the file.
 
 .EXAMPLE
-    .\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure-azl-demo.yml" -AuthType AD
+    .\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure-azl-demo.yml" -AuthType AD
     Generates AD parameters file from the azl-demo config.
 
 .EXAMPLE
-    .\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure-azl-lab.yml" -AuthType LocalIdentity -WhatIf
+    .\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure-azl-lab.yml" -AuthType LocalIdentity -WhatIf
     Shows what would be generated for local identity without writing a file.
 #>
 

configs/azure/arm-templates/README.md → config/azure/arm-templates/README.md

@@ -43,13 +43,13 @@ Use the config-driven generation script to populate parameters from `infrastruct
 
 ```powershell
 # Generate AD parameter file
-.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType AD
+.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType AD
 
 # Generate Local Identity parameter file
-.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType LocalIdentity
+.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType LocalIdentity
 ```
 
-The script reads all 54 parameters from `infrastructure.yml`, resolves Key Vault references, and writes a deployment-ready JSON file. See `configs/Generate-AzureLocal-Parameters.ps1` for full documentation.
+The script reads all 54 parameters from `infrastructure.yml`, resolves Key Vault references, and writes a deployment-ready JSON file. See `config/Generate-AzureLocal-Parameters.ps1` for full documentation.
 
 ### Option 2: Manual Placeholder Replacement
 

configs/azure/arm-templates/cluster-deployment/README.md → config/azure/arm-templates/cluster-deployment/README.md

@@ -30,13 +30,13 @@ Use the generation script to populate all 54 parameters from `infrastructure.yml
 
 ```powershell
 # AD auth
-.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType AD
+.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType AD
 
 # Local Identity auth
-.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType LocalIdentity
+.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType LocalIdentity
 ```
 
-The script reads the YAML config, maps all values, and writes a deployment-ready JSON. See `configs/Generate-AzureLocal-Parameters.ps1` for full documentation.
+The script reads the YAML config, maps all values, and writes a deployment-ready JSON. See `config/Generate-AzureLocal-Parameters.ps1` for full documentation.
 
 ### Option B: Manual Replacement
 
@@ -101,10 +101,10 @@ Key differences:
 Instead of manually filling placeholders, use the generation script:
 
 ```powershell
-.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType AD
+.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType AD
 ```
 
-See `configs/Generate-AzureLocal-Parameters.ps1` for full documentation.
+See `config/Generate-AzureLocal-Parameters.ps1` for full documentation.
 
 ## Validated Examples
 

configs/variables/assets/master-registry.yaml → config/schema/master-registry.yaml

@@ -2,7 +2,7 @@
 # Master Variable Registry - Azure Local Cloudnology Cloud Management Platform
 # =============================================================================
 # Version: 4.0.0
-# Schema: infrastructure.schema.json (v4.0.0)
+# Schema: variables.schema.json (v4.0.0)
 # Last Updated: 2026-03-05
 #
 # This file defines ALL variable names, types, and descriptions used across
@@ -83,7 +83,7 @@ _metadata:
       change: "Added B2B, GitLab, Arc Resource Bridge, cluster networking, monitoring extended"
       reason: "Variable audit from 157 PowerShell scripts"
   cross_references:
-    - source: "infrastructure.schema.json"
+    - source: "variables.schema.json"
       relationship: "validates infrastructure files against these definitions"
     - source: "registry-reference.mdx"
       relationship: "human-readable documentation of this registry"

configs/variables/assets/infrastructure.schema.json → config/schema/variables.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/Azure Local Cloud/azl-env/schemas/infrastructure.schema.json",
+  "$id": "https://github.com/Azure Local Cloud/azl-env/schemas/variables.schema.json",
   "title": "Azure Local Infrastructure Configuration (v4.0.0)",
   "description": "JSON Schema for validating Azure Local environment infrastructure.yml files. Aligned with master-registry.yaml v4.0.0 — 13-section hierarchy. NOTE: This schema is currently hand-maintained and MUST be kept in sync with master-registry.yaml (the canonical source). TODO: Auto-generate this schema from master-registry.yaml to prevent drift.",
   "type": "object",

configs/variables.template.yml → config/variables.example.yml

@@ -1,16 +1,21 @@
-################################################################################
-# Azure Local Toolkit - Variables Template
+# =============================================================================
+# variables.example.yml
+# Central configuration — single source of truth for all deployment phases.
 #
-# Copy this file to your own variables.yml and fill in your environment values.
-# This template contains the minimum required variables for a deployment.
+# Copy this file to variables.yml and fill in your values:
+#   cp config/variables.example.yml config/variables.yml
 #
-# For the full variable reference, see:
-#   - configs/infrastructure.yml (complete 14-section schema)
-#   - configs/variables/assets/master-registry.yaml (variable definitions)
+# DO NOT commit variables.yml — it is excluded by .gitignore.
+#
+# Key Vault References:
+#   Secrets use keyvault:// URIs and are resolved at runtime.
+#   Format: keyvault://<vault-name>/<secret-name>
+#   NEVER put actual passwords or secrets in this file.
 #
-# All secrets should be stored in Azure Key Vault and referenced as:
-#   keyvault://<vault-name>/<secret-name>
-################################################################################
+# For the full variable reference, see:
+#   - config/infrastructure.yml (complete 14-section schema)
+#   - config/schema/master-registry.yaml (variable definitions)
+# =============================================================================
 
 # =============================================================================
 # SITE

config/variables/readme.md

@@ -0,0 +1,32 @@
+# Variables
+
+This directory provides supplementary variable information for the Azure Local Toolkit.
+
+## Config Structure
+
+```
+config/
+├── infrastructure.yml          # Full 14-section config (platform deployments)
+├── variables.example.yml       # Copyable template with IIC example values
+├── variables.yml               # Your actual config (gitignored)
+├── schema/
+│   ├── master-registry.yaml    # Complete variable definitions with types/defaults
+│   └── variables.schema.json   # JSON Schema for validation
+└── variables/
+    └── readme.md               # This file
+```
+
+## Quick Start
+
+```bash
+cp config/variables.example.yml config/variables.yml
+# Edit config/variables.yml with your environment values
+```
+
+## References
+
+- `config/variables.example.yml` — minimal starting template (IIC fictional data)
+- `config/infrastructure.yml` — full 14-section configuration reference
+- `config/schema/master-registry.yaml` — authoritative variable definitions
+- `config/schema/variables.schema.json` — JSON Schema for CI validation
+

docs/configuration/variables.md

@@ -16,8 +16,8 @@ Master configuration template with 14 sections covering the full Azure Local dep
 - Active Directory
 - And more...
 
-This file serves as a **metadata and schema registry**. Copy `variables.template.yml` for your deployment-specific values.
+This file serves as a **metadata and schema registry**. Copy `variables.example.yml` for your deployment-specific values.
 
-## variables.template.yml
+## variables.example.yml
 
 Azure Local-specific variables extracted from the master config. Copy this file to `variables.yml` (gitignored) and fill in your environment values.

docs/index.md

@@ -12,7 +12,7 @@ Platform automation toolkit for **Azure Local** — deployment scripts, validati
 | Directory | Description |
 |-----------|-------------|
 | **scripts/** | 200+ PowerShell scripts organized by deployment stage (02–08), plus common modules, validation, handover, lifecycle, and tools |
-| **configs/** | Master infrastructure config template, ARM templates, and variable registry |
+| **config/** | Master infrastructure config template, ARM templates, and variable registry |
 | **tools/** | Planning utilities (S2D capacity calculator) |
 | **tests/** | Test infrastructure (future Pester suites) |
 
@@ -35,7 +35,7 @@ Platform automation toolkit for **Azure Local** — deployment scripts, validati
 ## Getting Started
 
 1. Clone the repository
-2. Copy `configs/variables.template.yml` to `configs/variables.yml`
+2. Copy `config/variables.example.yml` to `config/variables.yml`
 3. Fill in your environment-specific values
 4. Follow the deployment stage guides in order (02 → 08)
 

scripts/common/idrac-management/Enable-IdracVnc.ps1

@@ -66,15 +66,15 @@
     Ignore SSL certificate validation errors (useful for self-signed iDRAC certificates).
 
 .EXAMPLE
-    .\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml"
+    .\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml"
     Config-driven: enables VNC on all nodes using YAML settings and Key Vault credentials.
 
 .EXAMPLE
-    .\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -TargetNode "node-01"
+    .\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -TargetNode "node-01"
     Config-driven: targets only a specific node.
 
 .EXAMPLE
-    .\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -WhatIf
+    .\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -WhatIf
     Config-driven dry run: shows what would be configured without making changes.
 
 .EXAMPLE

scripts/common/idrac-management/README.md

@@ -42,20 +42,20 @@ Enables and configures VNC access on Dell iDRAC via Redfish API.
 
 ```powershell
 # Enable VNC on all nodes using infrastructure.yml settings
-.\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -IgnoreCertificateErrors
+.\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -IgnoreCertificateErrors
 
 # Target a single node
-.\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -TargetNode "node-01"
+.\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -TargetNode "node-01"
 
 # Dry run — show what would change without applying
-.\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -WhatIf
+.\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -WhatIf
 
 # Override VNC port from config default
-.\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -VNCPort 5902
+.\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -VNCPort 5902
 
 # Provide credentials explicitly (skips Key Vault resolution)
 $cred = Get-Credential -UserName "idrac_admin"
-.\Enable-IdracVnc.ps1 -ConfigPath "configs/infrastructure.yml" -Credential $cred
+.\Enable-IdracVnc.ps1 -ConfigPath "config/infrastructure.yml" -Credential $cred
 ```
 
 **Usage — Standalone mode:**

scripts/common/utilities/helpers/Connect-AzureCliSession.ps1

@@ -41,7 +41,7 @@
 
 .EXAMPLE
     # Read values from infrastructure.yml
-    .\Connect-AzureCliSession.ps1 -ConfigPath "../../configs/infrastructure.yml"
+    .\Connect-AzureCliSession.ps1 -ConfigPath "../../config/infrastructure.yml"
 
 .NOTES
     File Name      : Connect-AzureCliSession.ps1

scripts/common/utilities/helpers/Connect-AzureSession.ps1

@@ -45,7 +45,7 @@
 
 .EXAMPLE
     # Read values from infrastructure.yml
-    .\Connect-AzureSession.ps1 -ConfigPath "../../configs/infrastructure.yml"
+    .\Connect-AzureSession.ps1 -ConfigPath "../../config/infrastructure.yml"
 
 .NOTES
     File Name      : Connect-AzureSession.ps1

scripts/common/utilities/helpers/config-loader.ps1

@@ -538,13 +538,13 @@ function Get-AvailableSolutions {
 
 .DESCRIPTION
     Primary function for deployment scripts to load configuration.
-    Loads configs/infrastructure.yml from the repository root.
+    Loads config/infrastructure.yml from the repository root.
 
     This is the simplified loader for scripts that need direct access
     to infrastructure configuration without solution-based merging.
 
 .PARAMETER ConfigPath
-    Optional. Path to infrastructure.yml. Defaults to configs/infrastructure.yml
+    Optional. Path to infrastructure.yml. Defaults to config/infrastructure.yml
     in the repository root.
 
 .EXAMPLE
@@ -563,7 +563,7 @@ function Get-InfrastructureConfig {
         [string]$ConfigPath
     )
 
-    # Default to configs/infrastructure.yml in repo root
+    # Default to config/infrastructure.yml in repo root
     if (-not $ConfigPath) {
         $ConfigPath = Join-Path $script:RepoRoot "configs\infrastructure.yml"
     }