Skip to main content

Getting Started — Azure

Everything you need before using any module from terraform-az-modules: installation, authentication, provider config, remote state, and the variable conventions shared by every module.

Prerequisites​

ToolMinimum versionInstall
Terraform1.6.6developer.hashicorp.com/terraform/install
Azure CLIany recentlearn.microsoft.com
azurerm provider3.90.0declared in required_providers

Authentication​

Local development — Azure CLI​

The quickest option for local work:

az login
az account set --subscription "<subscription-id>"

Terraform picks up CLI credentials automatically.

CI/CD — Service Principal​

Create a service principal with Contributor rights on your subscription:

az ad sp create-for-rbac \
  --name "terraform-sp" \
  --role Contributor \
  --scopes /subscriptions/<subscription-id>

Export the output values before running Terraform:

export ARM_CLIENT_ID="<appId>"
export ARM_CLIENT_SECRET="<password>"
export ARM_SUBSCRIPTION_ID="<subscription-id>"
export ARM_TENANT_ID="<tenantId>"

Provider configuration​

Create versions.tf in your root module:

terraform {
  required_version = ">= 1.6.6"

  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.90.0"
    }
  }
}

provider "azurerm" {
  features {}
}

Remote state​

Store state in Azure Blob Storage so the whole team shares the same state file.

1. Create the storage account (one-time)​

az group create --name tfstate-rg --location eastus

az storage account create \
  --name tfstate$RANDOM \
  --resource-group tfstate-rg \
  --sku Standard_LRS \
  --allow-blob-public-access false

az storage container create \
  --name tfstate \
  --account-name <storage-account-name>

2. Add the backend block​

terraform {
  backend "azurerm" {
    resource_group_name  = "tfstate-rg"
    storage_account_name = "tfstateXXXXX"
    container_name       = "tfstate"
    key                  = "prod/terraform.tfstate"
  }
}

Workflow​

# Download providers and initialise the backend
terraform init

# Preview what will change
terraform plan

# Apply changes
terraform apply

# Tear down (use with care in production)
terraform destroy

Common variables​

Every module in terraform-az-modules shares these standard variables:

VariableTypeDescription
namestringShort resource name, e.g. app or cluster
environmentstringEnvironment label — prod, dev, staging
locationstringAzure region — eastus, westeurope, etc.
resource_group_namestringTarget resource group (required by most modules)
enabledboolSet to false to skip resource creation without removing the module block
extra_tagsmap(string)Additional tags merged with the module-generated tag set
custom_namestringOverride the auto-generated resource name entirely

Naming convention​

Modules automatically build resource names from name + environment + location. The resource_position_prefix variable controls whether the resource-type keyword is prepended or appended:

module "rg" {
  source = "git::https://github.com/terraform-az-modules/terraform-azurerm-resource-group.git?ref=v1.0.0"

  name        = "app"
  environment = "prod"
  location    = "eastus"
  # → produces: "rg-app-prod-eastus"  (resource_position_prefix = true, the default)

  # To fully override:
  # custom_name = "my-resource-group"
}

Pinning module versions​

Always pin modules to a release tag in production. Browse available tags on each module's GitHub releases page:

source = "git::https://github.com/terraform-az-modules/terraform-azurerm-aks.git?ref=v1.0.0"

Next steps​