HashiCorp Certified: Terraform Associate

terraform import vs import blocks for Terraform Associate

Both bring an existing object under Terraform by recording it in state at a resource address. The terraform import command writes only to state, and you must write the resource block yourself. An import block lives in the configuration, goes through the normal plan and apply, and with terraform plan -generate-config-out can write the resource blocks for you.

The terraform import command

terraform import ADDRESS ID, for example terraform import aws_instance.foo i-abcd1234. The ID format depends on the resource type: an EC2 instance ID for an instance, a zone ID for a Route 53 zone. The provider documentation gives the format.

You must write the resource block before running it. The command only imports into state and does not generate configuration.

With HCP Terraform, terraform import runs locally, so you may need local values for variables that are set in the workspace.

import blocks

An import block has to (the resource address) and id (the provider's ID), and optionally identity, for_each and provider. The to address must match a resource block in the configuration. HashiCorp suggests an imports.tf file, or each import block beside its resource block.

Terraform performs the import during terraform apply. The plan shows it, for example Plan: 1 to import, 0 to add, 0 to change, 0 to destroy. Because the import is in the code, it can be reviewed in a pull request and run in CI/CD like any other change.

Generating configuration

Write only the import blocks, then run terraform plan -generate-config-out=generated.tf. For each import target with no resource block, Terraform writes its best guess at the HCL to that file. The path must not already exist, or Terraform errors.

Review and edit the generated file, then run terraform apply. Some resources produce conflicting arguments, such as ipv6_address_count and ipv6_addresses. Terraform still writes the file, and you remove one argument and plan again. Configuration generation arrived in Terraform v1.5 as an experimental feature, so its output format may change.

If no other resource in the configuration uses that provider, add a provider block so Terraform knows which provider to use, and run terraform init again.

Rules for both

Import each remote object to only one resource address. Importing the same object at two addresses can cause unwanted behaviour.

Not every resource type can be imported. Each resource page in the Terraform Registry states at the bottom whether it can.

Where the exam catches people

Believing terraform import writes the resource block: it only updates state. Use an import block with -generate-config-out to generate configuration.
Believing -generate-config-out can append to an existing file: the path must be new, or Terraform errors.
Believing one object can be imported at two addresses: each remote object should be bound to one address.
Believing every resource type supports import: check the bottom of the resource's Registry page.