Platform Automation and IaC

The platform is a product, and a product is built from source. If the management groups, policies, and platform subscriptions only exist as a series of portal clicks, then nobody can review a change, reproduce the environment, or trust that what is documented matches what is deployed.

Purpose

This page defines the Infrastructure as Code strategy for the Azure platform: tool choice, repository structure, deployment scopes, and accelerator options.

Design Reasoning

For a new platform implementation, Microsoft’s recommended direction is to use Azure Verified Modules (AVM) together with the Azure Landing Zones IaC accelerator, in either Bicep or Terraform.

The tool choice is real but secondary:

• Bicep is a strong choice for Azure-first teams. It integrates directly with Azure Resource Manager, supports clean scope-based deployments, and the AVM-based ALZ approach uses Azure Deployment Stacks for lifecycle management.
• Terraform is a strong choice for organizations already standardized on Terraform, needing a broader multi-cloud workflow, or with established HCL pipelines.

The decision that actually matters is not Bicep versus Terraform. It is that the platform is deployed, reviewed, and operated as code — through pull requests and pipelines, not the portal.

Architecture Decision Record

Tradeoff: Adopting AVM and the accelerator means learning their conventions instead of writing everything from scratch. That up-front learning buys tested modules, a maintained upgrade path, and far less custom code to own.

Recommended Configuration

A repository structure that separates platform from workload and groups code by deployment scope:

1
platform-foundation/
2
  docs/
3
  infra/
4
    management-groups/
5
    policies/
6
    role-assignments/
7
    platform/
8
      management/
9
      connectivity/
10
      identity/
11
  pipelines/
12
  environments/
13
    prod/
14
    nonprod/

For Bicep, separate deployments by scope:

• Tenant scope where required
• Management group scope for hierarchy, policies, and RBAC
• Subscription scope for platform subscription resources
• Resource group scope for specific services

For Terraform, separate state by scope or platform capability to reduce blast radius and support least-privilege pipeline identities.

Give each pipeline identity (a workload identity / service principal with federated credentials) the least privilege for its scope — the policies pipeline does not need workload Contributor, and the workload pipeline does not need management-group rights.

Example Implementation

A management-group-scoped Bicep deployment:

1
az deployment mg create \
2
  --management-group-id contoso \
3
  --name platform-baseline \
4
  --location switzerlandnorth \
5
  --template-file ./infra/management-groups/main.bicep

A minimal Terraform provider baseline:

1
terraform {
2
  required_version = ">= 1.6.0"
3
}
4

5
provider "azurerm" {
6
  features {}
7
}

Validation Steps

Always preview changes before applying them. For Bicep, validate and run a what-if:

1
az deployment mg validate \
2
  --management-group-id contoso \
3
  --location switzerlandnorth \
4
  --template-file ./infra/management-groups/main.bicep
5

6
az deployment mg what-if \
7
  --management-group-id contoso \
8
  --location switzerlandnorth \
9
  --template-file ./infra/management-groups/main.bicep

For Terraform:

1
terraform fmt -check
2
terraform validate
3
terraform plan

The what-if / plan output is a required review gate, not a formality — it is how reviewers see the blast radius before a change reaches the tenant.

Common Mistakes

• Using the portal accelerator as the long-term operating model instead of the IaC accelerator.
• Making manual portal changes after IaC is introduced, which causes drift between code and reality.
• Mixing too many scopes into one deployment, which enlarges blast radius and complicates least privilege.
• Giving pipelines overly broad permissions.
• Not separating platform and workload code.
• Skipping pull requests and review gates for platform changes.

References

• Platform landing zone implementation options
• Azure Verified Modules
• Comparing Terraform and Bicep
• Deploy Bicep files to management group scope
• Azure Landing Zones Bicep repository
• Azure Landing Zones Terraform (AVM pattern module)