Terraform Azure Assistant

Your focused agent for day-to-day Azure Terraform tasks — writing configurations, troubleshooting plans, managing state, and keeping infrastructure code clean and maintainable.

When to Use This Agent

Choose Terraform Azure Assistant when:

• Writing or modifying Terraform configurations for Azure resources
• Troubleshooting Terraform plan/apply errors with Azure provider
• Managing Terraform state operations (import, move, remove, taint)
• Reviewing Terraform code for Azure best practices and security
• Converting Azure CLI or portal-provisioned resources to Terraform

Consider alternatives when:

• You need a comprehensive Azure landing zone design — use a Terraform implementation companion
• You need multi-cloud infrastructure — use a general Terraform engineer agent
• You need Azure ARM/Bicep templates — use a Bicep specialist agent

Quick Start

Copy
# .claude/agents/terraform-azure-assistant.yml
name: Terraform Azure Assistant
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Day-to-day Azure Terraform assistant for writing configs, debugging plans, and managing state

Example invocation:

claude "Import our existing Azure SQL Database into Terraform state and generate the matching configuration"

Core Concepts

Common Azure Terraform Operations

Operation	Command	Use Case
Initialize	terraform init	Set up providers and backend
Plan	terraform plan -out=plan.tfplan	Preview changes safely
Apply	terraform apply plan.tfplan	Execute saved plan
Import	terraform import azurerm_resource.name /subscriptions/.../resourceId	Bring existing resources under management
State Move	terraform state mv old.name new.name	Refactor without recreating
Taint	terraform taint azurerm_resource.name	Force recreation on next apply

Resource Import Workflow

Copy
# 1. Write the resource config block
# 2. Find the Azure resource ID
az resource show --name mydb --resource-group myrg \
  --resource-type "Microsoft.Sql/servers" --query id

# 3. Import into state
terraform import azurerm_mssql_server.main /subscriptions/.../Microsoft.Sql/servers/mydb

# 4. Run plan to verify — adjust config until plan shows no changes
terraform plan

Configuration

Parameter	Description	Default
workspace_strategy	How environments are separated (workspaces, directories)	directories
state_lock_timeout	Maximum wait for state lock	5m
plan_output	Save plan files for review	true
auto_format	Run terraform fmt on save	true
validation_level	Validation depth (syntax, plan, policy)	plan

Best Practices

1. Always save plans before applying. Run terraform plan -out=plan.tfplan and review the output before running terraform apply plan.tfplan. This ensures you apply exactly what you reviewed and prevents drift between plan and apply in fast-moving environments.

2. Use terraform state mv for refactoring, not destroy-and-recreate. When renaming resources or moving them into modules, state move preserves the existing Azure resource. A delete-and-create cycle causes downtime and potential data loss for stateful resources.

3. Import existing resources before writing new configs. When adopting Terraform for already-provisioned Azure resources, import first, then iteratively adjust the config until terraform plan shows no changes. This verifies your config matches reality before making modifications.

4. Keep provider blocks in a dedicated versions.tf file. Centralizing provider configuration and version constraints makes upgrades systematic. Lock the exact AzureRM version in production and test upgrades against a dev environment first.

5. Use terraform validate and fmt in pre-commit hooks. Catch syntax errors and formatting inconsistencies before they reach code review. Add terraform validate and terraform fmt -check to your CI pipeline as fast-fail gates.

Common Issues

Import succeeds but plan shows differences. After importing an Azure resource, the Terraform config rarely matches 100% on the first try. Run terraform plan, note each reported change, and update your config to match the actual resource state. Pay special attention to default values that Azure sets but your config omits.

State lock stuck after a failed apply. If Terraform crashes mid-apply, the Azure Storage blob lease may not be released. Use terraform force-unlock <lock-id> cautiously — first verify no other process is running. Azure blob leases expire after 60 seconds by default, so waiting is often the safest option.

Provider authentication fails in CI/CD. Azure Terraform auth works differently in CI than locally. In CI, use a service principal with ARM_CLIENT_ID, ARM_CLIENT_SECRET, ARM_TENANT_ID, and ARM_SUBSCRIPTION_ID environment variables. For GitHub Actions, prefer OIDC-based authentication to avoid storing long-lived secrets.