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
importblock and useterraform plan -generate-config-out. - Use the legacy
terraform importCLI command and know how it differs. - Inspect state with
terraform state list,terraform state show,terraform showandterraform output. - Enable and direct verbose logs with
TF_LOG,TF_LOG_PATHandTF_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:
import {
to = aws_s3_bucket.logs
id = "acme-prod-logs"
}
resource "aws_s3_bucket" "logs" {
bucket = "acme-prod-logs"
}How it works:
tois the destination resource address;idis 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 planandterraform 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_eachis supported inimportblocks (since 1.7), which makes importing many similar objects practical. Theidcan be an expression.- Terraform 1.12 also allows importing by an
identityattribute for providers that support resource identities.identityandidcannot 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:
terraform plan -generate-config-out=generated.tfTerraform 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
importblocks that have no matchingresourceblock yet.
The terraform import command (imperative, legacy)
terraform import aws_s3_bucket.logs acme-prod-logsThe 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.
- Find the import ID in the provider documentation: for
aws_security_groupit is the group ID. - Add an import block:
import {
to = aws_security_group.partner_https
id = "sg-0a1b2c3d4e5f6a7b8"
}- Generate a draft:
terraform plan -generate-config-out=generated.tf. - Open
generated.tf, clean it up (for example, replace the hard-coded VPC ID withmodule.network.vpc_id), and move it intosecurity.tf. - Run
terraform plan. It shows1 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. - 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:
terraform state list
terraform state list module.network
terraform state list 'aws_instance.web[*]'Sample output:
aws_instance.web[0]
aws_instance.web[1]
module.network.aws_subnet.private["a"]
module.network.aws_vpc.thisterraform state show
Shows all attributes recorded for one resource, including computed ones:
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.
terraform state list | grep aws_instance.webreturns the three addresses.- For each,
terraform state show 'aws_instance.web[1]'and compareinstance_type. - Find that
[1]hast3.largewhile the code sayst3.medium. terraform planshows~ instance_type = "t3.large" -> "t3.medium"for that instance, which will be corrected byapply.
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.
export TF_LOG=TRACE
export TF_LOG_PATH=./terraform-debug.log
terraform applyLog 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=DEBUGso 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
TRACElog (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.
- Set
TF_LOG_PROVIDER=DEBUGandTF_LOG_PATH=provider.log. - Re-run
terraform plan. - In the log, find the credential chain: it shows that the provider assumed role
terraform-cifrom theAWS_PROFILEvariable instead of the profile used by the CLI. - 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:
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:
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:
- Read the error message fully; Terraform usually names the resource and the argument.
- Run
terraform validateto catch syntax and reference problems. - Use
terraform state listandterraform state showto see what Terraform thinks exists. - Run
terraform plan -refresh-onlyto see whether reality has drifted. - Enable
TF_LOG_PROVIDER=DEBUGif the provider API call itself fails. - Only then consider imports,
movedblocks 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-outproduces configuration. - Exam tip: with the legacy
terraform importcommand you need the resource block before running it. - Pitfall: importing without matching configuration, then running
applyand being surprised that attributes are changed to defaults. - Pitfall:
-generate-config-outpointing at an existing file; Terraform refuses to overwrite it. - Exam tip:
TF_LOGacceptsTRACE,DEBUG,INFO,WARN,ERROR;TRACEis the most verbose.TF_LOG_PATHsends output to a file. - Exam tip:
terraform state listshows names;terraform state showshows 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.
- Terraform does not know the database exists, since it is not in state; it tried to create a new one with the same name.
- Add
importblocks for the instance, parameter group and subnet group, runterraform planand fix differences until the plan shows only imports, then apply. Optionally draft code with-generate-config-out. - Use
-generate-config-outto draft the block, orterraform state showafter the import to read the values Terraform recorded.
Key terms
- Import: attaching an existing object to a resource address in state.
importblock: 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
importblock and generate configuration with-generate-config-out. - I know that the legacy
terraform importcommand needs the resource block first. - I can use
state list,state show,showandoutputfor inspection. - I can enable
TF_LOGat a chosen level and redirect it withTF_LOG_PATH. - I know logs may contain secrets.
Official sources
- https://developer.hashicorp.com/terraform/language/import (opens in a new tab)
- https://developer.hashicorp.com/terraform/language/import/generating-configuration (opens in a new tab)
- https://developer.hashicorp.com/terraform/cli/state/inspect (opens in a new tab)
- https://developer.hashicorp.com/terraform/internals/debugging (opens in a new tab)
- https://developer.hashicorp.com/terraform/tutorials/certification-004/associate-review-004 (opens in a new tab)
