Skip to content

Commit 6da03a2

Browse files
kristopherjturnerkristopherjturner
authored
Merge pull request #3 from AzureLocal/feature/issue-14-unified-standards
[INFRA] Establish unified project-wide standards (issue #14)
2 parents dc38e7b + 1c4c948 commit 6da03a2

57 files changed

Lines changed: 325 additions & 103 deletions

File tree

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: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
## Summary
2+
3+
<!-- What does this PR do? One paragraph max. -->
4+
5+
## Related Issue
6+
7+
Closes #<!-- issue number -->
8+
9+
## Type of Change
10+
11+
- [ ] Bug fix
12+
- [ ] New feature / enhancement
13+
- [ ] Documentation update
14+
- [ ] Infrastructure / CI change
15+
- [ ] Refactor (no functional change)
16+
- [ ] Other:
17+
18+
## Testing Done
19+
20+
<!-- How did you test this? What environment, configuration, and scenarios? -->
21+
22+
## Checklist
23+
24+
- [ ] I have tested this in a non-production environment
25+
- [ ] I have updated the README or `docs/` if usage changed
26+
- [ ] I have added an entry to `CHANGELOG.md` under `[Unreleased]`
27+
- [ ] My code follows the project's style guidelines in `CONTRIBUTING.md`
28+
- [ ] 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-config.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# =============================================================================
2+
# validate-config.yml — Validate config files against schema
3+
# =============================================================================
4+
# Triggered on PRs and pushes that touch config/ or this workflow.
5+
# Validates YAML syntax and JSON Schema compliance.
6+
# =============================================================================
7+
8+
name: Validate Configuration
9+
10+
on:
11+
push:
12+
branches: [main]
13+
paths:
14+
- 'config/**'
15+
- '.github/workflows/validate-config.yml'
16+
pull_request:
17+
branches: [main]
18+
paths:
19+
- 'config/**'
20+
workflow_dispatch:
21+
22+
permissions:
23+
contents: read
24+
25+
jobs:
26+
validate:
27+
runs-on: ubuntu-latest
28+
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
33+
- name: Setup Python
34+
uses: actions/setup-python@v5
35+
with:
36+
python-version: '3.12'
37+
38+
- name: Install dependencies
39+
run: pip install pyyaml jsonschema
40+
41+
- name: Validate infrastructure.yml against schema
42+
run: |
43+
python3 -c "
44+
import yaml, json, sys
45+
from jsonschema import validate, ValidationError
46+
47+
with open('config/infrastructure.yml') as f:
48+
data = yaml.safe_load(f)
49+
50+
with open('config/schema/variables.schema.json') as f:
51+
schema = json.load(f)
52+
53+
try:
54+
validate(instance=data, schema=schema)
55+
print('✅ config/infrastructure.yml passes schema validation')
56+
except ValidationError as e:
57+
print(f'❌ Schema validation failed: {e.message}')
58+
print(f' Path: {\" > \".join(str(p) for p in e.absolute_path)}')
59+
sys.exit(1)
60+
"
61+
62+
- name: Validate variables.example.yml syntax
63+
run: |
64+
python3 -c "
65+
import yaml, sys
66+
with open('config/variables.example.yml') as f:
67+
data = yaml.safe_load(f)
68+
if data is None:
69+
print('❌ variables.example.yml is empty')
70+
sys.exit(1)
71+
print('✅ config/variables.example.yml is valid YAML')
72+
"

‎.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: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,10 @@ ansible/.vault_pass
3434
!.env.example
3535

3636
# Central config (actual values — never commit)
37-
configs/infrastructure-*.yml
38-
!configs/infrastructure.yml
39-
configs/credentials/
37+
config/infrastructure-*.yml
38+
!config/infrastructure.yml
39+
config/variables.yml
40+
config/credentials/
4041

4142
# Log files (keep the directory via .gitkeep)
4243
logs/**

‎CONTRIBUTING.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,16 @@ Examples:
7777
- Test against a real Azure Local environment before submitting
7878
- Describe your test environment and results in the PR
7979

80+
## Standards
81+
82+
This project follows the **org-wide AzureLocal standards** documented at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/). Key references:
83+
84+
- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required files, directories, labels, branch naming
85+
- [Scripting Standards](https://azurelocal.cloud/standards/scripting/scripting-standards) — PowerShell conventions
86+
- [Documentation Standards](https://azurelocal.cloud/standards/documentation/documentation-standards) — Writing and formatting
87+
- [Variable Management](https://azurelocal.cloud/docs/implementation/04-variable-management-standard) — Config file patterns
88+
- [Fictional Company Policy](https://azurelocal.cloud/standards/fictional-company-policy) — Use IIC, never Contoso
89+
8090
## Code of Conduct
8191

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

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Platform automation toolkit for **Azure Local** — deployment scripts, validati
1212
| Directory | Description |
1313
|-----------|-------------|
1414
| **[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 |
15-
| **[configs/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/configs)** | Master infrastructure config template, ARM templates, and variable registry |
15+
| **[config/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/configs)** | Master infrastructure config template, ARM templates, and variable registry |
1616
| **[tools/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/tools)** | Planning utilities (S2D capacity calculator) |
1717
| **[tests/](https://github.com/AzureLocal/azurelocal-toolkit/tree/main/tests)** | Test infrastructure (future Pester suites) |
1818

@@ -34,8 +34,8 @@ The toolkit follows a structured deployment lifecycle:
3434

3535
The toolkit uses a config-driven approach:
3636

37-
- **`configs/infrastructure.yml`** — Master configuration template with 14 sections covering Azure tenant, networking, compute, storage, security, and more
38-
- **`configs/variables.template.yml`** — Azure Local-specific variables for deployment
37+
- **`config/infrastructure.yml`** — Master configuration template with 14 sections covering Azure tenant, networking, compute, storage, security, and more
38+
- **`config/variables.example.yml`** — Azure Local-specific variables for deployment
3939

4040
## Related Repositories
4141

configs/Generate-AzureLocal-Parameters.ps1 renamed to config/Generate-AzureLocal-Parameters.ps1

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
- storageNetworkList (from network_intents with storage_networks)
2121
2222
.PARAMETER ConfigPath
23-
Path to the infrastructure YAML file. Defaults to configs/infrastructure.yml
23+
Path to the infrastructure YAML file. Defaults to config/infrastructure.yml
2424
relative to the repository root.
2525
2626
.PARAMETER AuthType
@@ -35,11 +35,11 @@
3535
Show what would be generated without writing the file.
3636
3737
.EXAMPLE
38-
.\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure-azl-demo.yml" -AuthType AD
38+
.\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure-azl-demo.yml" -AuthType AD
3939
Generates AD parameters file from the azl-demo config.
4040
4141
.EXAMPLE
42-
.\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure-azl-lab.yml" -AuthType LocalIdentity -WhatIf
42+
.\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure-azl-lab.yml" -AuthType LocalIdentity -WhatIf
4343
Shows what would be generated for local identity without writing a file.
4444
#>
4545

configs/azure/.gitkeep renamed to config/azure/.gitkeep

File renamed without changes.

configs/azure/arm-templates/README.md renamed to config/azure/arm-templates/README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,13 @@ Use the config-driven generation script to populate parameters from `infrastruct
4343

4444
```powershell
4545
# Generate AD parameter file
46-
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType AD
46+
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType AD
4747
4848
# Generate Local Identity parameter file
49-
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType LocalIdentity
49+
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType LocalIdentity
5050
```
5151

52-
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.
52+
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.
5353

5454
### Option 2: Manual Placeholder Replacement
5555

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,13 @@ Use the generation script to populate all 54 parameters from `infrastructure.yml
3030

3131
```powershell
3232
# AD auth
33-
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType AD
33+
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType AD
3434
3535
# Local Identity auth
36-
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType LocalIdentity
36+
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType LocalIdentity
3737
```
3838

39-
The script reads the YAML config, maps all values, and writes a deployment-ready JSON. See `configs/Generate-AzureLocal-Parameters.ps1` for full documentation.
39+
The script reads the YAML config, maps all values, and writes a deployment-ready JSON. See `config/Generate-AzureLocal-Parameters.ps1` for full documentation.
4040

4141
### Option B: Manual Replacement
4242

@@ -101,10 +101,10 @@ Key differences:
101101
Instead of manually filling placeholders, use the generation script:
102102

103103
```powershell
104-
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "configs/infrastructure.yml" -AuthType AD
104+
.\configs\Generate-AzureLocal-Parameters.ps1 -ConfigPath "config/infrastructure.yml" -AuthType AD
105105
```
106106

107-
See `configs/Generate-AzureLocal-Parameters.ps1` for full documentation.
107+
See `config/Generate-AzureLocal-Parameters.ps1` for full documentation.
108108

109109
## Validated Examples
110110

0 commit comments

Comments
 (0)