Terraform on Azure: Complete Guide to AzureRM/AzAPI Providers, State, Modules, and CI/CD

Terraform on Azure is the combination of HashiCorp's multi-cloud IaC tool Terraform with Azure resource management. While Bicep is an Azure-specific DSL, Terraform is multi-cloud (3,000+ Providers) with strong existing investments and an active OSS community. This article walks through Provider selection, State management, Module design, and CI/CD integration end to end.

Bicep vs Terraform: How to Choose

The modern rule of thumb: Bicep for greenfield Azure-only projects, Terraform for multi-cloud or existing Terraform projects.

AzureRM Provider and AzAPI Provider

Standard pattern: use AzureRM Provider as the base and reach for AzAPI Provider only for Preview features and newly added resources. The two can coexist inside the same Terraform project.

Managing Terraform State

Terraform State is a JSON file recording the current state of your infrastructure and is the baseline for terraform plan / apply. The default is local; in production it must be stored in a remote Backend.

Azure standard pattern

• Use an Azure Storage Account Blob Container as the Backend
• Implement State Lock (preventing concurrent updates) with Blob Lease
• Encrypt State (Customer-Managed Key)
• Use Versioning + Soft Delete to prevent accidental deletion
• Control access to State with Microsoft Entra ID authentication

Backend configuration example

terraform {
  backend "azurerm" {
    resource_group_name  = "rg-tfstate"
    storage_account_name = "stgtfstate001"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"
    use_oidc             = true
  }
}

Terraform Cloud (paid SaaS) is also available as a Backend and offers more advanced State management.

Module Design

A Terraform Module is a reusable unit of Terraform code.

Recommended directory layout

infra/
├── main.tf              # エントリポイント・Provider 設定
├── variables.tf         # 入力変数
├── outputs.tf           # 出力値
├── modules/
│   ├── network/         # VNet / NSG / Subnet
│   ├── compute/         # VM / App Service / AKS
│   ├── storage/         # Storage Account / Container
│   └── identity/        # Managed Identity / Key Vault
└── environments/
    ├── dev.tfvars
    ├── stage.tfvars
    └── prod.tfvars

Module invocation example

module "network" {
  source              = "./modules/network"
  vnet_name           = var.vnet_name
  address_space       = ["10.0.0.0/16"]
  location            = var.location
  resource_group_name = azurerm_resource_group.main.name
}

module "compute" {
  source              = "./modules/compute"
  vm_name             = var.vm_name
  subnet_id           = module.network.app_subnet_id
  resource_group_name = azurerm_resource_group.main.name
  depends_on          = [module.network]
}

Azure Verified Modules (AVM)

Azure Verified Modules (AVM, GA in 2024) are a set of Microsoft-quality-assured Terraform Modules and serve as reference implementations aligned with industry best practices.

• Officially maintained by Microsoft
• Aligned with the Well-Architected Framework
• Security baseline applied
• Published on the Terraform Registry
• A Bicep edition of AVM is also offered

In the enterprise, customizing on top of AVM is the standard approach. Modularization dramatically improves the maintainability of large-scale IaC.

Coexisting with Bicep

The two do not compete and can be used together. Typical patterns:

1. Bicep for Azure-only resources, Terraform for multi-cloud requirements (e.g. AWS RDS)
2. Bicep for greenfield development while keeping existing Terraform assets
3. Bicep / AzAPI for Microsoft's latest features (including Preview), Terraform AzureRM for stable features

CI/CD pipeline coexistence example

• Stage 1: build the Hub VNet with Bicep
• Stage 2: provision AWS resources + AKS with Terraform
• Stage 3: configure Azure SaaS with Bicep

Drift Detection

Drift Detection is the operation of detecting differences between Terraform State and the actual state of Azure resources. When resources are modified manually via the Azure Portal or CLI, State drifts and unexpected changes risk being applied during the next terraform apply.

Relevant commands

• terraform plan -refresh-only: refresh State to match current resources
• terraform apply -refresh-only: apply the diff
• terraform import: bring new resources into State

Embedding periodic Drift Detection in your CI/CD pipeline (for example weekly) makes it possible to catch manual changes early. Combining this with Azure Policy Deny Effect to prohibit manual changes outright is the standard enterprise pattern.

Integration with GitHub Actions / Azure Pipelines

Standard pattern

1. Lint: terraform fmt -check + terraform validate
2. Init: connect to the Backend
3. Plan: terraform plan -out=tfplan — predict changes
4. Manual Approval (for Production)
5. Apply: terraform apply tfplan

GitHub Actions example

name: Terraform Apply
on:
  push:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3
      - uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - run: terraform init
      - run: terraform plan -out=tfplan
      - run: terraform apply tfplan

Use OIDC / Workload Identity Federation for AzureRM Provider authentication (no secrets needed) and for Backend authentication as well. Auto-posting Plan output as a PR comment on Pull Requests is also a standard implementation.

Operational Best Practices

1. State must be stored in the Azure Storage Backend (local State is prohibited)
2. Combine State Lock + Versioning + Soft Delete against accidental deletion
3. Modularize for reusability (leverage AVM)
4. Separate configuration per environment with tfvars
5. OIDC / WIF for secret-less authentication
6. Embed Plan → Approval → Apply in the CI/CD pipeline
7. Detect manual changes with periodic Drift Detection
8. Use Azure Policy to prohibit manual changes
9. Auto-post Plan output as PR comments on Pull Requests
10. Pin Provider versions (required_version + required_providers in terraform.tf)

Related Certifications

• AZ-400 (DevOps Engineer Expert): the flagship certification for this area — covered deeply in Domain 3
• AZ-104 (Administrator): IaC fundamentals
• AZ-305 (Solutions Architect Expert): IaC strategy selection from an architect's viewpoint
• Outside Microsoft: HashiCorp Certified: Terraform Associate (vendor-neutral)

Frequently Asked Questions

The technical content in this article is based on the AzureRM Provider Documentation and the Microsoft Terraform on Azure Documentation. This article is not an official Microsoft Corporation product and has no affiliation or sponsorship relationship with Microsoft. Microsoft and Azure are trademarks of the Microsoft group of companies. Terraform is a trademark of HashiCorp. Information reflects official public materials as of May 24, 2026. Always check the official pages for the latest information.