Skip to content

Commit d7befcb

Browse files
kristopherjturnerkristopherjturner
authored
Merge pull request #17 from AzureLocal/feature/issue-14-unified-standards
[INFRA] Establish unified project-wide standards (issue #14)
2 parents a795a35 + 0b0178d commit d7befcb

47 files changed

Lines changed: 27496 additions & 4 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/pull_request_template.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,11 @@ Closes #<!-- issue number -->
2626
- [ ] I have added an entry to `CHANGELOG.md` under `[Unreleased]`
2727
- [ ] My code follows the project's style guidelines in `CONTRIBUTING.md`
2828
- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
29+
30+
## Standards Compliance
31+
32+
- [ ] Follows [repo structure standard](https://azurelocal.cloud/standards/repo-structure) (required files present)
33+
- [ ] Follows [naming conventions](https://azurelocal.cloud/standards/documentation/naming-conventions) (files, variables, resources)
34+
- [ ] Uses [IIC fictional company](https://azurelocal.cloud/standards/fictional-company-policy) in all examples (never Contoso)
35+
- [ ] Config changes validated against JSON Schema (if applicable)
36+
- [ ] No hardcoded IPs, names, secrets, or environment-specific values in committed code

‎.github/workflows/validate-repo-structure.yml‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
name: Validate Repo Structure
2+
on:
3+
pull_request:
4+
branches: [main]
5+
6+
jobs:
7+
check-structure:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v4
11+
12+
- name: Check required root files
13+
run: |
14+
missing=0
15+
for f in README.md CONTRIBUTING.md LICENSE CHANGELOG.md .gitignore; do
16+
if [ ! -f "$f" ]; then
17+
echo "::error::Missing required file: $f"
18+
missing=$((missing + 1))
19+
fi
20+
done
21+
if [ $missing -gt 0 ]; then
22+
echo "::error::$missing required root file(s) missing"
23+
exit 1
24+
fi
25+
echo "All required root files present"
26+
27+
- name: Check required directories
28+
run: |
29+
missing=0
30+
for d in docs .github; do
31+
if [ ! -d "$d" ]; then
32+
echo "::error::Missing required directory: $d/"
33+
missing=$((missing + 1))
34+
fi
35+
done
36+
if [ $missing -gt 0 ]; then
37+
echo "::error::$missing required directory(s) missing"
38+
exit 1
39+
fi
40+
echo "All required directories present"
41+
42+
- name: Check PR template
43+
run: |
44+
if [ ! -f ".github/PULL_REQUEST_TEMPLATE.md" ]; then
45+
echo "::error::Missing .github/PULL_REQUEST_TEMPLATE.md"
46+
exit 1
47+
fi
48+
echo "PR template found"
49+
50+
- name: Check config structure (if config dir exists)
51+
run: |
52+
if [ -d "config" ]; then
53+
missing=0
54+
if [ ! -f "config/variables.example.yml" ]; then
55+
echo "::error::Missing config/variables.example.yml"
56+
missing=$((missing + 1))
57+
fi
58+
if [ ! -f "config/schema/variables.schema.json" ]; then
59+
echo "::error::Missing config/schema/variables.schema.json"
60+
missing=$((missing + 1))
61+
fi
62+
if [ $missing -gt 0 ]; then
63+
exit 1
64+
fi
65+
echo "Config structure valid"
66+
else
67+
echo "No config/ directory — skipping config checks"
68+
fi
69+
70+
- name: Check variable reference doc (if config dir exists)
71+
run: |
72+
if [ -d "config" ]; then
73+
if [ ! -f "docs/reference/variables.md" ]; then
74+
echo "::error::Missing docs/reference/variables.md (required when config/ exists)"
75+
exit 1
76+
fi
77+
echo "Variable reference doc found"
78+
else
79+
echo "No config/ directory — skipping variable reference check"
80+
fi

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,4 @@ yarn-error.log*
2222
# References
2323
/product-azure-local-anywhere
2424
/prodtech-docs-azl-toolkit
25+
/project_management

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,15 @@ This starts a local development server at `http://localhost:3000/`.
7575
- Place in `blog/YYYY-MM-DD-slug/` directory
7676
- Include `authors` and `tags` frontmatter referencing `blog/authors.yml` and `blog/tags.yml`
7777

78+
## Standards
79+
80+
This project follows the **org-wide AzureLocal standards** documented at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/). Key references:
81+
82+
- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required files, directories, labels, branch naming
83+
- [Documentation Standards](https://azurelocal.cloud/standards/documentation/documentation-standards) — Writing and formatting
84+
- [Naming Conventions](https://azurelocal.cloud/standards/documentation/naming-conventions) — Files, variables, resources
85+
- [Fictional Company Policy](https://azurelocal.cloud/standards/fictional-company-policy) — Use IIC, never Contoso
86+
7887
## Code of Conduct
7988

8089
Be respectful and constructive. Keep discussions on-topic and collaborative.

‎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)