Terraform’s state is how it “remembers” what exists in your infrastructure so it can plan precise, minimal changes instead of blindly recreating resources. In this article, we’ll treat Terraform as a black box and learn how to inspect its memory using three key CLI tools: terraform show, the terraform state subcommands, and terraform output.
1. What Terraform State Actually Is
Terraform keeps a mapping between:
- Your configuration (
.tffiles) - The real resources in your cloud provider (IDs, IPs, ARNs, etc.)
This mapping lives in a state file, usually terraform.tfstate, and often in a remote backend such as S3, Azure Blob Storage, or GCS for team use. The state includes every attribute of every managed resource, plus metadata used for things like dependency ordering and change detection.
Why you care:
- Debugging: Is Terraform seeing the same thing you see in the console?
- Refactoring: How do you rename resources without destroying them?
- Automation: How do you feed outputs into CI/CD or other tools?
You should never hand-edit the state file; instead you use the CLI commands discussed below to read or safely modify it.
2. terraform show — Inspecting the Whole State or a Plan
Think of terraform show as “dump what Terraform currently knows” — it turns a state file or a saved plan into a human-readable or JSON view.
Core usage
# Show the current state snapshot (from the active backend)
terraform show
# Show a specific state file
terraform show path/to/terraform.tfstate
# Show a saved plan file
terraform show tfplan
# Machine-readable JSON for tooling
terraform show -json > plan.json- Without a file argument,
terraform showprints the latest state snapshot from the active backend. - With a plan file, it describes the proposed actions and resulting state.
- With
-json, you get a structured document that external tools (e.g. CI, tests) can parse and validate.
Important: When using
-json, sensitive values are printed in plain text; handle this carefully in pipelines and logs.
When to use terraform show
Use it when:
- You want a global view: “What exactly is Terraform tracking right now?”
- You want to inspect a plan artifact (
plan -out tfplan) before approving it in CI. - You want to feed state or plan data into a tool (via
-json) for policy checks, drift checks, or custom validation.
Conceptually, terraform show is read-only and holistic: it treats the state (or plan) as a whole, rather than individual resources.
3. terraform state — Fine-Grained State Inspection and Surgery
The terraform state command is a group of subcommands designed specifically to inspect and modify state without touching real infrastructure. This is the surgical toolkit you reach for when refactoring or repairing.
Key subcommands
| Command | What it does | Typical use |
|---|---|---|
terraform state list |
Lists all resource addresses in state | “What is Terraform tracking?” |
terraform state show ADDRESS |
Shows attributes of one resource | Debugging one resource (IDs, IPs, tags, etc.) |
terraform state mv SRC DEST |
Moves/renames a resource in state | Refactors config without destroy/recreate |
terraform state rm ADDRESS |
Removes a resource from state | Stop managing a resource without deleting it |
terraform state pull |
Prints raw state to stdout | Backup, inspection, or external processing |
terraform state push |
Uploads a local state file | Restore/correct broken remote state (used rarely, carefully) |
3.1 terraform state list
terraform state list
# e.g.
# aws_instance.web[0]
# aws_instance.web[1]
# aws_security_group.allow_sshThis gives you the resource addresses Terraform knows about, optionally filtered by a prefix. It’s extremely useful when working with modules or count/for_each, because you can see the exact address Terraform expects.
3.2 terraform state show
terraform state show aws_instance.web[0]This prints every attribute of that specific resource as seen in state — IDs, IPs, tags, relationships, and computed attributes. Semantically, it answers: “What does Terraform think this one resource looks like?”.
Use it when:
- Debugging drift: console vs state mismatch.
- Understanding complex resources: which subnet, which IAM role?
- Checking data sources that were resolved at apply time.
Note the difference:
terraform show→ everything (or full plan).terraform state show ADDRESS→ one resource only.
3.3 terraform state mv — Refactor Without Downtime
terraform state mv aws_instance.web aws_instance.appIf you simply rename the block in your .tf code, Terraform will plan to destroy the old resource and create a new one because it assumes they’re unrelated. state mv tells Terraform that the underlying resource is the same, you’re just changing the mapping.
This is critical for:
- Renaming resources.
- Moving resources into/out of modules.
- Splitting a monolith configuration into multiple modules/workspaces.
3.4 terraform state rm — Stop Managing Without Deleting
terraform state rm aws_instance.legacyThis removes the resource from Terraform’s management while leaving it alive in your provider. Use this when decommissioning Terraform from part of your estate or when you temporarily need Terraform to “forget” something (e.g. migration to a different tool).
3.5 terraform state pull / push
These expose and manipulate the raw state blob:
terraform state pull > backup.tfstate
terraform state push backup.tfstateThey’re useful for backups or extremely rare recovery scenarios, but they’re dangerous if misused, so in practice you rely much more on list, show, mv, and rm.
4. terraform output — Consuming State Safely
terraform output reads output values defined in the root module and prints their values from the state file. It is the “official interface” for other systems (and humans) to consume selected bits of state without parsing the state file directly.
4.1 Defining outputs in configuration
In your root module:
output "instance_ips" {
value = aws_instance.web[*].public_ip
}
output "lb_address" {
value = aws_lb.web.dns_name
}
output "db_connection_string" {
value = module.database.connection_string
sensitive = true
}- Outputs are calculated after
terraform applyand stored in state. - Only root module outputs are visible to
terraform output; child module outputs must be re-exposed.
4.2 Using terraform output interactively
# Show all outputs for the root module
terraform output
# Show one specific output
terraform output lb_address
# Machine-readable JSON
terraform output -json
# Raw string (no quotes/newlines), perfect for scripts
terraform output -raw lb_address- With no arguments, it prints all root outputs.
- With a
NAME, it prints just that value. -jsongives a JSON object keyed by output name; can be piped intojqor similar tools.-rawprints a bare string/number/boolean; ideal when exporting in shell scripts without extra quoting.
This is the idiomatic way to feed state into:
- CI/CD pipelines (e.g. get ALB DNS for integration tests).
- Other scripts (e.g. configure DNS records).
- Other tools (e.g. Ansible inventory).
5. Putting It Together: A Simple Example
Below is a minimal, self-contained configuration you can run locally.
5.1. Prerequisites
-
LocalStack running (Docker is typical):
docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstackLocalStack’s edge endpoint is exposed on
http://localhost:4566by default. -
Terraform installed (1.x).
5.2. Terraform Configuration Using LocalStack
Create a directory (for example tf-localstack-ec2) and within it create two files: versions.tf and main.tf.
versions.tf
Lock AWS provider to a version that is known to work well with LocalStack (4.x is a common choice):
terraform {
required_version = ">= 1.6.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}main.tf
provider "aws" {
region = "us-east-1"
access_key = "test"
secret_key = "test"
skip_credentials_validation = true
skip_metadata_api_check = true
skip_requesting_account_id = true
endpoints {
ec2 = "http://localhost:4566"
}
}
resource "aws_instance" "web" {
ami = "ami-12345678"
instance_type = "t3.micro"
tags = {
Name = "tf-demo-web-localstack"
}
}
output "web_public_ip" {
value = aws_instance.web.public_ip
}Notes:
- The
endpoints.ec2block points the EC2 API at LocalStack’s edge endpoint. - Credentials are dummy; LocalStack doesn’t actually validate them.
- The AMI ID is a placeholder; LocalStack typically does not require the AMI to exist, but EC2 support is limited and can hang for some combinations. For state/command learning it’s usually enough that Terraform “thinks” it created something.
5.3. How to Apply and Validate
From the directory containing these files:
-
Initialize and apply
terraform init terraform apply -auto-approveTerraform will talk to LocalStack instead of AWS because of the custom endpoint.
-
Validate with
showterraform showConfirm there is a
aws_instance.webblock with attributes populated from LocalStack’s response. -
Validate with
stateterraform state list # should include: # aws_instance.web terraform state show aws_instance.webThis tells you what Terraform’s state holds for this specific resource address.
-
Validate with
outputterraform output web_public_ip terraform output -raw web_public_ipFor LocalStack, the public IP may be empty or synthetic depending on EC2 emulation level, but the command proves the wiring from resource → state → output.
5.4. Rationale for These Choices
- We override only the EC2 endpoint to keep the example close to “real” AWS code while still talking to LocalStack.
- We relax provider validations (
skip_*flags) because LocalStack does not implement all AWS account/metadata APIs.
With this setup, you can safely experiment with terraform show, terraform state *, and terraform output on your laptop, without touching real AWS accounts or incurring cost.
6. Conceptual Summary: Which Command When?
| Need | Command | Rationale |
|---|---|---|
| See everything Terraform knows | terraform show |
Whole-state, read-only view (or a plan) |
| Inspect one resource deeply | terraform state show ADDRESS |
Focused, per-resource state inspection |
| List all tracked resources | terraform state list |
Discover resource addresses in state |
| Rename/move resources/modules | terraform state mv |
Refactor mappings without downtime |
| Forget a resource but keep it alive | terraform state rm |
Stop managing without deleting |
| Give other tools a clean interface | terraform output / -json / -raw |
Official way to expose selected state data developer. |
The underlying rationale is separation of concerns:
terraform show→ observability of plans and state.terraform state→ precise manipulation and inspection of state.terraform output→ controlled, stable API to state for humans and downstream systems.
Recent Comments