Skip to content

Terraform state and modules

Terraform’s plan is only as good as its memory of what it already built. That memory is the state file, and most production incidents with Terraform trace back to state: two people applying at once, a state file lost or leaked, or a refactor that made Terraform think a database should be destroyed. This page covers state from first principles to day-two operations, then modules, which let teams reuse the same infrastructure shape without copying it.

Read Terraform basics and the core workflow first if init, plan and apply are new to you. All complete samples on this page were run with Terraform 1.17.2 on Linux using the built-in terraform_data resource, so they need no cloud account. Backend samples that need a cloud account are marked as not run.

Topic What it answers
Why state exists What the state file stores and why Terraform cannot work without it.
Remote state and locking Where shared state should live and how locking prevents concurrent applies.
Inspecting and importing state Reading state and bringing existing resources under management.
Refactoring with moved and removed blocks Renaming and reorganizing code without destroying resources.
Workspaces What CLI workspaces are for and what they are not for.
Modules Packaging a reusable infrastructure pattern with inputs and outputs.
Module sources and versions Where modules come from and how to pin them.

Terraform state is a JSON document that maps each resource address in your configuration (terraform_data.web[0], module.web.aws_instance.app) to the real object it manages, with that object’s last known attributes. It also records dependencies and outputs.

Terraform needs this mapping for three reasons. First, identity: a cloud API knows about an instance with ID i-0abc, but nothing in the API says “this is OrdersPortal’s web server number one”. State is where that link lives. Second, diffing: to plan, Terraform compares configuration with state and with a refresh of the real objects, and only then can it say “update this tag” rather than “create another server”. Third, performance and ordering: state records dependencies so Terraform can destroy resources in the right order even after their configuration is deleted.

By default Terraform writes terraform.tfstate in the working directory. That is fine for learning and for throwaway environments; for anything shared it is a liability, because the file lives on one laptop and has no locking.

State also contains secrets. Marking a variable sensitive hides it from CLI output, but the value is still written to state if a resource stores it. This run shows the difference:

main.tf
variable "db_password" {
type = string
sensitive = true
}
resource "terraform_data" "db" {
input = {
name = "ordersportal-staging-db"
password = var.db_password
}
}
output "db_name" {
value = terraform_data.db.output.name
}
Terminal window
TF_VAR_db_password='S3cret-Example' terraform apply -auto-approve
grep -c 'S3cret-Example' terraform.tfstate
+ password = (sensitive value)
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
db_name = "ordersportal-staging-db"
2

The plan redacts the value, yet the state file contains it twice. Terraform 1.10 and later add ephemeral variables and outputs, and 1.11 and later add write-only resource arguments, which keep a value out of state entirely when the provider supports them.

Pitfalls:

  • Committing state to Git. It leaks secrets and guarantees conflicts. Add *.tfstate and *.tfstate.* to .gitignore.
  • Editing the JSON by hand. Use terraform state commands or configuration blocks; a hand edit can corrupt serial numbers and lineage.

A backend decides where state is stored. For teams, use a remote backend: an object store such as Amazon S3, Azure Blob Storage or Google Cloud Storage, or HCP Terraform. Remote state gives everyone the same source of truth, keeps the file off laptops, and can be encrypted at rest and access-controlled.

Locking is the other half. While a plan or apply runs, Terraform takes a lock on the state so a second run waits or fails instead of writing a conflicting version. Most remote backends lock automatically. The S3 backend has native locking that you turn on with use_lockfile = true, which writes a .tflock object next to the state; the older DynamoDB-based locking (dynamodb_table) is deprecated.

A typical configuration keeps the backend block generic and supplies the environment-specific values at init time, which Terraform calls a partial configuration. This sample is not run here because it needs an AWS account:

backend.tf
terraform {
backend "s3" {
bucket = "ordersportal-terraform-state"
region = "eu-west-2"
use_lockfile = true
encrypt = true
}
}
Terminal window
terraform init -backend-config="key=ordersportal/staging/terraform.tfstate"

Enable versioning on the bucket so you can recover an earlier state after a mistake, and restrict who can read it: anyone who can read state can read every secret in it.

If a run crashes and leaves a lock behind, terraform force-unlock <LOCK_ID> releases it. Use it only after confirming no other run is active, because it removes the protection against concurrent writes.

Pitfalls:

  • Sharing one state for unrelated systems. Large states make plans slow and widen the blast radius. Split state by lifecycle and ownership: network, shared data stores, each application.
  • Reading another team’s state directly. The terraform_remote_state data source exposes the whole state. Prefer publishing the few values others need (for example in a parameter store) or reading them with provider data sources.

The terraform state subcommands read and adjust state without touching real infrastructure:

Terminal window
terraform state list
terraform state show 'module.web.terraform_data.server["web-1"]'
module.web.terraform_data.server["web-1"]
module.web.terraform_data.server["web-2"]

state show prints the stored attributes of one instance, which is the quickest way to answer “what does Terraform think this resource looks like?”. terraform state rm makes Terraform forget an object without destroying it, and terraform state mv changes an address; both are now usually better expressed as configuration blocks (next section), because blocks are reviewed in a merge request and work in every environment that applies the code.

To adopt a resource that already exists, for example a storage account someone created in the portal, add an import block and a matching resource block, then plan. This fragment is not run here because it needs an Azure subscription:

import {
to = azurerm_resource_group.ordersportal
id = "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ordersportal-staging"
}
resource "azurerm_resource_group" "ordersportal" {
name = "ordersportal-staging"
location = "westeurope"
}

The plan shows the resource as “will be imported” and any differences between your configuration and the real object. terraform plan -generate-config-out=generated.tf (still marked experimental in the documentation) can write a first draft of the resource block for you to clean up.

Pitfalls:

  • Importing into the wrong environment’s state. The import block applies wherever the configuration is applied; check the backend key before you apply.
  • Accepting generated configuration as is. Generated blocks include every attribute, including defaults; trim them so future diffs stay readable.

Renaming a resource, switching from count to for_each, or moving resources into a module changes their addresses. Without help, Terraform sees one address disappear and another appear, and plans a destroy and a create. For a database that means data loss.

A moved block tells Terraform that an old address is now a new one. In this OrdersPortal sample the configuration started as two counted resources in the root module:

main.tf
resource "terraform_data" "web" {
count = 2
input = "ordersportal-staging-web-${count.index + 1}"
}

The refactor moves them into a module that uses for_each with stable keys, and records the moves:

main.tf
module "web" {
source = "./modules/web_tier"
name_prefix = "ordersportal-staging"
server_keys = ["web-1", "web-2"]
}
moved {
from = terraform_data.web[0]
to = module.web.terraform_data.server["web-1"]
}
moved {
from = terraform_data.web[1]
to = module.web.terraform_data.server["web-2"]
}
output "web_server_names" {
value = module.web.server_names
}

After terraform init (needed because a module was added), the plan contains no create or destroy:

# terraform_data.web[0] has moved to module.web.terraform_data.server["web-1"]
# terraform_data.web[1] has moved to module.web.terraform_data.server["web-2"]
Plan: 0 to add, 0 to change, 0 to destroy.

Keep moved blocks until every environment and every consumer of a shared module has applied them; then they can be removed.

A removed block is the configuration form of state rm: it removes a resource from management, and with lifecycle { destroy = false } it leaves the real object in place. It addresses a whole resource, not a single instance: Terraform 1.17 rejects from = module.web.terraform_data.server["web-2"] with “Resource instance keys not allowed”.

removed {
from = terraform_data.legacy_reports
lifecycle {
destroy = false
}
}

Pitfalls:

  • Refactoring and changing behavior in the same merge request. Make the address change with moved blocks first, confirm a plan of zero changes, then change arguments separately.
  • Deleting moved blocks too early. An environment that has not applied the move yet will plan a destroy and create.

CLI workspaces let one working directory hold several named states (terraform workspace new staging, terraform workspace select staging), and the configuration can read terraform.workspace. They are useful for short-lived copies of the same infrastructure, such as a test environment per feature branch.

HashiCorp’s documentation is explicit that workspaces are not appropriate for system decomposition or for deployments that need separate credentials and access controls. Production and staging usually differ in exactly those ways, so most teams give each long-lived environment its own backend key or its own root configuration instead. HCP Terraform also uses the word “workspace”, but there it means a separate unit with its own state, variables and permissions, which is a different concept.

Pitfalls:

  • Forgetting which workspace is selected. A plan against the wrong workspace looks plausible. Print terraform workspace show in pipeline logs.
  • Encoding environment differences with terraform.workspace conditionals everywhere. Per-environment variable files are easier to review.

A module is a folder of .tf files. Every configuration is a module (the root module), and a module block calls another one as a child. Modules let you write a pattern once, such as “a web tier with N servers, a load balancer and the right tags”, and reuse it across environments and applications. They also create a boundary: a platform team can own the module and its defaults while application teams set a handful of inputs.

A good module has a small, typed interface. The web tier module used in the refactoring sample has two inputs and one output:

modules/web_tier/variables.tf
variable "name_prefix" {
type = string
description = "Prefix for every server name, for example ordersportal-staging."
}
variable "server_keys" {
type = set(string)
description = "Stable keys for the servers in this tier."
}
modules/web_tier/main.tf
resource "terraform_data" "server" {
for_each = var.server_keys
input = "${var.name_prefix}-${each.key}"
}
modules/web_tier/outputs.tf
output "server_names" {
description = "Names of the servers in this tier."
value = sort([for s in terraform_data.server : s.output])
}

After terraform apply in the root, the output is:

web_server_names = [
"ordersportal-staging-web-1",
"ordersportal-staging-web-2",
]

The caller cannot reach into the module’s resources; it sees only outputs. That is deliberate: it lets the module author change internals without breaking callers.

Prefer composition over deep nesting. A root configuration that calls network, database and web_tier modules and wires their outputs together is easier to understand than a single “everything” module with fifty inputs and feature flags.

Pitfalls:

  • Thin wrapper modules. A module that wraps one resource and passes every argument through adds indirection without adding a decision. Write a module when it encodes a standard: naming, tagging, security defaults.
  • Provider blocks inside reusable modules. Configure providers in the root module and pass them in; a module with its own provider configuration cannot be used with count, for_each or depends_on.

The source argument says where a module comes from: a local path (./modules/web_tier), the public Terraform Registry (<namespace>/<name>/<provider>), a private registry in HCP Terraform, a Git repository (git::https://example.test/platform/terraform-modules.git//web_tier?ref=v1.4.0), or an archive in object storage. terraform init downloads remote modules into .terraform/modules.

Pin versions. For registry modules, use the version argument with a constraint such as ~> 5.2; for Git sources, use a tag in ref. An unpinned module means a plan can change because someone published a new version, not because you changed anything.

This fragment uses an invented private registry module and is not run here:

module "network" {
source = "app.terraform.io/example-org/ordersportal-network/aws"
version = "~> 2.1"
name = "ordersportal-staging"
cidr = "10.20.0.0/16"
}

Version the modules you publish with semantic versioning, write a changelog, and test them. terraform test runs .tftest.hcl files that plan or apply a module with given inputs and assert on the results.

Pitfalls:

  • Pointing at a branch. ref=main is a moving target; use tags.
  • Breaking changes without moved blocks. If a new module version renames resources, ship moved blocks inside the module so callers upgrade without replacements.
Situation Use
A team shares an environment Remote backend with locking and bucket versioning
You rename or reorganize resources moved blocks, then a zero-change plan
A resource exists but Terraform does not know it An import block
Terraform should stop managing a resource but keep it A removed block with destroy = false
You need a temporary copy of the same stack A CLI workspace
The same infrastructure shape repeats A module with a small typed interface, pinned by version

What would happen if you deleted the state file of a running environment? Terraform would no longer know it manages those resources. The next plan would propose creating everything again, which fails on name conflicts or creates duplicates. Recovery means restoring a previous state version (hence bucket versioning) or importing each resource.

Why is state considered sensitive? It stores resource attributes in plain text, including passwords, keys and connection strings that resources return or receive. sensitive = true only redacts CLI output. Protect state with encryption and access control, and use ephemeral values or write-only arguments where providers support them.

How does state locking work, and when would you use force-unlock? Before a write operation, Terraform acquires a lock in the backend; a second run sees the lock and stops. force-unlock removes a stale lock left by a crashed run, and should be used only after confirming no other run is in progress.

What is the difference between terraform state mv and a moved block? Both change a resource’s address in state. state mv is an imperative command run once against one state. A moved block is code: it is reviewed, applies in every environment, and can ship inside a module so consumers upgrade safely.

Senior scenario: three product teams copy-paste the same 400 lines of networking and database Terraform. How would you consolidate it? Extract a versioned module with a narrow interface (names, sizes, environment) and opinionated defaults for tagging, encryption and logging. Publish it to a private registry or tagged Git repository with a changelog and terraform test coverage. Migrate one team at a time: replace their resources with a module call plus moved blocks, and require a plan with zero changes before merging. Keep separate state per team and environment, and add policy checks in the pipeline so new code uses the module.