Skip to content

Maintaining Infrastructure with Terraform

Step 15 of 18

Maintaining Infrastructure with Terraform

Introduction

This lesson covers the Maintain infrastructure with Terraform area of the Terraform Associate (004) exam, objectives 7a to 7c. The area holds three of the 37 objectives, about 8% of this course's mock questions (HashiCorp does not publish domain weights; that proportion is an OnLevelUp choice). The exam lasts one hour, tests Terraform 1.12, and mixes true/false, multiple-choice and multiple-answer questions.

Real-world Terraform rarely starts from an empty cloud account. Teams inherit servers created by hand, scripts that built a network five years ago, and resources that someone created during an incident. Maintaining infrastructure means bringing existing objects under Terraform's control, inspecting what Terraform knows about them, and troubleshooting when something goes wrong.

After this lesson you will be able to import existing resources with import blocks and the terraform import command, generate configuration for imported objects, inspect state with terraform state list, terraform state show and terraform show, and enable detailed logs with TF_LOG.

Learning objectives

  • Explain why and when to import existing infrastructure.
  • Write an import block and use terraform plan -generate-config-out.
  • Use the legacy terraform import CLI command and know how it differs.
  • Inspect state with terraform state list, terraform state show, terraform show and terraform output.
  • Enable and direct verbose logs with TF_LOG, TF_LOG_PATH and TF_LOG_CORE/TF_LOG_PROVIDER.

7a. Importing existing infrastructure

Import attaches an existing real object to a resource address in state. Terraform will then manage it: future plans compare your configuration to the object and propose changes. Importing never creates or modifies the real object by itself; it only writes to state.

Why import

  • Resources created manually in the console that must now be managed as code.
  • Adoption of Terraform in a team with an existing environment.
  • Recovery after state loss or after removing resources from state by mistake.
  • Moving an object from one Terraform configuration to another (remove it from one state, import it into the other).

The import block (declarative, recommended)

Since Terraform 1.5 you can import by configuration:

HCL
import {
  to = aws_s3_bucket.logs
  id = "acme-prod-logs"
}

resource "aws_s3_bucket" "logs" {
  bucket = "acme-prod-logs"
}

How it works:

  • to is the destination resource address; id is the provider-specific identifier (a bucket name, an instance ID, a resource ARN, depending on the resource; the provider documentation's "Import" section tells you which).
  • The import happens during terraform plan and terraform apply. The plan shows # aws_s3_bucket.logs will be imported, and the import is carried out when you apply.
  • Because it is in code, it is reviewed in a pull request, appears in plans, and can be used in HCP Terraform runs.
  • for_each is supported in import blocks (since 1.7), which makes importing many similar objects practical. The id can be an expression.
  • Terraform 1.12 also allows importing by an identity attribute for providers that support resource identities. identity and id cannot be combined.
  • After a successful apply you may remove the import block; leaving it in place is harmless but no longer necessary.

Generating configuration

Writing a resource block by hand for a complex object is tedious. Let Terraform draft it:

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

Terraform reads the real object and writes a resource block with all attributes into generated.tf. Rules:

  • The target file must not already exist.
  • The generated code is a starting point. Review it, remove computed or redundant attributes, replace literals with variables and move it into your normal files.
  • This works only with import blocks that have no matching resource block yet.

The terraform import command (imperative, legacy)

Bash
terraform import aws_s3_bucket.logs acme-prod-logs

The command writes the object into state immediately. You must write the resource block first; the command does not generate it. It is still supported, but the block is preferred because it is declarative, repeatable and visible in a plan.

Aspect import block terraform import command
Introduced Terraform 1.5 Original feature
Where defined In configuration On the command line
Preview before change Yes, in plan No
Can generate configuration Yes, with -generate-config-out No
Many resources at once Yes, with for_each One command per object
Needs resource block first No when generating Yes

Worked example: adopting a hand-built security group

Scenario. During an incident, an engineer created the security group sg-0a1b2c3d4e5f6a7b8 in the console to allow port 443 from a partner network. It has been in production for months. The company now wants it managed by Terraform without any downtime.

Step by step.

  1. Find the import ID in the provider documentation: for aws_security_group it is the group ID.
  2. Add an import block:
HCL
import {
  to = aws_security_group.partner_https
  id = "sg-0a1b2c3d4e5f6a7b8"
}
  1. Generate a draft: terraform plan -generate-config-out=generated.tf.
  2. Open generated.tf, clean it up (for example, replace the hard-coded VPC ID with module.network.vpc_id), and move it into security.tf.
  3. Run terraform plan. It shows 1 to import, 0 to add, 0 to change, 0 to destroy. If the plan shows changes, your configuration differs from reality; adjust the code until the plan has no changes for this resource.
  4. Run terraform apply. State now tracks the group.

Why other approaches are weaker. Deleting and recreating the group would cut the partner's connection. terraform import works but gives no preview and no generated code. Editing the state file by hand is unsafe.

Limits of import

  • Import brings one object per resource address. Related objects (for example rules, attachments) may need their own import.
  • Import does not detect dependencies between objects; you must express references in code.
  • Not every resource type supports import. The provider documentation says whether it does.
  • The configuration must match the real object well enough. A plan after import often shows small differences (default values, tags) that you resolve.

7b. Inspecting state with the CLI

terraform state list

Lists every resource instance tracked in state, one address per line. It accepts filters:

Bash
terraform state list
terraform state list module.network
terraform state list 'aws_instance.web[*]'

Sample output:

Text
aws_instance.web[0]
aws_instance.web[1]
module.network.aws_subnet.private["a"]
module.network.aws_vpc.this

terraform state show

Shows all attributes recorded for one resource, including computed ones:

Bash
terraform state show aws_instance.web[0]

Sensitive values are masked in the CLI view, but they are still stored in the state file in clear text.

terraform show

terraform show prints the full state, or a saved plan when given a plan file (terraform show tfplan). With -json the output is machine-readable, which is useful in CI to enforce policies.

terraform output

terraform output reads root module outputs from state; terraform output -raw db_endpoint prints a single string without quotes (good for scripts) and -json prints structured values.

Comparison: inspection commands

Command Shows Typical use
terraform state list Addresses only Find the name of a resource
terraform state show ADDR Attributes of one resource Debug a specific object
terraform show Whole state, or a plan file Review or export for tools
terraform output Root module outputs Feed values to scripts
terraform graph Dependency graph in DOT format Understand ordering
terraform console Interactive expression evaluator Test expressions against state

Modifying state from the CLI

Besides read-only commands, terraform state mv, terraform state rm, terraform state pull and terraform state push change or export state. They create backups, but they run immediately. Prefer the declarative moved and removed blocks when possible (previous lesson).

Worked example: finding a drifted instance

Scenario. A monitoring alert says that one web server has the wrong instance type. The configuration uses count = 3. You do not know which of the instances differs.

Step by step.

  1. terraform state list | grep aws_instance.web returns the three addresses.
  2. For each, terraform state show 'aws_instance.web[1]' and compare instance_type.
  3. Find that [1] has t3.large while the code says t3.medium.
  4. terraform plan shows ~ instance_type = "t3.large" -> "t3.medium" for that instance, which will be corrected by apply.

Why not the alternatives. Looking at the cloud console works but cannot show what Terraform believes; state show reveals the state record, and the plan reveals the difference with the code.

7c. Verbose logging with TF_LOG

When a plan or apply fails with an unclear message, enable logging.

Bash
export TF_LOG=TRACE
export TF_LOG_PATH=./terraform-debug.log
terraform apply

Log levels from most to least verbose: TRACE, DEBUG, INFO, WARN, ERROR. TRACE is the most detailed. If TF_LOG is set to an invalid value, Terraform uses TRACE. To disable logging, unset the variable (unset TF_LOG).

Variable Purpose
TF_LOG Turns on logging for Terraform core and providers at the given level
TF_LOG_PATH Writes logs to a file instead of standard error
TF_LOG_CORE Sets the level for Terraform core only
TF_LOG_PROVIDER Sets the level for providers only
TF_INPUT=0 Disables prompts (useful in CI, not logging)

Practical advice:

  • Provider problems (API errors, authentication failures) are best investigated with TF_LOG_PROVIDER=DEBUG so that core noise is hidden.
  • Logs may contain credentials, request bodies and resource attributes. Never share a raw trace in a public issue without redacting it, and delete log files once the problem is solved.
  • To report a bug to HashiCorp or a provider maintainer, attach the TRACE log (redacted).

Worked example: diagnosing an authentication error

Scenario. terraform apply fails with Error: reading EC2 Instance: operation error EC2: DescribeInstances, https response error StatusCode: 403. The AWS CLI works on the same machine.

Step by step.

  1. Set TF_LOG_PROVIDER=DEBUG and TF_LOG_PATH=provider.log.
  2. Re-run terraform plan.
  3. In the log, find the credential chain: it shows that the provider assumed role terraform-ci from the AWS_PROFILE variable instead of the profile used by the CLI.
  4. Fix the environment, delete the log and re-run.

Related maintenance tasks

Importing many objects with for_each

A company that created twelve storage buckets by hand does not need twelve import blocks. A single block with for_each handles the whole set:

HCL
locals {
  legacy_buckets = {
    logs    = "acme-legacy-logs"
    exports = "acme-legacy-exports"
    media   = "acme-legacy-media"
  }
}

import {
  for_each = local.legacy_buckets
  to       = aws_s3_bucket.legacy[each.key]
  id       = each.value
}

resource "aws_s3_bucket" "legacy" {
  for_each = local.legacy_buckets
  bucket   = each.value
}

The plan reports three objects to import. If you add a fourth entry later, only that bucket is imported. This is the declarative advantage over running the command once per object.

Forcing replacement of a damaged object

Maintenance sometimes means rebuilding an object that is unhealthy even though Terraform believes it is fine, for example a virtual machine whose disk is corrupted. Use the -replace option rather than the older terraform taint:

Bash
terraform plan  -replace="aws_instance.web[1]"
terraform apply -replace="aws_instance.web[1]"

The plan shows the instance as "must be replaced, as requested", so the action is visible and reviewable. terraform taint marked the object in state immediately, which meant a teammate could apply the change by accident. It is deprecated in favour of -replace.

Understanding the graph and testing expressions

Two read-only helpers are useful during troubleshooting. terraform graph prints the dependency graph in DOT format, which shows why Terraform plans to create resources in a given order. terraform console opens an interactive prompt that evaluates expressions against the current configuration and state, so you can test cidrsubnet("10.0.0.0/16", 8, 2) or inspect aws_instance.web[0].private_ip without editing code.

A short troubleshooting routine

When a run fails or a plan surprises you, a good routine is:

  1. Read the error message fully; Terraform usually names the resource and the argument.
  2. Run terraform validate to catch syntax and reference problems.
  3. Use terraform state list and terraform state show to see what Terraform thinks exists.
  4. Run terraform plan -refresh-only to see whether reality has drifted.
  5. Enable TF_LOG_PROVIDER=DEBUG if the provider API call itself fails.
  6. Only then consider imports, moved blocks or -replace.

Following this order keeps you from making state changes before you understand the cause.

Common pitfalls and exam tips

  • Exam tip: import writes state only. It does not create, change or generate resources by itself. Only -generate-config-out produces configuration.
  • Exam tip: with the legacy terraform import command you need the resource block before running it.
  • Pitfall: importing without matching configuration, then running apply and being surprised that attributes are changed to defaults.
  • Pitfall: -generate-config-out pointing at an existing file; Terraform refuses to overwrite it.
  • Exam tip: TF_LOG accepts TRACE, DEBUG, INFO, WARN, ERROR; TRACE is the most verbose. TF_LOG_PATH sends output to a file.
  • Exam tip: terraform state list shows names; terraform state show shows attributes.
  • Pitfall: leaving debug logs with secrets on shared storage.
  • Exam tip: import brings an object into state in a state-modifying operation, so it also uses state locking.

Mini case study

Situation. A logistics company has a PostgreSQL database orders-prod created by hand, plus a parameter group and a subnet group. The platform team will manage them with Terraform. They write the aws_db_instance block and run terraform apply, and the apply fails with "DBInstanceAlreadyExists".

Questions. (1) Why did it fail? (2) What is the safe sequence? (3) What can help find the parameter group's settings?

Answer.

  1. Terraform does not know the database exists, since it is not in state; it tried to create a new one with the same name.
  2. Add import blocks for the instance, parameter group and subnet group, run terraform plan and fix differences until the plan shows only imports, then apply. Optionally draft code with -generate-config-out.
  3. Use -generate-config-out to draft the block, or terraform state show after the import to read the values Terraform recorded.

Key terms

  • Import: attaching an existing object to a resource address in state.
  • import block: declarative import, available since Terraform 1.5.
  • -generate-config-out: option that writes draft configuration for imported objects.
  • terraform state list / show: commands to inspect state.
  • TF_LOG: environment variable that sets the log level.
  • TF_LOG_PATH: file that receives log output.

Summary checklist

  • I can explain what import does and does not do.
  • I can write an import block and generate configuration with -generate-config-out.
  • I know that the legacy terraform import command needs the resource block first.
  • I can use state list, state show, show and output for inspection.
  • I can enable TF_LOG at a chosen level and redirect it with TF_LOG_PATH.
  • I know logs may contain secrets.

Official sources