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.
Topics on this page
Section titled “Topics on this page”| 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. |
Why state exists
Section titled “Why state exists”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:
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}TF_VAR_db_password='S3cret-Example' terraform apply -auto-approvegrep -c 'S3cret-Example' terraform.tfstate + password = (sensitive value)Apply complete! Resources: 1 added, 0 changed, 0 destroyed.db_name = "ordersportal-staging-db"2The 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
*.tfstateand*.tfstate.*to.gitignore. - Editing the JSON by hand. Use
terraform statecommands or configuration blocks; a hand edit can corrupt serial numbers and lineage.
Remote state and locking
Section titled “Remote state and locking”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:
terraform { backend "s3" { bucket = "ordersportal-terraform-state" region = "eu-west-2" use_lockfile = true encrypt = true }}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_statedata 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.
Inspecting and importing state
Section titled “Inspecting and importing state”The terraform state subcommands read and adjust state without touching real infrastructure:
terraform state listterraform 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.
Refactoring with moved and removed blocks
Section titled “Refactoring with moved and removed blocks”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:
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:
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
movedblocks first, confirm a plan of zero changes, then change arguments separately. - Deleting
movedblocks too early. An environment that has not applied the move yet will plan a destroy and create.
Workspaces
Section titled “Workspaces”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 showin pipeline logs. - Encoding environment differences with
terraform.workspaceconditionals everywhere. Per-environment variable files are easier to review.
Modules
Section titled “Modules”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:
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."}resource "terraform_data" "server" { for_each = var.server_keys input = "${var.name_prefix}-${each.key}"}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_eachordepends_on.
Module sources and versions
Section titled “Module sources and versions”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=mainis a moving target; use tags. - Breaking changes without
movedblocks. If a new module version renames resources, shipmovedblocks inside the module so callers upgrade without replacements.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Terraform section start: reading path for the section.
- Terraform basics and the core workflow: configuration blocks, init, plan and apply.
- GitLab CI/CD pipelines: running Terraform with protected variables and approvals.
- Ansible automation: configuring servers after Terraform creates them.