Terraform import is the process of binding an existing remote infrastructure object to a Terraform resource address so Terraform can begin managing it without creating a duplicate. Import sounds simple, but safe adoption requires three things to agree: the real infrastructure, the Terraform state binding, and the configuration that describes the intended object. Importing only updates state relationships; it does not automatically produce a complete, production-ready configuration.<\/p>\n
The current Terraform Associate (004)<\/a> scope includes state, core workflow, configuration, and import concepts. Import is especially important in mature environments where infrastructure already exists before an infrastructure-as-code program begins.<\/p>\n Record the resource identity, region or account, dependencies, tags, security settings, lifecycle expectations, and current owner. Confirm that the object is genuinely unmanaged by another Terraform state or automation system.<\/p>\n Importing the same object into two states creates conflicting ownership. The first governance question is therefore who should manage the resource after adoption.<\/p>\n The Terraform resource address determines where the imported object will live in configuration and state. Module paths, `for_each` keys, and `count` indexes must match the design you intend to keep.<\/p>\n Do not import everything into a temporary flat root module if the production architecture should use modules. Moving state later is possible, but careful addressing at the start reduces migration complexity.<\/p>\n Modern Terraform supports declarative import blocks that can be reviewed and applied as configuration. This makes import behavior visible in version control instead of relying only on one-time CLI commands.<\/p>\n Declarative import is especially useful for teams adopting many existing resources because the mapping can be reviewed, repeated in controlled environments, and retained as migration evidence.<\/p>\n Terraform can assist with configuration generation in import workflows, but generated configuration should be treated as a starting point. Providers expose many computed, optional, and defaulted attributes that may not belong in long-term configuration.<\/p>\n Reduce the configuration to the settings Terraform should intentionally manage. Keep values that represent policy and desired behavior; avoid freezing incidental provider defaults unless they matter.<\/p>\n A successful import does not mean the configuration matches reality. Run `terraform plan` and review every proposed change. The ideal first plan is often no-op or limited to intentional normalization.<\/p>\n If Terraform proposes destruction or major replacement after import, stop and investigate. The configuration may use a different immutable setting, resource type, region, or identifier than the existing object.<\/p>\n Some imported resources expose secrets or write-only settings differently from resources Terraform originally created. Do not attempt to force unknown secret values into configuration solely to achieve textual symmetry.<\/p>\n Use provider-supported secret references, ephemeral values, or write-only arguments where appropriate, and protect the imported state because it may contain sensitive remote attributes.<\/p>\n An existing resource may reference networks, identities, security groups, databases, or parent objects. Decide whether those dependencies will also be Terraform-managed or remain external data sources.<\/p>\n Use data sources for intentionally external dependencies instead of importing every surrounding resource. Adoption should clarify ownership boundaries rather than automatically expanding them.<\/p>\n Once the imported object produces a safe plan, teams may move it into reusable modules, rename resources, or reorganize state. Use state-aware refactoring features such as moved blocks or `terraform state mv` procedures rather than destroying and recreating infrastructure.<\/p>\n Version-control every refactor and review the plan after each step. The broader principle in change management applies: reduce the number of simultaneous changes while adopting business-critical infrastructure.<\/p>\n Resources should be adopted in batches that can be verified. Large brownfield environments tempt teams to import hundreds of resources at once. Smaller batches make it easier to review plans, identify provider defaults, and correct module design before repeating mistakes at scale.<\/p>\n Prioritize high-value resources and establish a repeatable migration pattern. Automation can help with inventory and import generation after the pattern is proven.<\/p>\n Once Terraform manages the object, console edits and competing automation should follow the new operating model. Document the workspace, module, owner, state backend, and allowed emergency-change process.<\/p>\nInventory the object before importing it<\/h3>\n
Write the resource address deliberately<\/h3>\n
Use import blocks for repeatable adoption<\/h3>\n
Generate or write configuration, then review it<\/h3>\n
Plan immediately after import<\/h3>\n
Handle sensitive and computed attributes carefully<\/h3>\n
Import dependencies in a controlled order<\/h3>\n
Refactor only after stable ownership is established<\/h3>\n
Finish with documented ownership<\/h3>\n