Skip to content

Commit 0b0178d

Browse files
kristopherjturnerkristopherjturner
committed
Merge branch 'feature/issue-15-variable-standardization' into feature/issue-14-unified-standards
2 parents 352869e + 7aff59b commit 0b0178d

4 files changed

Lines changed: 209 additions & 4 deletions

File tree

‎docs/implementation/03-key-inputs-and-variables.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -735,15 +735,19 @@ After gathering all required inputs and creating your infrastructure.yml:
735735

736736
---
737737

738-
*For questions about configuration variables or validation, refer to the Configuration Management Standard or contact the Azure Local Cloud documentation team.*
738+
*For questions about configuration variables or validation, refer to the [Variable Management Standard](./04-variable-management-standard.mdx) or contact the Azure Local Cloud documentation team.*
739+
740+
:::tip Cross-Repository Standard
741+
The **[Variable Management Standard](./04-variable-management-standard.mdx)** documents the org-wide pattern for `config/variables.example.yml`, JSON Schema validation, and `docs/reference/variables.md` across all five solution repositories.
742+
:::
739743

740744
---
741745

742746
## Navigation
743747

744748
| Previous | Up | Next |
745749
|----------|-----|------|
746-
| [How to Use This Runbook](./02-how-to-use-this-runbook.mdx) | [Implementation Guide](./index.mdx) | [Prerequisites and Assumptions](./04-prerequisites-and-assumptions.mdx) |
750+
| [How to Use This Runbook](./02-how-to-use-this-runbook.mdx) | [Implementation Guide](./index.mdx) | [Variable Management Standard](./04-variable-management-standard.mdx) |
747751

748752
---
749753

‎docs/implementation/04-prerequisites-and-assumptions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Prerequisites and Assumptions"
33
sidebar_label: "Prerequisites and Assumptions"
4-
sidebar_position: 4
4+
sidebar_position: 5
55
description: "Requirements and assumptions for Azure Local deployment."
66
category: "RUNBOOK"
77
scope: "Pre-deployment requirements"

‎docs/implementation/04-variable-management-standard.mdx‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: "Variable Management Standard"
3+
sidebar_label: "Variable Management Standard"
4+
sidebar_position: 4
5+
description: "Organization-wide variable naming, structure, and management standard for all AzureLocal solution repositories."
6+
category: "STANDARD"
7+
scope: "All AzureLocal solution repositories"
8+
purpose: "Define the canonical variable management pattern used across the org"
9+
author: "Azure Local Cloudnology Team"
10+
created: 2026-03-17
11+
updated: 2026-03-17
12+
version: "1.0.0"
13+
tags:
14+
- azure-local
15+
- configuration
16+
- variables
17+
- standards
18+
keywords:
19+
- variable management
20+
- naming conventions
21+
- variables.yml
22+
- variables.example.yml
23+
- schema validation
24+
status: "approved"
25+
---
26+
27+
# Variable Management Standard
28+
29+
[![Standard](https://img.shields.io/badge/Type-Standard-green?style=flat-square)](./index.mdx)
30+
[![Azure](https://img.shields.io/badge/Platform-Azure_Local-0078D4?style=flat-square&logo=microsoftazure)](https://learn.microsoft.com/en-us/azure/azure-local/)
31+
32+
> **DOCUMENT CATEGORY**: Standard
33+
> **SCOPE**: All AzureLocal solution repositories
34+
> **PURPOSE**: Canonical variable naming, structure, and management pattern
35+
36+
**Status**: Active
37+
38+
---
39+
40+
## Overview
41+
42+
Every AzureLocal solution repository follows a **single, standardized pattern** for managing deployment variables. This ensures consistency, validation, and automation compatibility across all solutions.
43+
44+
**Core principle:** One config file, one schema, one reference doc — per repo.
45+
46+
| Artifact | Location | Purpose |
47+
|----------|----------|---------|
48+
| Example config | `config/variables.example.yml` | Template with placeholder values — copy to `variables.yml` |
49+
| Active config | `config/variables.yml` | Environment-specific values (**never committed**) |
50+
| JSON Schema | `config/schema/variables.schema.json` | Validation rules enforced by CI |
51+
| Reference doc | `docs/reference/variables.md` | Human-readable variable catalog |
52+
53+
---
54+
55+
## Repository Matrix
56+
57+
| Repository | Config | Schema | Reference Doc | CI Workflow |
58+
|-----------|--------|--------|---------------|------------|
59+
| [azurelocal-toolkit](https://github.com/AzureLocal/azurelocal-toolkit) | [variables.example.yml](https://github.com/AzureLocal/azurelocal-toolkit/blob/main/config/variables.example.yml) | [schema](https://github.com/AzureLocal/azurelocal-toolkit/blob/main/config/schema/variables.schema.json) | [reference](https://github.com/AzureLocal/azurelocal-toolkit/blob/main/docs/reference/variables.md) | `validate-config.yml` |
60+
| [azurelocal-sofs-fslogix](https://github.com/AzureLocal/azurelocal-sofs-fslogix) | [variables.example.yml](https://github.com/AzureLocal/azurelocal-sofs-fslogix/blob/main/config/variables.example.yml) | [schema](https://github.com/AzureLocal/azurelocal-sofs-fslogix/blob/main/config/schema/variables.schema.json) | [reference](https://github.com/AzureLocal/azurelocal-sofs-fslogix/blob/main/docs/reference/variables.md) | `validate-config.yml` |
61+
| [aurelocal-avd](https://github.com/AzureLocal/aurelocal-avd) | [variables.example.yml](https://github.com/AzureLocal/aurelocal-avd/blob/main/config/variables.example.yml) | [schema](https://github.com/AzureLocal/aurelocal-avd/blob/main/config/schema/variables.schema.json) | [reference](https://github.com/AzureLocal/aurelocal-avd/blob/main/docs/reference/variables.md) | `validate-config.yml` |
62+
| [azurelocal-loadtools](https://github.com/AzureLocal/azurelocal-loadtools) | [variables.example.yml](https://github.com/AzureLocal/azurelocal-loadtools/blob/main/config/variables.example.yml) | [schema](https://github.com/AzureLocal/azurelocal-loadtools/blob/main/config/schema/variables.schema.json) | [reference](https://github.com/AzureLocal/azurelocal-loadtools/blob/main/docs/reference/variables.md) | `validate-config.yml` |
63+
| [azurelocal-vm-conversion-toolkit](https://github.com/AzureLocal/azurelocal-vm-conversion-toolkit) | [variables.example.yml](https://github.com/AzureLocal/azurelocal-vm-conversion-toolkit/blob/main/config/variables.example.yml) | [schema](https://github.com/AzureLocal/azurelocal-vm-conversion-toolkit/blob/main/config/schema/variables.schema.json) | [reference](https://github.com/AzureLocal/azurelocal-vm-conversion-toolkit/blob/main/docs/reference/variables.md) | `validate-config.yml` |
64+
65+
---
66+
67+
## Directory Structure
68+
69+
Every repository follows this layout:
70+
71+
```
72+
repo-root/
73+
├── config/
74+
│ ├── variables.example.yml # Committed — template
75+
│ ├── variables.yml # .gitignored — your values
76+
│ └── schema/
77+
│ └── variables.schema.json # JSON Schema for CI validation
78+
├── docs/
79+
│ └── reference/
80+
│ └── variables.md # Human-readable variable catalog
81+
└── .github/
82+
└── workflows/
83+
└── validate-config.yml # CI: validates example against schema
84+
```
85+
86+
---
87+
88+
## Naming Conventions
89+
90+
### File Naming
91+
92+
| File | Name | Notes |
93+
|------|------|-------|
94+
| Example config | `variables.example.yml` | Always `.example.yml`, never `.template.yml` |
95+
| Active config | `variables.yml` | Never committed |
96+
| Schema | `variables.schema.json` | Draft 2020-12 JSON Schema |
97+
| Reference doc | `variables.md` | Always at `docs/reference/variables.md` |
98+
99+
### Variable Naming
100+
101+
| Scope | Convention | Example |
102+
|-------|-----------|---------|
103+
| Top-level sections | `snake_case` | `azure_local`, `session_hosts` |
104+
| Keys within sections | `snake_case` | `subscription_id`, `cluster_name` |
105+
| Booleans | Descriptive name | `enable_real_time: true` |
106+
| Secrets | `keyvault://` URI | `keyvault://kv-name/secret-name` |
107+
| Azure resource IDs | Full ARM path | `/subscriptions/.../providers/...` |
108+
| Enum values | `snake_case` | `auth_method: "managed_identity"` |
109+
110+
### Section Organization
111+
112+
Each `variables.example.yml` is organized into **logical sections** separated by comment headers:
113+
114+
```yaml
115+
# =============================================================================
116+
# Section Name
117+
# =============================================================================
118+
section_name:
119+
key: "value"
120+
```
121+
122+
Common sections across repos include:
123+
- **azure** — Subscription, tenant, resource group, location
124+
- **keyvault** — Key Vault name and auth method
125+
- **azure_local** — Cluster-specific configuration
126+
- **tags** — Resource tagging (present in every repo)
127+
128+
Solution-specific sections are documented in each repo's `docs/reference/variables.md`.
129+
130+
---
131+
132+
## Secret Management
133+
134+
Secrets are **never** stored in plaintext in `variables.yml`. All sensitive values use the `keyvault://` URI format:
135+
136+
```yaml
137+
credentials:
138+
admin_password: "keyvault://kv-mysite/admin-password"
139+
```
140+
141+
**Resolution flow:**
142+
143+
1. Tool parses the URI → vault name + secret name
144+
2. Tool calls `az keyvault secret show` (or SDK equivalent)
145+
3. Secret value is passed directly — never written to disk
146+
147+
Repos that use Key Vault references: **toolkit**, **sofs-fslogix**, **avd**, **loadtools**
148+
149+
---
150+
151+
## Schema Validation
152+
153+
Every repo includes a JSON Schema that validates the structure of `variables.example.yml`. The CI workflow runs on every PR and push to `config/**`:
154+
155+
```yaml
156+
# .github/workflows/validate-config.yml
157+
name: Validate Config
158+
on:
159+
push:
160+
paths: ['config/**']
161+
pull_request:
162+
paths: ['config/**']
163+
164+
jobs:
165+
validate:
166+
runs-on: ubuntu-latest
167+
steps:
168+
- uses: actions/checkout@v4
169+
- uses: actions/setup-python@v5
170+
with:
171+
python-version: '3.12'
172+
- run: pip install pyyaml jsonschema
173+
- run: |
174+
python -c "
175+
import yaml, jsonschema, sys
176+
schema = yaml.safe_load(open('config/schema/variables.schema.json'))
177+
data = yaml.safe_load(open('config/variables.example.yml'))
178+
jsonschema.validate(data, schema)
179+
print('Validation PASSED')
180+
"
181+
```
182+
183+
---
184+
185+
## Getting Started with a New Repo
186+
187+
When adding a new solution repository to the org:
188+
189+
1. **Create** `config/variables.example.yml` with solution-specific sections
190+
2. **Create** `config/schema/variables.schema.json` with Draft 2020-12 JSON Schema
191+
3. **Create** `docs/reference/variables.md` documenting every variable with type, required, description, and default
192+
4. **Add** `.github/workflows/validate-config.yml` (copy from any existing repo)
193+
5. **Add** `config/variables.yml` to `.gitignore`
194+
6. **Update this page** with a link in the Repository Matrix table
195+
196+
---
197+
198+
## Related Documentation
199+
200+
- **[Key Inputs and Variables](./03-key-inputs-and-variables.mdx)** — How the toolkit uses `infrastructure.yml` and `master-registry.yaml`
201+
- **[Naming Standards](../planning/01-naming-standards.mdx)** — Azure resource naming conventions

‎docs/implementation/05-authentication.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Authentication Methods"
33
sidebar_label: "Authentication"
4-
sidebar_position: 5
4+
sidebar_position: 6
55
description: "Authentication options for Azure Local deployment — Azure PowerShell and Azure CLI session setup."
66
category: "RUNBOOK"
77
scope: "Azure authentication for deployment scripts"

0 commit comments

Comments
 (0)