Standard: IaC Tool Maturity Lifecycle — status tracking, warnings, and release gates

[kristopherjturner]

IaC Tool Maturity Lifecycle Standard

Problem

We have multiple IaC tools across multiple repos (Terraform, Bicep, ARM, PowerShell, Ansible) at varying levels of maturity — some tested, some untested, some partially working. There is no formal standard for:

• What lifecycle stage each tool is in
• What criteria must be met before a tool can be called "released"
• How to communicate tool status to users (warnings, badges, banners)
• Preventing untested tools from being presented as production-ready

Users following our docs could pick an untested tool path and hit a wall with no warning.

Proposal

1. Define Lifecycle Stages

Stage	Label	Meaning	User Warning
Draft	🔴 Draft	Scaffolded / placeholder — not functional	⛔ "This tool is not yet functional. Do not use."
Alpha	🟠 Alpha	Partially implemented — major gaps, may break	⚠️ "Alpha: Incomplete and untested. Use at your own risk."
Beta	🟡 Beta	Feature-complete but not fully tested in production	⚠️ "Beta: Not yet validated in production. Report issues."
Release Candidate	🔵 RC	Fully tested, pending final sign-off	ℹ️ "Release Candidate: Validated but awaiting final approval."
Released	🟢 Released	Fully tested, validated, production-ready	✅ No warning needed
Deprecated	⚫ Deprecated	Being phased out	⚠️ "Deprecated: Will be removed in a future release."

2. Release Gate Criteria

A tool cannot advance to Released unless ALL of these are met:

• End-to-end deployment succeeds against a real Azure Local environment
• Idempotent re-run succeeds (deploy twice, no errors or drift)
• Destroy/cleanup succeeds cleanly
• All resources match variables.example.yml configuration
• Passes automated validation checks (lint, format, schema)
• Peer-reviewed by at least 1 other contributor
• Documentation is complete (deployment guide, variables reference, troubleshooting)
• CI/CD pipeline exists and passes

3. Status Display in Documentation

Every tool-specific doc page must include a status badge/banner at the top:

> [!WARNING]
> **Tool Status: 🟠 Alpha** — This Terraform module is partially implemented and has not been tested
> against a production Azure Local environment. Do not use for production deployments.
> See [Tool Maturity Standard](https://azurelocal.cloud/standards/tool-maturity/) for details.

4. Status Tracking Matrix (per repo)

Each repo must maintain a tool status table in its README.md or docs/index.md:

| Tool | Status | Last Tested | Tested By | Notes |
|------|--------|-------------|-----------|-------|
| PowerShell | 🟡 Beta | 2026-03-01 | @kristopherjturner | End-to-end on TPLabs |
| Terraform | 🟠 Alpha | — | — | Azure resources only, no guest config |
| Bicep | 🟠 Alpha | — | — | Compiles, not deployed |
| ARM | 🔴 Draft | — | — | Auto-generated from Bicep |
| Ansible | 🔴 Draft | — | — | Roles scaffolded, not tested |

5. Standards Document

Create a standards document (docs/standards/tool-maturity.md or equivalent) that:

• Defines the lifecycle stages and their criteria
• Specifies the warning banner format
• Specifies the status table format
• Documents the release gate checklist
• Is replicated to each repo (or linked from the central docs site)

Scope

This standard applies to ALL repos in the AzureLocal org:

• azurelocal-avd — Terraform, Bicep, ARM, PowerShell, Ansible
• azurelocal-sofs-fslogix — Terraform, Bicep, ARM, PowerShell, Ansible
• azurelocal-toolkit — PowerShell, Bicep
• azurelocal-loadtools — PowerShell
• azurelocal-vm-conversion-toolkit — PowerShell

Acceptance Criteria

• Standards document written and published to azurelocal.cloud docs site
• Standards document replicated to each repo (or linked — per issue Create standards replication mechanism from docs site to all repos #6)
• Every repo has a tool status table in README/index
• Every tool-specific doc page has a status banner
• CI check (optional, future) that validates status banners exist
• No tool is labeled "Released" without passing all gate criteria

Related

• Track IaC tool maturity status across all repos (Built / Tested / Released) #5 — Track IaC tool maturity status across all repos (tracking matrix)
• Create standards replication mechanism from docs site to all repos #6 — Standards replication mechanism from docs site to repos

[kristopherjturner]

Related to #16 (TKT-6) — Research: Azure Deployment Stacks for ARM/Bicep Deployments. Implementation of this issue should account for deployment stack adoption across all repos.

[kristopherjturner]

Tracked in Azure DevOps: https://dev.azure.com/hybridcloudsolutions/Azure%20Local%20Toolkit/_workitems/edit/194