From 6ea2bbf0a41d34c5799d8c438f24e467c6e3979b Mon Sep 17 00:00:00 2001 From: Kristopher Turner Date: Sun, 12 Apr 2026 23:36:25 +0000 Subject: [PATCH] chore(standards): replace local standards/ with stub pointing to AzureLocal/platform Phase 1 of the platform rollout (ADR-0002). Deletes the local copies of org-wide standards docs and replaces them with a STANDARDS.md stub linking to the canonical source in AzureLocal/platform/standards/. The previous .md files were duplicates of azurelocal.github.io/standards/ that had drifted. The canonical copies now live (and are authored) in AzureLocal/platform; this repo consumes them by reference. Co-Authored-By: Claude Opus 4.6 (1M context) --- STANDARDS.md | 9 ++++ standards/automation.md | 69 ------------------------ standards/documentation.md | 75 -------------------------- standards/examples.md | 103 ------------------------------------ standards/index.md | 37 ------------- standards/infrastructure.md | 69 ------------------------ standards/naming.md | 64 ---------------------- standards/scripting.md | 89 ------------------------------- standards/solutions.md | 69 ------------------------ standards/variables.md | 65 ----------------------- 10 files changed, 9 insertions(+), 640 deletions(-) create mode 100644 STANDARDS.md delete mode 100644 standards/automation.md delete mode 100644 standards/documentation.md delete mode 100644 standards/examples.md delete mode 100644 standards/index.md delete mode 100644 standards/infrastructure.md delete mode 100644 standards/naming.md delete mode 100644 standards/scripting.md delete mode 100644 standards/solutions.md delete mode 100644 standards/variables.md diff --git a/STANDARDS.md b/STANDARDS.md new file mode 100644 index 0000000..a782ed2 --- /dev/null +++ b/STANDARDS.md @@ -0,0 +1,9 @@ +# Standards + +AzureLocal organization standards are maintained centrally in the [`AzureLocal/platform`](https://github.com/AzureLocal/platform) repository. This repo does **not** keep a local copy. + +- **Canonical source**: [`AzureLocal/platform/standards/`](https://github.com/AzureLocal/platform/tree/main/standards) +- **Rendered for humans**: [azurelocal.cloud/standards](https://azurelocal.cloud/standards/) +- **Governance**: [ADR-0002 — Standards as single source of truth](https://github.com/AzureLocal/platform/blob/main/decisions/0002-standards-single-source.md) + +Changes to any standard are PRs against `AzureLocal/platform`, not against this repo. diff --git a/standards/automation.md b/standards/automation.md deleted file mode 100644 index 1f86c36..0000000 --- a/standards/automation.md +++ /dev/null @@ -1,69 +0,0 @@ -# Automation Interoperability - -> **Canonical reference:** [Scripting Framework (full)](https://azurelocal.cloud/standards/scripting/scripting-framework) -> **Applies to:** All AzureLocal repositories -> **Last Updated:** 2026-03-17 - ---- - -## Overview - -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. - ---- - -## Config Flow - -```mermaid -flowchart TB - A["config/variables.yml
(single source of truth)"] --> B[Terraform .tfvars] - A --> C[Bicep .bicepparam] - A --> D[ARM parameters.json] - A --> E[PowerShell ConvertFrom-Yaml] - A --> F[Ansible group_vars] - B --> G[Identical Infrastructure] - C --> G - D --> G - E --> G - F --> G -``` - ---- - -## Deployment Path Matrix - -| Tool | Azure Resources | Configuration | Monitoring | Scaling | -|------|:---:|:---:|:---:|:---:| -| **Terraform** | ✅ | Delegates | ✅ | ✅ | -| **Bicep** | ✅ | Delegates | ✅ | ✅ | -| **ARM** | ✅ | Delegates | ✅ | — | -| **PowerShell** | ✅ | ✅ | ✅ | ✅ | -| **Ansible** | ✅ | ✅ | ✅ | ✅ | - -!!! warning "Delegates" - "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. - ---- - -## Interoperability Rules - -1. **Single source of truth** — `config/variables.yml` is the only config file. All tool-specific parameter files are derived. -2. **Identical output** — Given the same config, every tool must produce the same infrastructure. -3. **Idempotency** — All scripts and templates must be safe to re-run. -4. **Error handling** — Every tool must validate config before executing changes. -5. **Logging** — All operations logged to `./logs/` with consistent format. - ---- - -## Variable Path Contract - -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. - ---- - -## Related Standards - -- [Scripting Standards](scripting.md) -- [Infrastructure Standards](infrastructure.md) -- [Solution Standards](solutions.md) -- [Variable Standards](variables.md) \ No newline at end of file diff --git a/standards/documentation.md b/standards/documentation.md deleted file mode 100644 index 902cb64..0000000 --- a/standards/documentation.md +++ /dev/null @@ -1,75 +0,0 @@ -# Documentation Standards - -> **Canonical reference:** [Documentation Standards (full)](https://azurelocal.cloud/standards/documentation/documentation-standards) -> **Applies to:** All AzureLocal repositories -> **Last Updated:** 2026-03-17 - ---- - -## Principles - -| Principle | Rule | -|-----------|------| -| Documentation-First | Document **before** implementing. Keep docs current with code. | -| Single Source of Truth | One authoritative document per topic. Cross-reference, don't duplicate. | -| Audience-Aware | Write for operators, developers, or executives — with appropriate depth. | -| Actionable | Step-by-step procedures, examples, prerequisites, and outcomes. | - ---- - -## File Naming - -| Type | Convention | Pattern | Example | -|------|-----------|---------|---------| -| Directories | lowercase-with-hyphens | `^[a-z][a-z0-9-]*$` | `guides/`, `reference/` | -| Markdown (docs/) | lowercase with hyphens | `*.md` | `deployment-guide.md` | -| Root files | UPPERCASE | — | `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md` | -| PowerShell scripts | PascalCase | `Verb-Noun.ps1` | `Deploy-Solution.ps1` | -| Config files | lowercase-with-hyphens | — | `variables.example.yml` | - ---- - -## MkDocs Material Conventions - -This repo uses **MkDocs Material** with the following conventions: - -- **Admonitions**: Use `!!! note`, `!!! warning`, `!!! danger`, `!!! info`, `!!! tip` -- **Code blocks**: Always include a language identifier (e.g., ` ```powershell `, ` ```yaml `) -- **Code copy**: Enabled via `content.code.copy` -- **Mermaid diagrams**: Supported via `pymdownx.superfences` custom fence -- **Tables**: Use standard Markdown tables -- **Tabs**: Use `=== "Tab Name"` via `pymdownx.tabbed` - ---- - -## Frontmatter & Metadata - -Every documentation page should include: - -```markdown -# Page Title - -> Brief one-line description of the page's purpose. - ---- -``` - ---- - -## Fictional Company — Contoso (IIC) - -All examples must use IIC. See the [Examples & IIC Policy](examples.md) page for the full reference card. - -| Never Use | Use Instead | -|-----------|-------------| -| `contoso`, `fabrikam`, `northwind` | Contoso | -| `example.com`, `test.com` | `contoso.cloud` | -| Real customer names | IIC naming patterns | - ---- - -## Related Standards - -- [Naming Conventions (full reference)](https://azurelocal.cloud/standards/documentation/naming-conventions) -- [Badge Library](https://azurelocal.cloud/standards/documentation/badge-library) -- [Scripting Standards](scripting.md) \ No newline at end of file diff --git a/standards/examples.md b/standards/examples.md deleted file mode 100644 index 89bd54c..0000000 --- a/standards/examples.md +++ /dev/null @@ -1,103 +0,0 @@ -# Examples & IIC Policy - -> **Canonical reference:** [Fictional Company Policy (full)](https://azurelocal.cloud/standards/fictional-company-policy) -> **Applies to:** All AzureLocal repositories -> **Last Updated:** 2026-03-17 - ---- - -## Policy - -All examples, sample configurations, and walkthroughs use **one** fictional company: **Contoso (IIC)**. - -!!! warning "Mandatory" - Never use `contoso`, `fabrikam`, `adventure-works`, `woodgrove`, `example.com`, or any real customer name. - **IIC only** — in every repo, every example, every sample config. - ---- - -## IIC Reference Card - -| Attribute | Value | -|-----------|-------| -| **Full Name** | Contoso | -| **Abbreviation** | IIC | -| **Domain (public)** | `contoso.cloud` / `iic.cloud` | -| **Domain (on-prem AD)** | `contoso.local` | -| **NetBIOS Name** | `IMPROBABLE` | -| **Entra ID Tenant** | `improbability.onmicrosoft.com` | -| **Email Pattern** | `user@contoso.cloud` | - ---- - -## AzureLocal Naming Patterns - -### Azure Resources - -| Resource | Pattern | Example | -|----------|---------|---------| -| Resource Group | `rg-iic--<##>` | `rg-iic-platform-01` | -| Virtual Network | `vnet-iic--<##>` | `vnet-iic-compute-01` | -| Subnet | `snet-iic-` | `snet-iic-management` | -| Network Security Group | `nsg-iic-` | `nsg-iic-compute` | -| Key Vault | `kv-iic-` | `kv-iic-platform` | -| Storage Account | `stiic<##>` | `stiicdata01` | -| Log Analytics | `law-iic--<##>` | `law-iic-monitor-01` | -| Managed Identity | `id-iic-` | `id-iic-deploy` | - -### Active Directory - -| Resource | Pattern | Example | -|----------|---------|---------| -| OU path | `OU=,OU=Servers,DC=iic,DC=local` | — | -| Service account | `svc.iic.` | `svc.iic.deploy` | -| Group | `grp-iic-` | `grp-iic-admins` | - -### IP Addresses - -| Network | Range | Usage | -|---------|-------|-------| -| Management | `10.0.0.0/24` | Node management | -| Compute | `10.0.2.0/24` | Workload traffic | - ---- - -## Real Identities - -| Name | Usage | -|------|-------| -| **Azure Local Cloud** | Community project, GitHub org, `azurelocal.cloud` | -| **Hybrid Cloud Solutions** | Author/maintainer LLC, script headers, copyright | - ---- - -## Usage Examples - -### In `config/variables.example.yml` - -```yaml -subscription: - subscription_id: "00000000-0000-0000-0000-000000000000" - tenant_id: "00000000-0000-0000-0000-000000000000" - location: "eastus" - -security: - keyvault_name: "kv-iic-platform" - -azure_local: - resource_group: "rg-iic-platform-01" - cluster_name: "azlocal-iic-01" -``` - -### In Documentation - -> Contoso deploys Azure Local clusters using IIC naming patterns, -> with all configuration driven from a single `config/variables.yml` file. - ---- - -## Enforcement - -- **PR review**: Reviewers flag any use of `contoso`, `fabrikam`, or other non-IIC names -- **Config validation**: `variables.example.yml` uses IIC naming in all placeholders -- **CI**: Vale linting rules flag non-IIC fictional company names (when configured) \ No newline at end of file diff --git a/standards/index.md b/standards/index.md deleted file mode 100644 index 58c0a57..0000000 --- a/standards/index.md +++ /dev/null @@ -1,37 +0,0 @@ -# Standards - -This repository follows the **org-wide AzureLocal standards** maintained on the central documentation site. - -!!! info "Central Standards" - The full standards suite is at [azurelocal.cloud/standards](https://azurelocal.cloud/standards/). - This section provides the key rules adapted for this solution. - ---- - -## Standards Pages - -| Standard | Local Page | Central Reference | -|----------|-----------|------------------| -| Documentation | [Documentation Standards](documentation.md) | [Full Reference](https://azurelocal.cloud/standards/documentation/documentation-standards) | -| Scripting | [Scripting Standards](scripting.md) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-standards) | -| Variables | [Variable Standards](variables.md) | [Full Reference](https://azurelocal.cloud/standards/variable-management/) | -| Naming Conventions | [Naming Conventions](naming.md) | [Full Reference](https://azurelocal.cloud/standards/documentation/naming-conventions) | -| Solutions | [Solution Standards](solutions.md) | [Full Reference](https://azurelocal.cloud/standards/solutions/solution-development-standard) | -| Infrastructure | [Infrastructure Standards](infrastructure.md) | [Full Reference](https://azurelocal.cloud/standards/infrastructure/) | -| Automation | [Automation Interoperability](automation.md) | [Full Reference](https://azurelocal.cloud/standards/scripting/scripting-framework) | -| Examples & IIC | [Examples & IIC](examples.md) | [Full Reference](https://azurelocal.cloud/standards/fictional-company-policy) | - ---- - -## References - -- [Variable Reference](../reference/variables.md) — Per-variable catalog for this repo -- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) — Required file layout - ---- - -## Repo-Specific Conventions - -- **IaC tooling**: Terraform, Bicep, ARM, PowerShell, Ansible -- **Config file**: `config/variables.example.yml` — see [Variable Reference](../reference/variables.md) -- **Fictional company**: Contoso (IIC) — see [IIC Policy](examples.md) \ No newline at end of file diff --git a/standards/infrastructure.md b/standards/infrastructure.md deleted file mode 100644 index 54b75f8..0000000 --- a/standards/infrastructure.md +++ /dev/null @@ -1,69 +0,0 @@ -# Infrastructure Standards - -> **Canonical reference:** [Infrastructure Standards (full)](https://azurelocal.cloud/standards/infrastructure/) -> **Applies to:** All AzureLocal repositories -> **Last Updated:** 2026-03-17 - ---- - -## Overview - -Standards for Infrastructure as Code (IaC), Terraform state management, and deployment processes for AzureLocal solutions. - ---- - -## Infrastructure Pipeline - -```mermaid -flowchart LR - A[Generate Variables] --> B[Validate Config] - B --> C[Plan Infrastructure] - C --> D[Review Changes] - D --> E[Apply Changes] - E --> F[Update State] -``` - ---- - -## State Management - -| Principle | Rule | -|-----------|------| -| Remote state | Store Terraform state in Azure Storage Account | -| State locking | Enable locking during all operations | -| Backup | Regular state file backups before destructive operations | -| Naming | `-.tfstate` (e.g., `platform-prod.tfstate`) | - ---- - -## IaC Tool Parity - -All tools must produce **identical infrastructure** when given the same configuration values: - -| Tool | Primary Format | State Management | -|------|---------------|-----------------| -| Terraform | `.tf` / `.tfvars` | Remote state in Azure Storage | -| Bicep | `.bicep` / `.bicepparam` | ARM deployment history | -| ARM | `.json` | ARM deployment history | -| PowerShell | `.ps1` | Config-driven, logged | -| Ansible | `.yml` | Inventory-based | - ---- - -## Deployment Phases - -| Phase | Scope | Tools | -|-------|-------|-------| -| Phase 1: Azure Foundation | Resource groups, networking, Key Vault, storage | Terraform, Bicep, ARM | -| Phase 2: Compute & Workload | VMs, clusters, workload deployment | Terraform, PowerShell | -| Phase 3: Configuration | Guest config, monitoring, policies | PowerShell, Ansible | - ---- - -## Related Standards - -- [Infrastructure Generation & Deployment Process](https://azurelocal.cloud/standards/infrastructure/infrastructure-generation-deployment-process) -- [State Management](https://azurelocal.cloud/standards/infrastructure/state-management) -- [Solution Development Standard](solutions.md) -- [Variable Standards](variables.md) -- [Automation Interoperability](automation.md) \ No newline at end of file diff --git a/standards/naming.md b/standards/naming.md deleted file mode 100644 index f872cb0..0000000 --- a/standards/naming.md +++ /dev/null @@ -1,64 +0,0 @@ -# Naming Conventions - -> **Canonical reference:** [Naming Conventions (full)](https://azurelocal.cloud/standards/documentation/naming-conventions) -> **Applies to:** All AzureLocal repositories -> **Last Updated:** 2026-03-17 - ---- - -## File & Directory Naming - -| Type | Convention | Pattern | Example | -|------|-----------|---------|---------| -| Directories | lowercase-with-hyphens | `^[a-z][a-z0-9-]*$` | `getting-started/` | -| Markdown (docs/) | lowercase with hyphens | `*.md` | `deployment-guide.md` | -| Root files | UPPERCASE | — | `README.md`, `CHANGELOG.md` | -| PowerShell scripts | PascalCase | `Verb-Noun.ps1` | `Deploy-Solution.ps1` | -| Config files | lowercase-with-hyphens | — | `variables.example.yml` | - ---- - -## Azure Resource Naming - -All resources follow the [IIC naming patterns](examples.md): - -| Resource Type | Pattern | Example | -|--------------|---------|---------| -| Resource Group | `rg-iic--<##>` | `rg-iic-platform-01` | -| Virtual Network | `vnet-iic--<##>` | `vnet-iic-compute-01` | -| Network Security Group | `nsg-iic-` | `nsg-iic-compute` | -| Key Vault | `kv-iic-` | `kv-iic-platform` | -| Storage Account | `stiic<##>` | `stiicdata01` | -| Log Analytics | `law-iic--<##>` | `law-iic-monitor-01` | - ---- - -## Variable Naming - -| Rule | Standard | Example | -|------|----------|---------| -| YAML sections | `snake_case` | `azure_local`, `networking` | -| YAML keys | `snake_case` | `subscription_id`, `resource_name` | -| Pattern | `^[a-z][a-z0-9_]*$` | — | -| Max length | 50 characters | — | - ---- - -## Git Branch Naming - -| Pattern | Usage | Example | -|---------|-------|---------| -| `main` | Default branch | — | -| `feature/` | New features | `feature/add-validation` | -| `fix/` | Bug fixes | `fix/config-parsing` | -| `docs/` | Documentation | `docs/deployment-guide` | -| `infra/` | CI/CD | `infra/add-pester-tests` | - ---- - -## Related Standards - -- [Full Naming Conventions](https://azurelocal.cloud/standards/documentation/naming-conventions) -- [Repository Structure](https://azurelocal.cloud/standards/repo-structure) -- [Documentation Standards](documentation.md) -- [Examples & IIC](examples.md) \ No newline at end of file diff --git a/standards/scripting.md b/standards/scripting.md deleted file mode 100644 index 0a1801f..0000000 --- a/standards/scripting.md +++ /dev/null @@ -1,89 +0,0 @@ -# Scripting Standards - -> **Canonical reference:** [Scripting Standards (full)](https://azurelocal.cloud/standards/scripting/scripting-standards) -> **Applies to:** All AzureLocal repositories -> **Last Updated:** 2026-03-17 - ---- - -## Script Naming - -| Script Type | Pattern | Example | -|-------------|---------|---------| -| PowerShell Core | `Verb-Noun.ps1` | `Deploy-Solution.ps1` | -| Azure PowerShell | `Verb-AzResource.ps1` | `New-AzKeyVault.ps1` | -| Azure CLI (PowerShell) | `az-verb-resource.ps1` | `az-deploy-resource.ps1` | -| Azure CLI (Bash) | `az-verb-resource.sh` | `az-deploy-resource.sh` | -| Standalone (no config) | `Verb-Noun-Standalone.ps1` | `Deploy-Solution-Standalone.ps1` | -| Remote/orchestration | `Invoke-.ps1` | `Invoke-Deployment.ps1` | - ---- - -## Config-Driven vs Standalone - -| Mode | Config File | Dependencies | Use Case | -|------|-------------|-------------|----------| -| Config-driven (Options 2-4) | `config/variables.yml` | Config loader, helpers, Key Vault | Multi-environment automation, CI/CD | -| Standalone (Option 5) | Inline `#region CONFIGURATION` | None | Demos, single-use, external sharing | - -### Config-Driven Rules - -- Read all values from `config/variables.yml` — never hardcode -- Accept `-ConfigPath` parameter (auto-discover if not provided) -- Use helper functions: `ConvertFrom-Yaml`, `Resolve-KeyVaultRef`, logging - -### Standalone Rules - -- All variables in `#region CONFIGURATION` block at top -- Variable names match `variables.yml` paths (e.g., `$subscription_id`) -- Zero external dependencies — copy, paste, run - ---- - -## `Invoke-` Script Requirements - -### Required Parameters - -| Parameter | Type | Default | Purpose | -|-----------|------|---------|---------| -| `-ConfigPath` | `[string]` | `""` | Path to `variables.yml` | -| `-Credential` | `[PSCredential]` | `$null` | Override credential resolution | -| `-TargetNode` | `[string[]]` | `@()` (all) | Limit to specific node(s) | -| `-WhatIf` | `[switch]` | `$false` | Dry-run mode | -| `-LogPath` | `[string]` | `""` (auto) | Override log file path | - -All `Invoke-` scripts must use `[CmdletBinding()]` to enable `-Verbose` and `-Debug`. - -### Credential Resolution Order - -1. **`-Credential` parameter** — if passed, use immediately -2. **Key Vault** — read from config; try `Az.KeyVault`, fall back to `az` CLI -3. **Interactive prompt** — `Get-Credential` with username pre-filled - ---- - -## Logging - -- Log to `./logs//.log` -- Use `Write-Verbose` for detailed output -- Log format: `[YYYY-MM-DD HH:MM:SS] [LEVEL] Message` - ---- - -## Solution Script Conventions - -| Convention | Rule | -|-----------|------| -| IaC tools | Terraform, Bicep, ARM, PowerShell, Ansible | -| Config source | `config/variables.yml` (single source of truth) | -| Parameter derivation | All tool-specific param files derived from central config | -| Idempotency | All scripts must be safe to re-run | - ---- - -## Related Standards - -- [PowerShell Organization Standard](https://azurelocal.cloud/standards/scripting/powershell-organization-standard) -- [Scripting Framework](https://azurelocal.cloud/standards/scripting/scripting-framework) -- [Bash Scripting Standards](https://azurelocal.cloud/standards/scripting/bash-scripting-standards) -- [Automation Interoperability](automation.md) \ No newline at end of file diff --git a/standards/solutions.md b/standards/solutions.md deleted file mode 100644 index 6428aba..0000000 --- a/standards/solutions.md +++ /dev/null @@ -1,69 +0,0 @@ -# Solution Development Standards - -> **Canonical reference:** [Solution Development Standard (full)](https://azurelocal.cloud/standards/solutions/solution-development-standard) -> **Applies to:** All AzureLocal solution repositories -> **Last Updated:** 2026-03-17 - ---- - -## IaC Tool Support - -Each tool must declare which deployment phases it supports: - -| Tool | Azure Resources | Configuration | Networking | Monitoring | -|------|:---:|:---:|:---:|:---:| -| **Terraform** | ✅ | Delegates | ✅ | ✅ | -| **Bicep** | ✅ | Delegates | ✅ | ✅ | -| **ARM** | ✅ | Delegates | ✅ | ✅ | -| **PowerShell** | ✅ | ✅ | ✅ | ✅ | -| **Ansible** | ✅ | ✅ | ✅ | ✅ | - -!!! warning "Delegates" - "Delegates" means the tool provisions Azure resources but does not configure the guest OS. A separate tool (PowerShell or Ansible) handles guest configuration. - ---- - -## Parameter File Derivation - -All tool-specific parameter files MUST be derivable from `config/variables.yml`: - -| Tool | Parameter File | Derivation | -|------|---------------|------------| -| Terraform | `src/terraform/terraform.tfvars` | Map YAML sections to HCL variables | -| Bicep | `src/bicep/main.bicepparam` | Map YAML sections to Bicep parameters | -| ARM | `src/arm/azuredeploy.parameters.json` | Map YAML sections to ARM parameter schema | -| PowerShell | *(reads config directly)* | `ConvertFrom-Yaml` from config file | -| Ansible | `common/ansible/inventory/hosts.yml` | Map YAML sections to `group_vars` | - -The central config is the **single source of truth**. Tool-specific files are convenience copies that should be regenerable. - ---- - -## Conditional Resource Support - -| Tool | Mechanism | Example | -|------|-----------|--------| -| **Terraform** | `count` / `for_each` | `count = var.enable_feature ? 1 : 0` | -| **Bicep** | `if` condition | `resource res '...' = if (enableFeature) { ... }` | -| **ARM** | `condition` property | `"condition": "[equals(parameters('enableFeature'), 'true')]"` | -| **PowerShell** | `switch` / `if` | `if ($config.feature_enabled) { ... }` | -| **Ansible** | `when:` clause | `when: enable_feature == true` | - -All tools must produce **identical infrastructure** when given the same configuration values. - ---- - -## Multi-Tool Parity - -- Every supported tool must cover the same set of resources -- Tool-specific parameter files are derived from `config/variables.yml` -- CI tests validate that each tool's output matches the expected state -- New resources added to one tool must be added to all supported tools - ---- - -## Related Standards - -- [Infrastructure Standards](https://azurelocal.cloud/standards/infrastructure/) -- [Variable Reference](../reference/variables.md) -- [Scripting Standards](scripting.md) \ No newline at end of file diff --git a/standards/variables.md b/standards/variables.md deleted file mode 100644 index 0cdf6f6..0000000 --- a/standards/variables.md +++ /dev/null @@ -1,65 +0,0 @@ -# Variable Standards - -> **Canonical reference:** [Variable Management Standard](https://azurelocal.cloud/standards/variable-management/) -> **Full variable catalog:** [Variable Reference](../reference/variables.md) -> **Last Updated:** 2026-03-17 - ---- - -## Overview - -This repository uses a **single central configuration file** — `config/variables.yml` — as the source of truth for all deployment automation. Copy from `config/variables.example.yml` to get started. - ---- - -## Naming Rules - -| Rule | Standard | Example | -|------|----------|--------| -| Top-level sections | `snake_case` | `azure_local`, `networking` | -| Keys within sections | `snake_case` | `subscription_id`, `resource_name` | -| Pattern | `^[a-z][a-z0-9_]*$` | — | -| Max length | 50 characters | — | -| Booleans | Descriptive names | `monitoring_enabled: true` | -| Secrets | `keyvault://` URI format | `keyvault://kv-iic-platform/admin-password` | - ---- - -## Config File Structure - -``` -config/ -├── variables.example.yml # Template with IIC examples (committed) -├── variables.yml # Your actual config (gitignored) -└── schema/ - └── variables.schema.json # JSON Schema for CI validation -``` - ---- - -## Key Vault Resolution - -Secrets are never stored in plaintext: - -```yaml -security: - admin_password: "keyvault://kv-iic-platform/admin-password" - domain_join_password: "keyvault://kv-iic-platform/domain-join" -``` - ---- - -## CI Validation - -Every PR validates `config/variables.example.yml` against `config/schema/variables.schema.json` using the `validate-config.yml` workflow. - ---- - -## Detailed Reference - -For the complete variable catalog see: - -- **[Variable Reference](../reference/variables.md)** — per-variable documentation -- **[Variable Management Standard](https://azurelocal.cloud/docs/implementation/04-variable-management-standard)** — org-wide governance -- **[Variable Management Suite](https://azurelocal.cloud/standards/variable-management/)** — registry, schema validation, workflows -- Tool-specific parameter mapping \ No newline at end of file