Terraform State and Modules

State, workspaces, modules, refactoring (moved, removed, import blocks), targeted runs and terraform test. Use it after the basics in Terraform.

Documentation: Terraform State, Modules, Refactoring, Tests

Verification: commands, flags and HCL blocks were run with Terraform 1.17.1 on small local-only configurations (terraform_data resource and a local module, no cloud provider, no remote backend). terraform -help output was used for flags. Remote backends, registry and Git module sources, and -target against real infrastructure were not run. OpenTofu was not run: its differences are not covered here (unverified).

State #

State maps your configuration to real objects. It can hold secrets in plain text, so keep it out of Git and use a remote backend with locking for shared work.

Addresses look like aws_instance.web, aws_instance.web[0], aws_instance.web["key"] and module.<NAME>.aws_instance.web. Quote addresses containing ["key"] in the shell.

Backend Changes #

Workspaces #

Workspaces give one configuration several separate state files within the same backend. They are not a substitute for separate accounts or environments with different access.

resource "terraform_data" "env" {
  input = terraform.workspace == "prod" ? "large" : "small"
}

terraform.workspace gives the current name. The default workspace is called default and cannot be deleted.

Modules #

A module is a directory of .tf files. The root module calls child modules.

module "app" {
  source = "./modules/app"      # local path
  name   = var.name
}

module "net" {
  source  = "terraform-aws-modules/vpc/aws"   # registry: NAMESPACE/NAME/PROVIDER
  version = "~> 5.0"                          # pin registry modules
}

module "git" {
  source = "git::https://example.com/org/repo.git//modules/app?ref=v1.2.0"
}

output "app_id" {
  value = module.app.id
}

Inside the module, declare inputs with variable, results with output, and reference them as module.<NAME>.<OUTPUT>. Registry and Git sources above are illustrative and were not downloaded (unverified).

Refactoring Without Destroying #

Rename or restructure in code, then record the change so Terraform does not plan a destroy and create. These blocks need a recent Terraform (the removed block needs 1.7 or later).

moved {
  from = terraform_data.old_name
  to   = terraform_data.new_name
}

moved {
  from = module.old
  to   = module.new
}

removed {
  from = terraform_data.legacy
  lifecycle {
    destroy = false    # forget it, do not destroy the real object
  }
}

import {
  to = terraform_data.imported
  id = "EXISTING_ID"    # the provider's import ID, see the resource docs
}

Targeting and Replacing #

-target is for recovery and exceptional cases: Terraform warns that the result may be incomplete and state can drift from code. Run a full plan afterwards.

Terraform Test #

Test files end in .tftest.hcl and live next to the configuration or in a tests/ directory. Each run block executes a plan or apply and checks assertions. Resources created by command = apply are destroyed when the file finishes.

variables {
  name = "demo"
}

run "applies" {
  command = apply      # or plan (the default is apply)
  assert {
    condition     = module.app.id != ""
    error_message = "module output is empty"
  }
}

run "rejects_empty_name" {
  command = plan
  variables {
    name = ""
  }
  expect_failures = [var.name]    # passes only if the validation fails
}

With command = plan, a condition that depends on a value only known after apply fails with “Unknown condition value”. Use command = apply for those checks.

Good Practice #

• Take terraform state pull > backup.tfstate before state mv, state rm or state push.
• Prefer moved, removed and import blocks over CLI state edits: they are reviewable in a pull request.
• Run terraform plan -detailed-exitcode in CI to catch drift.
• Pin module versions and commit .terraform.lock.hcl.
• Keep -target out of routine pipelines.

OpenTofu #

tofu accepts the same subcommands used here, but its feature set has diverged from Terraform’s since the fork (it adds features such as state encryption, unverified here). Check the OpenTofu docs for each block and flag before relying on it: not verified here.

See Also #

• Terraform
• Ansible Cheat-Sheet
• Packer