Skip to content

Commit efdeada

Browse files
kristopherjturnerkristopherjturner
committed
docs: canonical 9-file standards, replace legacy filenames
- Create all 9 canonical standards files (index, documentation, scripting, variables, naming, solutions, infrastructure, automation, examples) - Delete old non-standard filenames (documentation-standards.md, scripting-standards.md, variables-environment-standards.md, badge-standards.md) - Update mkdocs.yml nav to canonical 9-item block
1 parent 9ee283c commit efdeada

14 files changed

Lines changed: 640 additions & 30 deletions

‎docs/standards/automation.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
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 automation tools interoperate within the Load Testing Framework. All tools share a single configuration source and follow consistent patterns for execution, logging, and error handling.
12+
13+
---
14+
15+
## Config Flow
16+
17+
```mermaid
18+
flowchart TB
19+
A["config/variables.yml<br/>(single source of truth)"] --> B[Cluster Configs]
20+
A --> C[Workload Profiles]
21+
A --> D[Credential Templates]
22+
B --> E[Test Execution]
23+
C --> E
24+
D --> E
25+
E --> F[Results in reports/]
26+
```
27+
28+
---
29+
30+
## Tool Integration Matrix
31+
32+
| Tool | Storage Tests | Network Tests | Compute Tests | Database Tests |
33+
|------|:---:|:---:|:---:|:---:|
34+
| **VMFleet** | ✅ | — | — | — |
35+
| **fio** | ✅ | — | — | — |
36+
| **iPerf3** | — | ✅ | — | — |
37+
| **HammerDB** | — | — | — | ✅ |
38+
| **stress-ng** | — | — | ✅ | — |
39+
40+
---
41+
42+
## Interoperability Rules
43+
44+
1. **Single source of truth** — `config/variables.yml` is the base config; tool-specific configs are in subdirectories.
45+
2. **Consistent execution** — All tools launched via `Invoke-` wrapper scripts.
46+
3. **Idempotency** — All scripts must be safe to re-run.
47+
4. **Error handling** — Every tool must validate config before executing tests.
48+
5. **Logging** — All operations logged to `./logs/` with consistent format.
49+
6. **Results** — All test results stored in `reports/` with timestamped output.
50+
51+
---
52+
53+
## Variable Path Contract
54+
55+
Scripts must use variable paths that exist in the schema. See the [Variable Standards](variables.md) for naming rules and the [Variable Reference](../reference/variables.md) for the complete catalog.
56+
57+
---
58+
59+
## Related Standards
60+
61+
- [Scripting Standards](scripting.md)
62+
- [Infrastructure Standards](infrastructure.md)
63+
- [Solution Standards](solutions.md)
64+
- [Variable Standards](variables.md)

‎docs/standards/badge-standards.md‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/standards/documentation-standards.md‎

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎docs/standards/documentation.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
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-]*$` | `tools/`, `getting-started/` |
25+
| Markdown (docs/) | lowercase with hyphens | `*.md` | `workload-profiles.md` |
26+
| Root files | UPPERCASE | — | `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md` |
27+
| PowerShell scripts | PascalCase | `Verb-Noun.ps1` | `Start-VMFleetWorkload.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:
35+
36+
- **Admonitions**: `!!! note`, `!!! warning`, `!!! danger`, `!!! info`, `!!! tip`
37+
- **Code blocks**: Always include a language identifier
38+
- **Code copy**: Enabled via `content.code.copy`
39+
- **Mermaid diagrams**: Supported via `pymdownx.superfences`
40+
- **Tables**: Standard Markdown tables
41+
- **Tabs**: `=== "Tab Name"` via `pymdownx.tabbed`
42+
43+
---
44+
45+
## Badges
46+
47+
Use Shields.io Markdown badges for visual metadata at the top of documentation pages:
48+
49+
```markdown
50+
[![Label](https://img.shields.io/badge/Label-Value-color?style=flat-square&logo=icon)](URL)
51+
```
52+
53+
| Badge | Markdown |
54+
|-------|----------|
55+
| Standard | `[![Standard](https://img.shields.io/badge/Type-Standard-green?style=flat-square)](./index.md)` |
56+
| AzureLocal | `[![AzureLocal](https://img.shields.io/badge/AzureLocal-Community-0078D4?style=flat-square)](https://azurelocal.cloud)` |
57+
| PowerShell | `[![PowerShell](https://img.shields.io/badge/Language-PowerShell-blue?style=flat-square&logo=powershell)](https://docs.microsoft.com/en-us/powershell/)` |
58+
59+
**Placement rules**: 2–4 badges max per page, immediately after `# Title`, order: Type → Organization → Technology → Category, always `?style=flat-square`.
60+
61+
---
62+
63+
## Fictional Company — Infinite Improbability Corp (IIC)
64+
65+
All examples must use IIC naming patterns:
66+
67+
| Never Use | Use Instead |
68+
|-----------|-------------|
69+
| `contoso`, `fabrikam`, `northwind` | Infinite Improbability Corp |
70+
| `example.com`, `test.com` | `improbability.cloud` |
71+
| Real customer names | IIC naming patterns |
72+
73+
---
74+
75+
## Related Standards
76+
77+
- [Naming Conventions (full reference)](https://azurelocal.cloud/standards/documentation/naming-conventions)
78+
- [Badge Library (full reference)](https://azurelocal.cloud/standards/documentation/badge-library)
79+
- [Naming Conventions](naming.md)
80+
- [Scripting Standards](scripting.md)

‎docs/standards/examples.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
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, walkthroughs, and documentation across every AzureLocal repository 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+
## IIC Reference Card
20+
21+
| Attribute | Value |
22+
|-----------|-------|
23+
| **Full Name** | Infinite Improbability Corp |
24+
| **Abbreviation** | IIC |
25+
| **Domain (public)** | `improbability.cloud` / `iic.cloud` |
26+
| **Domain (on-prem AD)** | `iic.local` |
27+
| **NetBIOS Name** | `IMPROBABLE` |
28+
| **Entra ID Tenant** | `improbability.onmicrosoft.com` |
29+
| **Email Pattern** | `user@improbability.cloud` |
30+
| **Origin** | A nod to *The Hitchhiker's Guide to the Galaxy* |
31+
32+
---
33+
34+
## LoadTools Naming Patterns
35+
36+
### Azure Resources
37+
38+
| Resource | Pattern | Example |
39+
|----------|---------|---------|
40+
| Resource Group | `rg-iic-loadtools-<##>` | `rg-iic-loadtools-01` |
41+
| Key Vault | `kv-iic-<purpose>` | `kv-iic-platform` |
42+
| Storage Account | `stiic<purpose><##>` | `stiicresults01` |
43+
| Log Analytics | `law-iic-<purpose>-<##>` | `law-iic-monitor-01` |
44+
45+
### Cluster & Nodes
46+
47+
| Resource | Pattern | Example |
48+
|----------|---------|---------|
49+
| Cluster | `iic-clus<NN>` | `iic-clus01` |
50+
| Test VMs | `iic-vm<tool>-<NN>` | `iic-vmfleet-01` |
51+
52+
---
53+
54+
## Real Identities
55+
56+
These are **not** fictional — use for authorship and attribution:
57+
58+
| Name | Usage |
59+
|------|-------|
60+
| **Azure Local Cloud** | Community project, GitHub org, `azurelocal.cloud` |
61+
| **Hybrid Cloud Solutions** | Author/maintainer LLC, script headers, copyright |
62+
63+
---
64+
65+
## Usage Examples
66+
67+
### In `config/variables.example.yml`
68+
69+
```yaml
70+
azure:
71+
subscription_id: "00000000-0000-0000-0000-000000000000"
72+
resource_group: "rg-iic-loadtools-01"
73+
location: "eastus"
74+
75+
keyvault:
76+
name: "kv-iic-platform"
77+
78+
testing:
79+
cluster_name: "iic-clus01"
80+
vm_count: 64
81+
```
82+
83+
### In Documentation
84+
85+
> Infinite Improbability Corp validates storage performance on `iic-clus01` using
86+
> VMFleet with 64 test VMs across four Azure Local nodes.
87+
88+
### In Scripts
89+
90+
```powershell
91+
# Example: Start VMFleet workload on IIC cluster
92+
$clusterName = "iic-clus01"
93+
$credential = Get-Secret -Vault "kv-iic-platform" -Name "svc-iic-deploy"
94+
Invoke-VMFleetWorkload -ClusterName $clusterName -Credential $credential
95+
```
96+
97+
---
98+
99+
## Enforcement
100+
101+
- **PR review**: Reviewers flag any use of `contoso`, `fabrikam`, or other non-IIC names
102+
- **Config validation**: `variables.example.yml` uses IIC naming patterns in all placeholders
103+
- **CI**: Vale linting rules can flag non-IIC fictional company names (when configured)

‎docs/standards/index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
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 the Load Testing Framework.
8+
9+
---
10+
11+
## Standards Pages
12+
13+
| Standard | Local Page | Central Reference |
14+
|----------|-----------|------------------|
15+
| Documentation | [Documentation Standards](documentation.md) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) |
16+
| Scripting | [Scripting Standards](scripting.md) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) |
17+
| Variables | [Variable Standards](variables.md) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) |
18+
| Naming Conventions | [Naming Conventions](naming.md) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) |
19+
| Solutions | [Solution Standards](solutions.md) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) |
20+
| Infrastructure | [Infrastructure Standards](infrastructure.md) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) |
21+
| Automation | [Automation Interoperability](automation.md) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) |
22+
| Examples & IIC | [Examples & IIC](examples.md) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) |
23+
24+
---
25+
26+
## References
27+
28+
- [Variable Reference](../reference/variables.md) — Per-variable catalog for this repo
29+
- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout
30+
31+
---
32+
33+
## Repo-Specific Conventions
34+
35+
This repository follows additional conventions specific to the Load Testing Framework:
36+
37+
- **Config file**: `config/variables.example.yml` with `clusters/`, `credentials/`, `profiles/`, `variables/` subdirectories — see [Variable Reference](../reference/variables.md)
38+
- **Load tools**: VMFleet, fio, iPerf3, HammerDB, stress-ng — each has dedicated script modules
39+
- **Performance baselines**: Store in `reports/` for comparison across runs
40+
- **Fictional company**: Infinite Improbability Corp (IIC) — see [IIC Policy](examples.md)

‎docs/standards/infrastructure.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
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), state management, and deployment processes for the Load Testing Framework.
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 | `loadtools-<env>.tfstate` (e.g., `loadtools-prod.tfstate`) |
36+
37+
---
38+
39+
## LoadTools-Specific Infrastructure
40+
41+
| Convention | Rule |
42+
|-----------|------|
43+
| Primary tooling | PowerShell scripts with config-driven execution |
44+
| Config source | `config/variables.yml` with `clusters/`, `credentials/`, `profiles/` subdirectories |
45+
| VM provisioning | VMFleet VMs provisioned via PowerShell or Hyper-V cmdlets |
46+
| Network validation | iPerf3 tests validate network throughput before storage tests |
47+
48+
### Test Infrastructure Lifecycle
49+
50+
```mermaid
51+
flowchart TB
52+
A[Provision Test VMs] --> B[Configure Workload Profiles]
53+
B --> C[Run Baseline Tests]
54+
C --> D[Store Results in reports/]
55+
D --> E[Compare Against Baselines]
56+
E --> F[Teardown or Retain]
57+
```
58+
59+
---
60+
61+
## Related Standards
62+
63+
- [Infrastructure Generation & Deployment Process](https://azurelocal.cloud/standards/infrastructure/infrastructure-generation-deployment-process)
64+
- [State Management](https://azurelocal.cloud/standards/infrastructure/state-management)
65+
- [Solution Development Standard](solutions.md)
66+
- [Variable Standards](variables.md)
67+
- [Automation Interoperability](automation.md)

0 commit comments

Comments
 (0)