Terraform Azure Implementation Companion

Your specialized agent for implementing Azure infrastructure using Terraform, following Azure best practices and HashiCorp conventions for production-grade deployments.

When to Use This Agent

Choose Terraform Azure Implementation Companion when:

• Writing Terraform configurations for Azure resources (VMs, AKS, App Services, networking)
• Migrating existing Azure infrastructure to Terraform management
• Reviewing and refactoring Azure Terraform modules for best practices
• Setting up Terraform state management with Azure Storage backends
• Implementing Azure-specific patterns (hub-spoke networking, landing zones)

Consider alternatives when:

• You need multi-cloud Terraform (AWS + Azure + GCP) — use a general Terraform agent
• You need ARM/Bicep templates instead of Terraform — use a Bicep agent
• You need Azure architecture design without IaC — use an Azure architect agent

Quick Start

Copy
# .claude/agents/terraform-azure.yml
name: Terraform Azure Implementation Companion
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Azure Terraform agent for implementing infrastructure as code with Azure provider best practices

Example invocation:

claude "Create a Terraform module for an AKS cluster with a system node pool, user node pool, Azure CNI networking, and Azure AD integration"

Core Concepts

Azure Terraform Project Structure

infrastructure/
├── main.tf              # Provider config, backend
├── variables.tf         # Input variable declarations
├── outputs.tf           # Output values
├── terraform.tfvars     # Variable values (not in git)
├── versions.tf          # Provider version constraints
├── modules/
│   ├── networking/      # VNet, subnets, NSGs
│   ├── compute/         # VMs, VMSS, AKS
│   ├── database/        # SQL, Cosmos, Redis
│   └── monitoring/      # Log Analytics, App Insights
└── environments/
    ├── dev.tfvars
    ├── staging.tfvars
    └── prod.tfvars

Azure Provider Configuration

Copy
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 3.80"
    }
  }
  backend "azurerm" {
    resource_group_name  = "rg-terraform-state"
    storage_account_name = "stterraformstate"
    container_name       = "tfstate"
    key                  = "prod.terraform.tfstate"
  }
}

provider "azurerm" {
  features {}
  subscription_id = var.subscription_id
}

Configuration

Parameter	Description	Default
azure_region	Primary Azure region	eastus2
naming_convention	Resource naming pattern (CAF, custom)	caf
state_backend	State storage (azurerm, terraform-cloud)	azurerm
environment	Target environment (dev, staging, prod)	dev
provider_version	AzureRM provider version constraint	~> 3.80

Best Practices

1. Follow Azure Cloud Adoption Framework naming conventions. Use the CAF naming module or consistent prefixes (rg- for resource groups, vnet- for VNets, aks- for clusters). Consistent naming makes resources discoverable, supports automation, and simplifies cost tracking across environments.

2. Pin provider versions with pessimistic constraints. Use ~> 3.80 (not >= 3.0) to allow patch updates while preventing breaking changes from major or minor version bumps. Run terraform init -upgrade in CI to catch provider updates before they hit production.

3. Use data sources to reference existing resources. When your Terraform config depends on resources managed elsewhere (shared VNets, Key Vaults, DNS zones), use data blocks instead of hardcoding resource IDs. This keeps your config portable and self-documenting.

4. Implement Azure-specific lifecycle rules. Some Azure resources require prevent_destroy lifecycle rules (databases, key vaults). Others need ignore_changes for auto-managed properties (managed identity object IDs, auto-generated passwords). Configure these explicitly to prevent accidental data loss.

5. Store sensitive values in Azure Key Vault, not tfvars. Reference secrets using data "azurerm_key_vault_secret" instead of passing them through variable files. This keeps secrets out of state files (or at least reduces them) and provides audit trails for secret access.

Common Issues

Terraform plan shows unexpected resource replacements. Azure resources that require replacement on certain attribute changes (like changing the SKU tier or location) can cause downtime. Always review plan output carefully, use lifecycle { prevent_destroy = true } on critical resources, and test changes in a non-production environment first.

State file conflicts when multiple developers run apply. Without state locking, concurrent applies corrupt the state file. Azure Storage backend supports state locking natively via blob leases — ensure your backend config has it enabled (it is by default). For teams, use Terraform Cloud or Spacelift for centralized state management.

Azure API rate limiting causes intermittent failures. Large Terraform configurations that create many resources simultaneously can hit Azure subscription-level API limits. Add parallelism flag (terraform apply -parallelism=5) to throttle concurrent operations, and use depends_on to sequence resource creation logically.