Removing one depot restarts three CHG-5188

Describe the end state, let the tool compute the change, and understand what "converge" really promises.

Two ways to say what you want

There are two broad ways to automate infrastructure. A procedural script lists steps: create a network, create three servers, attach them. Run it twice and you get six servers, unless you write all the checking yourself. A declarative configuration describes the end state: "there are three servers of this size on this network". A tool compares that description with reality and computes the steps.

Terraform: Up & Running opens with this comparison, together with two others that shape tool choice. Configuration management versus provisioning separates configuring software on existing hosts (Ansible, Puppet, Chef) from creating the hosts, networks, and services themselves (Terraform, OpenTofu, CloudFormation). Mutable versus immutable separates changing servers in place from replacing them with new ones built from an updated image. Most real platforms combine them, for example Terraform to provision, an image pipeline for immutable hosts, and Ansible where in-place configuration is still needed.

Plan, then apply

The declarative cycle has three steps:

1. Refresh: read the real state of every managed resource through the provider's API.
2. Plan: compare real state with the configuration and produce a list of actions. Symbols mark each one: + create, ~ update in place, -/+ destroy and re-create, - destroy.
3. Apply: execute those actions in dependency order.

The plan is the most important artifact in infrastructure as code. It is the change request a reviewer should read, more than the diff of the code, because small code changes can produce large plans. The “Reading plans and refactoring safely” notes are devoted to reading them.

Idempotence and convergence

A good declarative run is idempotent. Applying the same configuration again changes nothing, and plan reports "No changes". That property is what makes automation safe to re-run after a failure, on a schedule, or from CI. It is also a test. If a second plan immediately after an apply still shows changes, something is fighting the tool, such as a provider bug, a value computed differently each time, or another system modifying the resource.

Drift

When someone changes managed infrastructure by hand, reality drifts from the code. The next refresh notices, and the plan proposes changing it back. That is a decision point, not an automatic correction. If the manual change was an emergency fix that should stay, update the code. If it was a mistake, let the apply revert it. Running plans regularly, for example nightly in CI, turns drift from an occasional surprise into a routine report.

Providers and the graph

The core engine knows nothing about clouds. Providers implement create, read, update, and delete for each resource type against an API. The engine builds a dependency graph from references between resources (a server referencing a network's ID depends on that network), and that graph decides the order of operations and what can run in parallel. Understanding that references create dependencies explains most ordering questions, and the rare need for an explicit depends_on.

Key terms

Desired state

A description of how infrastructure should be, as opposed to the steps to make it so.

Plan

The computed difference between desired state and real state. It lists what will be created, changed, replaced, or destroyed.

Idempotence

Applying the same configuration twice has the same effect as applying it once. The second run changes nothing.

Drift

Real infrastructure that no longer matches the code, usually because someone changed it by hand.

Read further

• Terraform Up & Running, 3rd edition, Ch. 1, "Why Terraform" (Purchase)
  The comparison of configuration management and provisioning tools, mutable and immutable infrastructure, procedural and declarative languages, and the argument for declarative provisioning.
• Terraform Up & Running, 3rd edition, Ch. 2, "Getting Started with Terraform" (Purchase)
  Providers, resources, plan and apply, variables and outputs. Run the examples locally if you can, or read the plan output carefully.
• UNIX and Linux System Administration Handbook, 5th edition, Ch. 23, "Configuration Management" (Purchase)
  The general concepts (operations, variables, facts, change handlers) and the comparison of tools. It shows that these ideas predate any one product.

Small code changes can produce destructive plans. Learn why addresses, `count`, and renames cause replacements, and how to refactor without them.

The plan is the change

A code diff can look harmless while its plan destroys production. Reviewing infrastructure changes means reading the plan, not just the code. Read it in this order:

1. The summary line: Plan: 3 to add, 1 to change, 2 to destroy. Any destroy deserves an explanation.
2. Every -/+ (replace) and - (destroy) on a stateful resource, such as databases, volumes, buckets, and DNS zones.
3. The reason for each replacement. The plan marks the attribute with # forces replacement, or shows that the address itself changed.

The rule: no destroy or replace of stateful resources is approved unless the PR description says why and how data is preserved.

Identity is the address

The tool identifies each resource by its address in the code: aws_db_instance.ledger, module.ledger.aws_db_instance.main, aws_instance.scanner[2], or aws_instance.scanner["depot-3"]. State maps addresses to real objects. Consequences:

• Renaming a resource changes its address.
• Moving it into a module changes its address.
• Reordering a count-based list changes the addresses of everything after the change.

To the tool, a new address with no state entry is a new object to create, and an old address in state that no longer appears in the code is an object to destroy. Without help, every "tidy" refactor is a destroy and re-create.

count versus for_each

Terraform: Up & Running's loops chapter shows the trap. count creates resource[0], resource[1], and so on, indexed by position. Remove depot-2 from the middle of a list and depot-3 slides from index 2 to index 1. The plan then updates or replaces the depots after it to match their new positions, and destroys the last index. Three depots restart because one was decommissioned.

for_each over a set or map addresses by key: scanner["depot-3"] stays scanner["depot-3"] whatever else changes. Use count only for identical, interchangeable copies (or as an on/off switch with 0 or 1), and for_each for anything with a name. Converting an existing count resource to for_each itself changes addresses, which brings us to moved.

Refactoring with moved blocks

A moved block tells the tool that the object at one address now lives at another:

moved {
  from = aws_db_instance.ledger
  to   = module.ledger.aws_db_instance.main
}

moved {
  from = aws_instance.scanner[2]
  to   = aws_instance.scanner["depot-3"]
}

The next plan shows the object as moved and updates state, with no destroy and no create. Re-plan after adding them. A correct refactor plans as zero changes apart from the intended ones. Older workflows did the same with state mv commands run by hand. moved blocks are better because they are reviewed in the PR and applied consistently by every environment's pipeline.

Guardrails

• lifecycle { prevent_destroy = true } on resources whose loss is unacceptable. Any plan that would destroy them fails.
• Provider-side deletion protection (most databases and buckets offer it), which also stops deletion from consoles and scripts.
• create_before_destroy for resources that can briefly coexist, to avoid downtime on replacement.
• Apply the reviewed plan: plan -out=tfplan, review, then apply tfplan. If state changed in between, the apply refuses instead of doing something nobody reviewed.

Key terms

Resource address

The identity of a resource in code, such as module.ledger.aws_db_instance.main or aws_instance.scanner["depot-3"].

Replacement

Destroy and re-create (-/+), either because an attribute cannot change in place or because the address changed.

moved block

A declaration telling the tool that an object at an old address now lives at a new one, so it updates state instead of replacing.

prevent_destroy

A lifecycle setting that makes any plan that would destroy the resource fail.

Read further

• Terraform Up & Running, 3rd edition, Ch. 4, "How to Create Reusable Infrastructure with Terraform Modules" (Purchase)
  Module inputs, outputs, and versioning. Note how moving a resource into a module changes its address.
• Terraform Up & Running, 3rd edition, Ch. 5, "Terraform Tips and Tricks — Loops, If-Statements, Deployment, and Gotchas" (Purchase)
  count versus for_each (especially the limitation when removing an item from the middle of a list), zero-downtime deployment, and the gotchas section on refactoring and on valid plans that still fail.