What is terraform import and when do you need it?

terraform import is the bridge between manually-created infrastructure and Infrastructure as Code. Think of it like adopting a rescue dog — the dog already exists, you just need to register it in your system and start managing it properly. The resource is out there in AWS or GCP, and terraform import tells Terraform 'this resource exists, start tracking it in state.'

Internally, terraform import works by taking a resource address (the Terraform resource block identifier) and a cloud provider resource ID (like an AWS instance ID), then making API calls to fetch the current attributes of that resource and writing them into the state file. Critically, import does NOT generate the HCL configuration for you — it only updates state. This means you must first write the resource block in your .tf files that matches the imported resource, then run the import, and then iterate by running terraform plan to see what attributes are missing or mismatched in your HCL until the plan shows no changes.

The traditional import workflow is tedious but important: write an empty or partial resource block, run terraform import aws_rds_cluster.payments_db payments-db-prod-cluster-id, then run terraform plan repeatedly while adding missing attributes to your HCL until the plan is clean. Each plan iteration will show you attributes that differ between your config and the actual resource — things like backup retention periods, maintenance windows, or parameter groups that you forgot to specify.

Starting with Terraform 1.5, the import block was introduced as a declarative alternative. Instead of running an imperative CLI command, you add an import block to your configuration that specifies the resource address and cloud ID. When you run terraform plan, it shows the import as part of the plan, and terraform apply executes it. This is a significant improvement because imports become part of your version-controlled code, reviewable in pull requests, and repeatable across environments.

Common scenarios where you need terraform import include: migrating a legacy infrastructure to Terraform (the most common case), recovering after accidental state deletion, bringing a resource that was created via the AWS console clickops into Terraform management, and splitting a large Terraform project into smaller ones where some resources need to move to a different state file.

There are important gotchas with import. Not all resource attributes are importable — some providers or resource types do not support import at all, and you will get an error. Some resources require specific ID formats that are not obvious — for example, an AWS security group rule import requires a combination of security group ID, type, protocol, port range, and CIDR. After importing, you must verify with terraform plan that your configuration matches the imported resource, because any drift will be 'corrected' on the next apply, potentially causing outages. Finally, import does not handle dependencies — if you import a subnet but not the VPC it belongs to, your configuration must use a data source for the VPC or import it as well.