[INFRA] Standardize variable management, naming, and structure across all repositories

[kristopherjturner]

Problem

Variable management is inconsistent across repos — different folder names, file names, hierarchies, and documentation patterns. Things are spread everywhere.

Current State by Repo

Repo	Config Folder	Config File(s)	Variable Docs	Hierarchy
azurelocal-toolkit	configs/	infrastructure.yml (full 13-section v4.0.0), variables.template.yml (simplified flat)	configs/variables/readme.md	v4.0.0 master-registry aligned
azurelocal-sofs-fslogix	config/	variables.example.yml (solution-specific flat)	docs/standards/variables.md, docs/reference/variables.md, docs/deployment/variables.md — 3 separate places	Flat, solution-specific sections
azurelocal.github.io	standards/variable-management/	master-registry.yaml, infrastructure.schema.json	7 docs: index, registry-reference, schema-validation, usage-workflows, technical-standards, governance, examples, troubleshooting	v4.0.0, 970+ variables, 13 sections
aurelocal-avd	config/	*.yml files	Unknown	Likely divergent
azurelocal-loadtools	config/	clusters/, credentials/, profiles/, variables/ subdirs	docs/ various	Completely different structure

Specific Problems

1. Folder naming inconsistency: configs/ (toolkit) vs config/ (SOFS, AVD, loadtools) — no standard
2. File naming inconsistency: infrastructure.yml vs variables.yml vs variables.example.yml — what's the canonical name?
3. Duplicate purpose files in toolkit: infrastructure.yml (full 13-section) and variables.template.yml (simplified flat) serve overlapping purposes with different structures
4. Variable docs spread across 3 paths in SOFS: docs/standards/variables.md, docs/reference/variables.md, docs/deployment/variables.md
5. Schema divergence: The toolkit's infrastructure.yml follows the v4.0.0 master-registry 13-section hierarchy; the SOFS repo's variables.example.yml uses a flat, solution-specific structure that doesn't map to the registry
6. No shared schema validation: The Docusaurus site defines JSON Schema validation with infrastructure.schema.json but none of the solution repos use it
7. No variable governance in solution repos: The Docusaurus site has a full governance workflow (proposal > review > approval > implementation > deployment) but it's not adopted anywhere else

---

What Already Works Well (Keep/Adopt)

• Docusaurus site's variable management suite — most mature system: 970+ variable registry, JSON Schema, governance, naming rules (snake_case, ^[a-z][a-z0-9_]*$, max 50 chars)
• SOFS repo's single-file approach — config/variables.example.yml is clean, well-commented, easy to copy
• Key Vault URI pattern — both toolkit and SOFS use keyvault:// consistently
• Per-VM map pattern — both repos use zero-padded string keys ("01", "02")
• IIC fictional company values — consistent example data in both toolkit and SOFS

---

Proposed Solution

1. Standardize Config Directory Structure Across All Repos

config/                          # Standardize on singular (majority already use it)
├── variables.example.yml        # Copyable template with IIC examples
├── variables.yml                # User's actual config (gitignored)
└── schema/                      # Validation assets (optional)
    ├── master-registry.yaml     # Synced from central source
    └── variables.schema.json    # JSON Schema for validation

2. Define Two Tiers of Variable Files

• Solution repos (SOFS, AVD, loadtools, vm-conversion): Use config/variables.example.yml with a flat, solution-specific structure. Keep it simple — these are single-purpose repos.
• Platform repos (toolkit): Use config/infrastructure.yml with the full registry-aligned hierarchy for multi-solution deployments.

3. Standardize Variable Naming Rules (Adopt from Docusaurus Site)

• Format: snake_case — pattern: ^[a-z][a-z0-9_]*$
• Max 50 characters
• Top-level sections: snake_case (e.g., azure_local, data_disks)
• Keys within sections: snake_case (e.g., subscription_id, volume_size_gb)
• Per-resource maps: zero-padded string keys ("01", "02")
• Booleans: descriptive names (role_enabled: true)
• Secrets: keyvault:// URI format — never plaintext

4. Consolidate Variable Documentation Per Repo

Each repo should have exactly ONE variable reference doc:

• docs/reference/variables.md — the single variable reference
• Remove/redirect: docs/standards/variables.md -> link to org-wide variable naming standard
• Remove/redirect: docs/deployment/variables.md -> merge into getting-started or reference page

5. Add Schema Validation to CI

• Each repo maintains a config/schema/variables.schema.json
• CI validates config/variables.example.yml against the schema on every PR
• Schema synced from central source or generated per-repo

6. Retire variables.template.yml in Toolkit

Consolidate into variables.example.yml to match the org-wide pattern.

---

Migration Path

Repo	Current	Target	Changes
azurelocal-toolkit	configs/infrastructure.yml + configs/variables.template.yml	config/infrastructure.yml + config/variables.example.yml	Rename configs/ to config/, retire template, add schema
azurelocal-sofs-fslogix	config/variables.example.yml	config/variables.example.yml (no change)	Consolidate 3 variable docs to 1, add schema
aurelocal-avd	config/*.yml	config/variables.example.yml	Standardize file naming
azurelocal-loadtools	config/ (subdirs)	config/variables.example.yml + subdirs	Add standard example file
azurelocal-vm-conversion-toolkit	None	config/variables.example.yml (if applicable)	Add if scripts use config

---

Relevant Files (Audit References)

File	What It Contains
azurelocal.github.io/standards/variable-management/	Full variable mgmt suite (7 docs, 970+ vars)
azurelocal.github.io/standards/variable-management/technical-standards.mdx	Naming rules, data types, validation patterns
azurelocal.github.io/standards/variable-management/governance.mdx	Change process, versioning, repo sync
azurelocal.github.io/standards/documentation/naming-conventions.mdx	Variable naming within naming conventions v3.1
azurelocal-sofs-fslogix/config/variables.example.yml	SOFS variable template (clean, well-commented)
azurelocal-sofs-fslogix/docs/standards/variables.md	SOFS variable standards
azurelocal-sofs-fslogix/docs/reference/variables.md	SOFS variable reference
azurelocal-sofs-fslogix/docs/deployment/variables.md	SOFS variable deployment docs (redirect page)
azurelocal-toolkit/configs/infrastructure.yml	Toolkit full config (v4.0.0, 13-section)
azurelocal-toolkit/configs/variables.template.yml	Toolkit simplified template (to be retired)

---

Acceptance Criteria

• All repos use config/ (singular) as the config directory name
• All repos have config/variables.example.yml with IIC example values
• Variable naming follows snake_case rules org-wide
• Each repo has exactly ONE variable reference doc at docs/reference/variables.md
• Key Vault URI pattern (keyvault://) used consistently for all secrets
• CI validates the example config file against a schema on PR
• variables.template.yml in toolkit retired in favor of variables.example.yml
• Central variable naming standard documented and linked from all repos

[kristopherjturner]

Related Issues

• Automation interoperability standard & variable framework azurelocal-sofs-fslogix#47 — Automation interoperability standard & variable framework (the existing per-repo effort this issue standardizes org-wide)
• [INFRA] Establish unified project-wide standards across all AzureLocal repositories #14 — [INFRA] Establish unified project-wide standards across all AzureLocal repositories (companion issue covering all standards beyond variables)