Skip to content

Commit 01c9909

Browse files
kristopherjturnerkristopherjturner
committed
chore(standards): add docs/standards with 9 standardized MDX files
1 parent 18d7d22 commit 01c9909

9 files changed

Lines changed: 644 additions & 0 deletions

File tree

‎docs/standards/automation.mdx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Automation Interoperability
2+
3+
> **Canonical reference:** [Scripting Framework (full)](https://azurelocal.cloud/standards/scripting/scripting-framework)
4+
> **Applies to:** All AzureLocal repositories
5+
> **Last Updated:** 2026-03-17
6+
7+
---
8+
9+
## Overview
10+
11+
This standard defines how multiple automation tools (Terraform, Bicep, ARM, PowerShell, Ansible) interoperate across AzureLocal solutions. All tools share a single configuration source and must produce identical infrastructure.
12+
13+
---
14+
15+
## Config Flow
16+
17+
```mermaid
18+
flowchart TB
19+
A["config/variables.yml<br/>(single source of truth)"] --> B[Terraform .tfvars]
20+
A --> C[Bicep .bicepparam]
21+
A --> D[ARM parameters.json]
22+
A --> E[PowerShell ConvertFrom-Yaml]
23+
A --> F[Ansible group_vars]
24+
B --> G[Identical Infrastructure]
25+
C --> G
26+
D --> G
27+
E --> G
28+
F --> G
29+
```
30+
31+
---
32+
33+
## Deployment Path Matrix
34+
35+
| Tool | Azure Resources | Configuration | Monitoring | Scaling |
36+
|------|:---:|:---:|:---:|:---:|
37+
| **Terraform** | ✅ | Delegates | ✅ | ✅ |
38+
| **Bicep** | ✅ | Delegates | ✅ | ✅ |
39+
| **ARM** | ✅ | Delegates | ✅ | — |
40+
| **PowerShell** | ✅ | ✅ | ✅ | ✅ |
41+
| **Ansible** | ✅ | ✅ | ✅ | ✅ |
42+
43+
:::warning[Delegates]
44+
"Delegates" means the IaC tool provisions Azure resources but does not configure the guest OS or application layer. A separate tool (PowerShell or Ansible) handles guest configuration.
45+
:::
46+
47+
---
48+
49+
## Interoperability Rules
50+
51+
1. **Single source of truth** — `config/variables.yml` is the only config file. All tool-specific parameter files are derived.
52+
2. **Identical output** — Given the same config, every tool must produce the same infrastructure.
53+
3. **Idempotency** — All scripts and templates must be safe to re-run.
54+
4. **Error handling** — Every tool must validate config before executing changes.
55+
5. **Logging** — All operations logged to `./logs/` with consistent format.
56+
57+
---
58+
59+
## Variable Path Contract
60+
61+
Scripts must use variable paths that exist in the schema. See the [Variable Standards](variables) for naming rules and the [Variable Reference](variables) for the complete catalog.
62+
63+
---
64+
65+
## Related Standards
66+
67+
- [Scripting Standards](scripting)
68+
- [Infrastructure Standards](infrastructure)
69+
- [Solution Standards](solutions)
70+
- [Variable Standards](variables)

‎docs/standards/documentation.mdx‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Documentation Standards
2+
3+
> **Canonical reference:** [Documentation Standards (full)](https://azurelocal.cloud/standards/documentation/documentation-standards)
4+
> **Applies to:** All AzureLocal repositories
5+
> **Last Updated:** 2026-03-17
6+
7+
---
8+
9+
## Principles
10+
11+
| Principle | Rule |
12+
|-----------|------|
13+
| Documentation-First | Document **before** implementing. Keep docs current with code. |
14+
| Single Source of Truth | One authoritative document per topic. Cross-reference, don't duplicate. |
15+
| Audience-Aware | Write for operators, developers, or executives — with appropriate depth. |
16+
| Actionable | Step-by-step procedures, examples, prerequisites, and outcomes. |
17+
18+
---
19+
20+
## File Naming
21+
22+
| Type | Convention | Pattern | Example |
23+
|------|-----------|---------|---------|
24+
| Directories | lowercase-with-hyphens | `^[a-z][a-z0-9-]*$` | `guides/`, `reference/` |
25+
| Markdown (docs/) | lowercase with hyphens | `*.md` | `deployment-guide.md` |
26+
| Root files | UPPERCASE | — | `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md` |
27+
| PowerShell scripts | PascalCase | `Verb-Noun.ps1` | `Deploy-Solution.ps1` |
28+
| Config files | lowercase-with-hyphens | — | `variables.example.yml` |
29+
30+
---
31+
32+
## MkDocs Material Conventions
33+
34+
This repo uses **MkDocs Material** with the following conventions:
35+
36+
- **Admonitions**: Use `!!! note`, `!!! warning`, `!!! danger`, `!!! info`, `!!! tip`
37+
- **Code blocks**: Always include a language identifier (e.g., ` ```powershell `, ` ```yaml `)
38+
- **Code copy**: Enabled via `content.code.copy`
39+
- **Mermaid diagrams**: Supported via `pymdownx.superfences` custom fence
40+
- **Tables**: Use standard Markdown tables
41+
- **Tabs**: Use `=== "Tab Name"` via `pymdownx.tabbed`
42+
43+
---
44+
45+
## Frontmatter & Metadata
46+
47+
Every documentation page should include:
48+
49+
```markdown
50+
# Page Title
51+
52+
> Brief one-line description of the page's purpose.
53+
54+
---
55+
```
56+
57+
---
58+
59+
## Fictional Company — Infinite Improbability Corp (IIC)
60+
61+
All examples must use IIC. See the [Examples & IIC Policy](examples) page for the full reference card.
62+
63+
| Never Use | Use Instead |
64+
|-----------|-------------|
65+
| `contoso`, `fabrikam`, `northwind` | Infinite Improbability Corp |
66+
| `example.com`, `test.com` | `improbability.cloud` |
67+
| Real customer names | IIC naming patterns |
68+
69+
---
70+
71+
## Related Standards
72+
73+
- [Naming Conventions (full reference)](https://azurelocal.cloud/standards/documentation/naming-conventions)
74+
- [Badge Library](https://azurelocal.cloud/standards/documentation/badge-library)
75+
- [Scripting Standards](scripting)

‎docs/standards/examples.mdx‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Examples & IIC Policy
2+
3+
> **Canonical reference:** [Fictional Company Policy (full)](https://azurelocal.cloud/standards/fictional-company-policy)
4+
> **Applies to:** All AzureLocal repositories
5+
> **Last Updated:** 2026-03-17
6+
7+
---
8+
9+
## Policy
10+
11+
All examples, sample configurations, and walkthroughs use **one** fictional company: **Infinite Improbability Corp (IIC)**.
12+
13+
:::warning[Mandatory]
14+
Never use `contoso`, `fabrikam`, `adventure-works`, `woodgrove`, `example.com`, or any real customer name.
15+
**IIC only** — in every repo, every example, every sample config.
16+
:::
17+
18+
---
19+
20+
## IIC Reference Card
21+
22+
| Attribute | Value |
23+
|-----------|-------|
24+
| **Full Name** | Infinite Improbability Corp |
25+
| **Abbreviation** | IIC |
26+
| **Domain (public)** | `improbability.cloud` / `iic.cloud` |
27+
| **Domain (on-prem AD)** | `iic.local` |
28+
| **NetBIOS Name** | `IMPROBABLE` |
29+
| **Entra ID Tenant** | `improbability.onmicrosoft.com` |
30+
| **Email Pattern** | `user@improbability.cloud` |
31+
32+
---
33+
34+
## AzureLocal Naming Patterns
35+
36+
### Azure Resources
37+
38+
| Resource | Pattern | Example |
39+
|----------|---------|---------|
40+
| Resource Group | `rg-iic-<purpose>-<##>` | `rg-iic-platform-01` |
41+
| Virtual Network | `vnet-iic-<purpose>-<##>` | `vnet-iic-compute-01` |
42+
| Subnet | `snet-iic-<purpose>` | `snet-iic-management` |
43+
| Network Security Group | `nsg-iic-<purpose>` | `nsg-iic-compute` |
44+
| Key Vault | `kv-iic-<purpose>` | `kv-iic-platform` |
45+
| Storage Account | `stiic<purpose><##>` | `stiicdata01` |
46+
| Log Analytics | `law-iic-<purpose>-<##>` | `law-iic-monitor-01` |
47+
| Managed Identity | `id-iic-<purpose>` | `id-iic-deploy` |
48+
49+
### Active Directory
50+
51+
| Resource | Pattern | Example |
52+
|----------|---------|---------|
53+
| OU path | `OU=<Purpose>,OU=Servers,DC=iic,DC=local` | — |
54+
| Service account | `svc.iic.<purpose>` | `svc.iic.deploy` |
55+
| Group | `grp-iic-<purpose>` | `grp-iic-admins` |
56+
57+
### IP Addresses
58+
59+
| Network | Range | Usage |
60+
|---------|-------|-------|
61+
| Management | `10.0.0.0/24` | Node management |
62+
| Compute | `10.0.2.0/24` | Workload traffic |
63+
64+
---
65+
66+
## Real Identities
67+
68+
| Name | Usage |
69+
|------|-------|
70+
| **Azure Local Cloud** | Community project, GitHub org, `azurelocal.cloud` |
71+
| **Hybrid Cloud Solutions** | Author/maintainer LLC, script headers, copyright |
72+
73+
---
74+
75+
## Usage Examples
76+
77+
### In `config/variables.example.yml`
78+
79+
```yaml
80+
subscription:
81+
subscription_id: "00000000-0000-0000-0000-000000000000"
82+
tenant_id: "00000000-0000-0000-0000-000000000000"
83+
location: "eastus"
84+
85+
security:
86+
keyvault_name: "kv-iic-platform"
87+
88+
azure_local:
89+
resource_group: "rg-iic-platform-01"
90+
cluster_name: "azlocal-iic-01"
91+
```
92+
93+
### In Documentation
94+
95+
> Infinite Improbability Corp deploys Azure Local clusters using IIC naming patterns,
96+
> with all configuration driven from a single `config/variables.yml` file.
97+
98+
---
99+
100+
## Enforcement
101+
102+
- **PR review**: Reviewers flag any use of `contoso`, `fabrikam`, or other non-IIC names
103+
- **Config validation**: `variables.example.yml` uses IIC naming in all placeholders
104+
- **CI**: Vale linting rules flag non-IIC fictional company names (when configured)

‎docs/standards/index.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Standards
2+
3+
This repository follows the **org-wide AzureLocal standards** maintained on the central documentation site.
4+
5+
:::info[Central Standards]
6+
The full standards suite is at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/).
7+
This section provides the key rules adapted for this solution.
8+
:::
9+
10+
---
11+
12+
## Standards Pages
13+
14+
| Standard | Local Page | Central Reference |
15+
|----------|-----------|------------------|
16+
| Documentation | [Documentation Standards](documentation) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) |
17+
| Scripting | [Scripting Standards](scripting) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) |
18+
| Variables | [Variable Standards](variables) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) |
19+
| Naming Conventions | [Naming Conventions](naming) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) |
20+
| Solutions | [Solution Standards](solutions) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) |
21+
| Infrastructure | [Infrastructure Standards](infrastructure) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) |
22+
| Automation | [Automation Interoperability](automation) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) |
23+
| Examples & IIC | [Examples & IIC](examples) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) |
24+
25+
---
26+
27+
## References
28+
29+
- [Variable Reference](variables) — Per-variable catalog for this repo
30+
- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout
31+
32+
---
33+
34+
## Repo-Specific Conventions
35+
36+
- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible
37+
- **Config file**: `config/variables.example.yml` — see [Variable Reference](variables)
38+
- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples)

‎docs/standards/infrastructure.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Infrastructure Standards
2+
3+
> **Canonical reference:** [Infrastructure Standards (full)](https://azurelocal.cloud/standards/infrastructure/)
4+
> **Applies to:** All AzureLocal repositories
5+
> **Last Updated:** 2026-03-17
6+
7+
---
8+
9+
## Overview
10+
11+
Standards for Infrastructure as Code (IaC), Terraform state management, and deployment processes for AzureLocal solutions.
12+
13+
---
14+
15+
## Infrastructure Pipeline
16+
17+
```mermaid
18+
flowchart LR
19+
A[Generate Variables] --> B[Validate Config]
20+
B --> C[Plan Infrastructure]
21+
C --> D[Review Changes]
22+
D --> E[Apply Changes]
23+
E --> F[Update State]
24+
```
25+
26+
---
27+
28+
## State Management
29+
30+
| Principle | Rule |
31+
|-----------|------|
32+
| Remote state | Store Terraform state in Azure Storage Account |
33+
| State locking | Enable locking during all operations |
34+
| Backup | Regular state file backups before destructive operations |
35+
| Naming | `<solution>-<env>.tfstate` (e.g., `platform-prod.tfstate`) |
36+
37+
---
38+
39+
## IaC Tool Parity
40+
41+
All tools must produce **identical infrastructure** when given the same configuration values:
42+
43+
| Tool | Primary Format | State Management |
44+
|------|---------------|-----------------|
45+
| Terraform | `.tf` / `.tfvars` | Remote state in Azure Storage |
46+
| Bicep | `.bicep` / `.bicepparam` | ARM deployment history |
47+
| ARM | `.json` | ARM deployment history |
48+
| PowerShell | `.ps1` | Config-driven, logged |
49+
| Ansible | `.yml` | Inventory-based |
50+
51+
---
52+
53+
## Deployment Phases
54+
55+
| Phase | Scope | Tools |
56+
|-------|-------|-------|
57+
| Phase 1: Azure Foundation | Resource groups, networking, Key Vault, storage | Terraform, Bicep, ARM |
58+
| Phase 2: Compute & Workload | VMs, clusters, workload deployment | Terraform, PowerShell |
59+
| Phase 3: Configuration | Guest config, monitoring, policies | PowerShell, Ansible |
60+
61+
---
62+
63+
## Related Standards
64+
65+
- [Infrastructure Generation & Deployment Process](https://azurelocal.cloud/standards/infrastructure/infrastructure-generation-deployment-process)
66+
- [State Management](https://azurelocal.cloud/standards/infrastructure/state-management)
67+
- [Solution Development Standard](solutions)
68+
- [Variable Standards](variables)
69+
- [Automation Interoperability](automation)

0 commit comments

Comments
 (0)