Terraform Import, State Inspection, and Debug Logging

The terraform import command records an existing real-world object in Terraform state so Terraform manages it in place from then on, without recreating it. Its syntax is terraform import ADDRESS ID: ADDRESS (first) is a managed resource address in your configuration, such as aws_s3_bucket.logs, and ID (second) is the provider-specific identifier of the real object - an instance ID for aws_instance, a bucket name for aws_s3_bucket, a path such as projects/P/zones/Z/instances/N for many Google resources. Each provider's documentation lists the ID format each resource type expects. Data sources cannot be import targets: they are read every run, never managed.

The rule to remember: you must write the resource block before you import. The CLI command refuses an address that is not declared in configuration, and it updates state only - immediately, without a plan - and never writes or edits your .tf files. The workflow is therefore: write the block, import, then run terraform plan and adjust the block's arguments until the plan is clean.

resource "aws_s3_bucket" "logs" {
  bucket = "acme-log-archive"
}

terraform import aws_s3_bucket.logs acme-log-archive
terraform plan   # reconcile config with the imported attributes

A few mechanics matter in practice:

• One object per run. Each invocation imports a single resource instance.
• Instance addresses. For a resource using count or for_each, import into one instance: aws_instance.web[0] or aws_iam_role.svc["ci"]. In a POSIX shell, wrap a for_each address in single quotes so the double quotes reach Terraform: terraform import 'aws_iam_role.svc["ci"]' ci-deployer.
• Provider configuration. The command reads the real object through the provider, so credentials must be available, and the provider configuration it uses may depend only on input variables, environment variables or literals - not on data sources or other non-variable inputs. If any provider argument - a role ARN, an endpoint, a project ID - is computed from a data source or another resource's attribute, plan and apply still work but terraform import fails; supply that value through an input variable (or environment variable) instead.
• Locking. It acquires the state lock like any state-writing operation.

If the plan after import still shows changes, your configuration does not yet match reality - keep editing the block, not the state. A moved block is not an alternative: it renames addresses of objects Terraform already manages and cannot adopt an unmanaged object.

The import block, available since Terraform 1.5 and the recommended approach today, turns import into part of the normal plan/apply cycle instead of a one-off CLI action. You declare in configuration which object goes to which address, and the import happens - visibly - when the plan is applied:

import {
  to = aws_instance.web
  id = "i-0a1b2c3d4e5f67890"
}

resource "aws_instance" "web" {
  ami           = "ami-0abcd1234example"
  instance_type = "t3.micro"
}

The id argument accepts an expression (a variable or local, for example), not only a literal string, and its format is the same provider-specific ID the CLI command takes.

Bulk import (Terraform 1.7 and later) pairs the import block's for_each with the resource's. Iterating the same map, each.key builds the instance address and each.value supplies the provider ID:

variable "buckets" {
  default = { logs = "acme-logs", assets = "acme-assets" }
}

import {
  for_each = var.buckets
  to       = aws_s3_bucket.this[each.key]
  id       = each.value
}

resource "aws_s3_bucket" "this" {
  for_each = var.buckets
  bucket   = each.value
}

Import blocks are idempotent. Once the target is in state, a leftover import block plans no further action - no error, no re-import. You may delete it after the apply or keep it as a record of where the resource came from. Like the CLI command, an import block never changes the real object; it only records it in state.

The -generate-config-out flag writes configuration for objects you are importing but did not create. When a plan contains import blocks whose targets have no corresponding resource block, Terraform reads each object through the provider and writes a best-effort resource block for it into the file you name:

import {
  to = google_compute_instance.legacy
  id = "projects/acme-prod/zones/us-central1-a/instances/legacy-vm"
}

terraform plan -generate-config-out=generated.tf

Three behaviours to know:

• Only configless targets. Import targets that already have a resource block are not generated.
• The file must be new. Terraform errors if the path already exists - including the file from your previous run. Move the reviewed output into your configuration (or pick another file name) before generating for additional import blocks.
• The output needs review. It is a starting point: prune computed or redundant attributes and replace hard-coded values with variables and references. Generated blocks can also contain mutually exclusive arguments, which makes validation fail; keep the one you want and re-plan.

Once the plan is clean, apply to complete the import. Keep the division of labour straight: terraform import needs hand-written configuration and touches only state; the import block plus -generate-config-out is the only path where Terraform writes configuration for you.

Five read-only commands cover state inspection, and each answers a different question:

terraform state list can be filtered by address, and -id=ID does a reverse lookup: given a provider ID, it prints the address of the resource that manages that object. terraform state show zooms into a single instance:

terraform state list
terraform state list module.network
terraform state list -id=i-0a1b2c3d4e5f67890
terraform state show google_compute_instance.vm

terraform state pull downloads the current state through whichever backend is configured and prints it in the raw state-file format, so terraform state pull > backup.tfstate is a common pre-refactor backup. If the stored file uses an older state-file version, the printed copy is upgraded to the newest version the installed Terraform supports. All of these commands read state without modifying it; the commands that change state (state mv, state rm, state push) are covered in the state-management lesson.

terraform show renders a file in human-readable form: with no argument, the current state; given a path, a saved plan file or a state file. It takes a file path, not a resource address - for one resource, use terraform state show ADDRESS. With -json it emits HashiCorp's documented machine-readable format, the stable interface for policy checks, CI gates and other tooling:

terraform plan -out=tfplan
terraform show tfplan          # human-readable review of the saved plan
terraform show -json tfplan    # machine-readable, for automation

Two near-twins trip people up:

So integrate tools with show -json, and use state pull when you need the actual state document, such as a restorable backup.

terraform output prints the root module's output values from state:

terraform output                     # all outputs; sensitive ones redacted
terraform output instance_ip         # one value, as an HCL-style literal (strings quoted)
terraform output -raw instance_ip    # bare string for shell substitution
terraform output -json               # all outputs as JSON for tools

-raw prints a string, number or boolean with no quotes or formatting, which is what curl "$(terraform output -raw api_url)" needs; it works only for primitive values, so use -json for lists, maps and objects. Outputs marked sensitive = true are redacted in the all-outputs listing, but naming the output, or using -json or -raw, prints the real value in plain text. Sensitivity controls display; it is not encryption, and the value is stored in plain text in state - one reason state storage must be protected.

Verbose logging is enabled with the TF_LOG environment variable - there is no CLI flag for it. Setting it to any value turns logging on, and detailed logs appear on stderr; the value chooses the verbosity. The documented levels, from most to least verbose:

export TF_LOG=DEBUG
terraform apply

TF_LOG=TRACE terraform plan   # one-off, without exporting

TF_LOG=JSON suits log platforms that ingest structured lines, but HashiCorp states that the JSON log encoding is not a stable interface and may change without warning, so parsers may need updating between versions. If TF_LOG holds something that is not a level name, current Terraform falls back to TRACE and prints a warning - but that is implementation behaviour, so set a real level name.

When to use it: verbose logging is for reproducing a failure you cannot explain from normal output - an opaque provider error, unexpected plan behaviour, a crash - and for capturing a TRACE log to attach to a bug report against Terraform or a provider. Because TRACE logs include provider API traffic, they can contain sensitive values: enable logging for the reproduction, turn it off afterwards, and review or redact the captured output before sharing it.

TF_LOG_PATH sends log output to the file you name, appending to it, instead of writing it to stderr. The catch: TF_LOG_PATH does nothing by itself - HashiCorp's debugging docs state that logging must be enabled with TF_LOG even when TF_LOG_PATH is set. (Logs enabled through the scoped variables below are written to the same file.)

export TF_LOG=TRACE
export TF_LOG_PATH=./terraform.log
terraform apply   # full trace appended to ./terraform.log

When a TRACE log is overwhelming, scope it. TF_LOG_CORE sets a level for Terraform core only (graph building, state handling, plan logic), and TF_LOG_PROVIDER sets a level for provider plugins only (the API calls to AWS, Google Cloud, Azure and so on). Both take the same level names as TF_LOG and activate only their subset of the logs.

The two scoped variables do not combine with TF_LOG the same way. TF_LOG_PROVIDER overrides TF_LOG for providers, so you can raise (or lower) provider detail while core keeps the general level - in the fourth row, providers log at DEBUG while core stays at ERROR. TF_LOG_CORE takes effect only when TF_LOG is unset: in Terraform's logging code, a set TF_LOG wins for core, which is why the last row still logs core at TRACE. To get core-only output, set TF_LOG_CORE and leave TF_LOG unset.

Choosing between them is the practical skill. A resource failing with an opaque API error is a provider-side question (TF_LOG_PROVIDER=TRACE shows the actual requests and responses), while confusion about dependency ordering or state handling is core-side. For a bug report, a TRACE log captured with TF_LOG_PATH is the standard supporting evidence.