Upgrade Strategy

Versioning

• Treat module changes as semantic versioned releases
• Promote changes from dev -> staging -> prod
• Pin provider versions to tested ranges in each root stack
• Document breaking changes in DECISIONS.md

Backwards Compatibility

• All new variables must have explicit defaults to avoid breaking existing deployments
• Module output removals or renames are breaking changes and require migration guides
• No silent breaking changes — every interface change must be documented

Upgrade Process

1. Validate formatting and static checks (./scripts/validate.sh).
2. Apply to envs/dev and verify service health and connectivity.
3. Apply to envs/staging and run regression checks.
4. Apply to envs/prod during approved maintenance window.

Rollback Stance

• Prefer forward-fixes where possible
• If rollback is required, revert Terraform code and re-apply
• For state-sensitive resources (databases, OpenAI deployments), review destructive diffs before apply

Tier Progression

When upgrading from one maturity tier to the next:

• Foundation -> Enterprise: Enable policy baseline, diagnostics, managed identity role assignments
• Enterprise -> Regulated: Enable CMK, private AKS, add APIM, firewall, and egress controls

Each tier extension adds modules to the root stack composition. Existing modules are not modified.