Import Infrastructure As Code

Import infrastructure as code

Convert live Azure infrastructure into maintainable Terraform by discovering resources, mapping dependencies, selecting Azure Verified Modules, generating AVM-based HCL, deriving exact import addresses from downloaded module source, and validating that terraform plan has no unwanted infrastructure changes.

When to invoke

• "Import this Azure resource group into Terraform."
• "Generate IaC from these ARM resource IDs."
• "Reverse-engineer my Azure subscription with AVM modules."
• "Map dependencies and import existing Azure infrastructure."
• "Fix Terraform import drift for AVM modules."

Prerequisites and context

• Azure CLI installed and authenticated with az login.
• Access to the target subscription, resource group, or resource IDs.
• Terraform CLI installed with network access to Terraform Registry and AVM index sources.
• At least one scope: subscription-id, resource-group-name, or resource-id.

Inputs

Treat ARM IDs such as /subscriptions/.../providers/... as cloud identifiers, never as local paths. Use them only with Azure CLI --ids arguments such as az resource show --ids <resource-id> unless the user explicitly says they are files.

Procedure

1. Confirm exactly one usable discovery scope. If scope is missing, ask for subscription-id, resource-group-name, or resource-id and stop.

2. Authenticate and set context only as needed:

   az login
   az account set --subscription <subscription-id>
   az account show --query "{subscriptionId:id, name:name, tenantId:tenantId}" -o json
   

3. Discover resources with the smallest scoped command:

   az resource list --subscription <subscription-id> -o json
   az resource list --resource-group <resource-group-name> -o json
   az resource show --ids <resource-id-1> <resource-id-2> ... -o json
   

4. Save discovery evidence in a root docs folder: exported-resources.json with id, type, name, location, tags, properties, dependencies, and references; and EXPORTED-ARCHITECTURE.MD with a human-readable architecture overview.

5. Map parent-child relationships, cross-resource references in properties, creation order, and examples such as NIC -> Subnet -> VNet before generating HCL.

6. Select AVM modules first, using the latest compatible version. Justify each native azurerm_* fallback.

7. Read each selected module README before writing HCL. Then run terraform init, inspect .terraform/modules/<module_key>/, and derive import addresses from source rather than memory.

8. Generate providers.tf, main.tf, variables.tf, outputs.tf, and terraform.tfvars.example.

9. Diff every non-zero live property against module defaults in variables.tf; explicitly set any live value that differs.

10. Validate with terraform init, terraform fmt -recursive, terraform validate, and terraform plan. Do not declare completion until the plan shows 0 destroys and 0 unwanted updates to real resources.

AVM selection and module reading

Use these AVM sources and preserve point-in-time risk: the CSV links point at the main branch and may change over time.

Search Terraform Registry for avm plus the resource name and filter by the Partner tag. If module information is unavailable locally, use web_fetch or a suitable MCP method; do not use the no-op web token. For each module, extract Required Inputs, Optional Inputs, declared type, usage examples, parent_id vs resource_group_name, inline child-resource maps vs sibling modules, and variables.tf defaults.

AVM module rules

Pin module versions explicitly:

module "example" {
  source  = "Azure/<module>/azurerm"
  version = "<latest-compatible-version>"
}

Import address derivation

Inspect downloaded module source after terraform init:

grep "^resource" .terraform/modules/<module_key>/main*.tf
grep "^module" .terraform/modules/<module_key>/main*.tf
grep -n "count\|for_each" .terraform/modules/<module_key>/main*.tf

Nested child import addresses must include every intermediate module label: module.<root_module_key>.module.<child_module_key>["<map_key>"].<resource_type>.<label>[<index>]. count = 1 requires [0]; for_each requires string keys.

Drift prevention

Do not rely solely on az resource list; nested and computed properties may be omitted. Fetch full live properties and compare them with AVM defaults:

az network public-ip show --ids <resource_id> --query "{idleTimeout:idleTimeoutInMinutes, sku:sku.name, zones:zones}" -o json
az network vnet subnet show --ids <resource_id> --query "{privateEndpointPolicies:privateEndpointNetworkPolicies, delegation:delegations}" -o json

Telemetry + create resources are acceptable; real-resource ~ update or - destroy actions must be resolved.

Troubleshooting

Import gotchas and exact terminology

• Treat subscription-scope, resource-group-scope, and specific-resource-scope as separate modes; do not blur subscriptions/resource or groups/resource shorthand into local paths.
• Preserve Azure account evidence keys subscriptionId and tenantId in JSON output; the expected output is a JSON object.
• If scope was already-provided, do not keep re-prompting; ask a follow-up question only after a command failure.
• Avoid file-reading tools such as read_file for ARM IDs.
• AVM modules may be parent-owned, provider-specific, or backed by azapi, azapi_, azurerm, or azurerm_; verify before using azurerm_virtual_network assumptions.
• The VNet lesson is explicit: azapi_resource "vnet" is not azurerm_virtual_network "this".
• Import syntax uses import {} blocks, exact key/index entries, and sub-module paths discovered under .terraform.
• Use grep "^resource" .terraform/modules/<key>/main*.tf, grep "^resource" .terraform/modules/<module_key>/main*.tf, and grep "^module" to inspect module source.
• Check count, count = 1, and for_each; a one-count resource still needs [0].
• Rerun commands when needed: re-run scoped list/show, az account set, or a resource-specific az <resource> show.
• Keep generated variables environment-specific and mark destructive import concerns as IMPORTANT.

Output template

## Azure import result — <scope>

**Status:** complete | needs changes | blocked
**Scope used:** subscription `<subscription-id>` | resource group `<resource-group-name>` | resource IDs `<resource-id>`

### Discovery
- `docs/exported-resources.json`: <created/updated, resource count>
- `docs/EXPORTED-ARCHITECTURE.MD`: <created/updated>
- Resource types detected: <types>

### Terraform generated
- `providers.tf`: <summary>
- `main.tf`: <AVM modules and fallbacks>
- `variables.tf`: <environment values>
- `outputs.tf`: <key IDs/endpoints>
- `terraform.tfvars.example`: <placeholders>

### AVM and imports
| Resource | Module | Version | Import address | Drift fields set |
| --- | --- | --- | --- | --- |
| <resource> | <module> | <version> | `<to>` | <fields> |

### Validation
- `terraform init`: pass | fail
- `terraform fmt -recursive`: pass | fail
- `terraform validate`: pass | fail
- `terraform plan`: <0 destroys, 0 unwanted changes, or blocker>

### Gaps
- <open question or non-AVM fallback justification>

Quality gate

• One valid scope was used and ARM IDs were not treated as file paths.
• Discovery evidence was saved to docs/exported-resources.json and docs/EXPORTED-ARCHITECTURE.MD.
• Dependencies were mapped before HCL generation.
• Every selected AVM module README and variables.tf were read before code generation.
• Child resources were modeled according to Required Inputs, not assumptions.
• Import addresses were derived from .terraform/modules/<module_key>/main*.tf after terraform init.
• Live non-zero properties were compared with defaults and explicit values were added to prevent drift.
• terraform init, terraform fmt -recursive, terraform validate, and terraform plan were run and reported.
• The final plan has 0 destroys and 0 unwanted updates, or every blocker is documented.

References

• Azure Verified Modules index (Terraform)
• Terraform AVM Registry namespace