Terraform identifies resources by address. Rename a resource, wrap it in a module, or switch from count to for_each, and the address changes. Without help, Terraform sees "old address gone, new address appeared" and plans destroy + create.
The config-driven refactoring blocks fix that, and unlike terraform state mv, they're reviewed in a merge request, shown in a plan, and applied identically to every environment.
| Task | Block | Since |
|---|---|---|
| Rename / restructure | moved |
Terraform 1.1 |
| Adopt an existing object | import |
Terraform 1.5 (for_each 1.7; in child modules 1.16) |
| Stop managing without destroying | removed |
Terraform 1.7 |
| Find unmanaged objects and generate config | terraform query + list blocks |
Terraform 1.14 |
| Force replacement | -replace=ADDR |
Terraform 0.15.2 (replaces taint) |
OpenTofu has moved, import (with for_each) and removed too, sometimes earlier than Terraform.
moved blocks¶
# Rename
moved {
from = azurerm_storage_account.sa
to = azurerm_storage_account.logs
}
# Single resource → count / for_each
moved {
from = azurerm_key_vault.this
to = azurerm_key_vault.this[0]
}
# count → for_each (one block per instance)
moved {
from = azurerm_subnet.this[0]
to = azurerm_subnet.this["aks"]
}
moved {
from = azurerm_subnet.this[1]
to = azurerm_subnet.this["data"]
}
# Into a module
moved {
from = azurerm_virtual_network.main
to = module.network.azurerm_virtual_network.this
}
# Rename a module call (moves everything inside it)
moved {
from = module.vnet
to = module.network
}
The plan shows # azurerm_storage_account.sa has moved to azurerm_storage_account.logs and no create/destroy.
Rules and practices:
- Put
movedblocks in the module that owns the resources. A shared module that renames internals ships themovedblock, and every consumer upgrades without state surgery. This is what makes internal refactors a minor release instead of a major one (shared modules). - Keep them for a while. Leave
movedblocks in place until every environment and every consumer has applied past them. In shared modules, keep them through at least one major version. Removing amovedblock before a consumer upgrades turns into destroy/create for them. - Chains work.
a → bthen laterb → cboth stay; Terraform follows the chain. - Moves can't cross state files or resource types. Changing
azurerm_app_servicetoazurerm_linux_web_appis a different type: useremoved+import. (Some providers supportmovedacross types via resource identity; check the provider docs.) - Moving into or out of a module with its own provider configuration isn't possible. Another reason child modules shouldn't configure providers.
import blocks¶
Adopt something that already exists (created by hand, by ARM/Bicep, by another tool):
import {
to = azurerm_resource_group.legacy
id = "/subscriptions/0000.../resourceGroups/rg-legacy-prod"
}
resource "azurerm_resource_group" "legacy" {
name = "rg-legacy-prod"
location = "canadacentral"
}
terraform plan # shows "will be imported", plus any differences
terraform apply # imports (and applies any differences)
Generate the configuration¶
Writing the resource block by hand for a complex object is tedious. Let Terraform draft it:
terraform plan -generate-config-out=generated.tf
For every import block whose to address has no resource block yet, Terraform writes one with every attribute the provider reports. The output is a starting point: remove computed and default values, replace literals with references and variables, then move it into the right file.
Import many with for_each (1.7+)¶
locals {
existing_rgs = {
app = "/subscriptions/0000.../resourceGroups/rg-app-prod"
data = "/subscriptions/0000.../resourceGroups/rg-data-prod"
}
}
import {
for_each = local.existing_rgs
to = azurerm_resource_group.this[each.key]
id = each.value
}
Import by identity (1.12+)¶
Some providers expose a structured resource identity, so you can import with attributes instead of a hand-built ID string:
import {
to = aws_s3_bucket.logs
identity = {
bucket = "acme-logs-prod"
}
}
id and identity are mutually exclusive. Which resources support identity depends on the provider version.
Imports inside child modules (1.16+)¶
Before 1.16, import blocks had to live in the root module. Now a module that owns a resource can own its import too, driven by an input:
# modules/storage/main.tf
variable "existing_storage_account_id" {
type = string
default = null
}
import {
for_each = var.existing_storage_account_id == null ? {} : { this = var.existing_storage_account_id }
to = azurerm_storage_account.this
id = each.value
}
Useful when migrating many app repos onto a shared module: each consumer passes the ID of what it already has, and the module adopts it.
After importing¶
- Leave the
importblock in for one apply cycle per environment, then delete it. Re-running an import of something already in state is a no-op, so leaving it longer is harmless but noisy. - Read the plan. An import plus an "update in-place" means your configuration doesn't match reality; decide which one is right before applying.
- The old CLI command (
terraform import ADDR ID) still works but changes state immediately with no plan. Use the block.
terraform query and list resources (1.14+)¶
Finding what to import used to mean scripting the cloud CLI. Terraform 1.14 added list resources: providers can implement a "list" operation, and you query it from a .tfquery.hcl file.
# discover.tfquery.hcl
list "azurerm_resource_group" "untracked" {
provider = azurerm
config {
# filter arguments are provider-specific; check the provider docs
}
}
terraform query # print what was found
terraform query -generate-config-out=imported.tf # write import + resource blocks
The generated file contains import blocks and resource configuration for what the query found, ready to review and trim. Provider support is still growing, so check whether your provider implements list resources for the types you need. Terraform 1.15+ formats .tfquery.hcl files with terraform fmt.
removed blocks¶
Stop managing a resource without destroying it:
removed {
from = azurerm_storage_account.legacy
lifecycle {
destroy = false
}
}
Delete the resource block, add the removed block, apply. The object stays in Azure; Terraform forgets it. Typical uses:
- Handing a resource over to another stack or another team (
removedhere,importthere) - Splitting a large state (below)
- Retiring Terraform management of something without an outage
With destroy = true (the default), a removed block destroys the object and can run destroy-time provisioners, which is a reviewable alternative to deleting the block.
from can be a resource or a whole module (from = module.legacy_app).
Forcing replacement: -replace¶
terraform plan -replace='azurerm_linux_virtual_machine.web["web1"]'
terraform apply -replace='azurerm_linux_virtual_machine.web["web1"]'
Replaces the old terraform taint workflow: the replacement shows up in a plan instead of silently marking state. For replacement driven by a change in something else, use replace_triggered_by.
Moving resources between states¶
Splitting a monolithic state, or handing ownership to another stack. No block can move across states, so it's two coordinated changes:
In the source stack:
removed {
from = azurerm_key_vault.shared
lifecycle { destroy = false }
}
In the destination stack:
import {
to = azurerm_key_vault.shared
id = "/subscriptions/.../vaults/kv-shared-prod"
}
resource "azurerm_key_vault" "shared" {
# ...
}
Order: apply the destination first (now both states know the resource, which is briefly fine as long as nobody applies changes to it from the source), then apply the source to forget it. Or the other way round if you accept a short window where nobody manages it. Either way, check that both plans show no changes to the real object.
The CLI way (terraform state mv -state-out=...) works only with local state files and is effectively legacy. Use the blocks.
Provider upgrades that change resource types¶
Providers occasionally replace a resource type (azurerm_app_service → azurerm_linux_web_app, azurerm_storage_container.storage_account_name → storage_account_id). Patterns:
- Read the provider's upgrade guide for the major version. They usually include the exact migration steps.
- For a new resource type:
removed { destroy = false }on the old +importon the new, in one change. - For an argument rename: update the argument; check the plan for unexpected replacement.
- For many repos: put the migration (
moved/import/removed) inside the shared module, release it as a major version with upgrade notes, and let Renovate open the MRs.