Dependency Graph and Plan

An implicit dependency exists whenever an argument of one block contains a reference to another object. Writing docker_network.bookshelf.name inside the container tells Terraform two things at once: it needs the value, and it must therefore create the network first. This is the preferred form because the dependency is derived from the data that is actually used, so it cannot drift away from the code.

Source: Terraform Docs — Resource behavior, resource dependencies and Docker provider documentation.

Three details are worth remembering. A reference to an attribute of a resource that uses count or for_each creates a dependency on all its instances. A reference to a module output creates a dependency on the resources the output depends on. And a reference to a data source whose arguments are known at plan time lets Terraform read it early, during planning, while a data source that depends on a not-yet-created resource is deferred to apply (this is the (known after apply) you see on its attributes).

Sometimes one object relies on the behavior of another without reading any of its attributes. The classic Bookshelf case is a container that connects to PostgreSQL at start-up: it needs the database container to exist, but it only receives a hostname string. The depends_on meta-argument adds the missing edge. It accepts a list of references to resources, data sources or modules in the same module.

Source: Terraform Docs — The depends_on meta-argument.

The documentation calls depends_on a last resort, for three reasons. It forces Terraform to be conservative: it cannot know which attributes of the upstream object matter, so it assumes any of them may change and shows more values as (known after apply). That can produce larger plans and replace more resources than necessary. The effect is strongest when the dependency is a whole module, because every resource and data source in the module then waits for the upstream object. And it hides the reason for the edge, so a short comment explaining why should accompany every use. The better fix is nearly always to pass the value through an expression, for example by building the host name from the container’s name attribute so that the reference itself carries the dependency. The details of the argument are in Meta-arguments.

Some lifecycle settings add or reverse edges. create_before_destroy reverses the destroy-time edge between a replaced object and the objects that depend on it, so that the new object is created, dependents are re-pointed and only then the old object is destroyed; the setting is applied to the dependencies as well, which is why it can spread. replace_triggered_by adds an edge from the referenced resource and forces a replacement when that resource changes. prevent_destroy does not change the graph, but it turns a plan that would destroy the object into an error. The semantics are in Lifecycle, Validation and Checks; the point here is that these settings change the plan, so they are visible in terraform plan and in terraform graph -type=plan.

Normal mode is what you get without a flag. Terraform refreshes the state from the real objects, diffs the result against the configuration, and proposes one action per resource instance, which the output marks with symbols:

Source: Terraform Docs — terraform plan.

A typical abbreviated plan for the Bookshelf configuration after changing an image tag:

Source: Terraform Docs — terraform plan (output abbreviated and illustrative).

The comment # forces replacement is the clue to read: the provider declared that the attribute cannot be updated in place. Replacement is a provider decision, not a core one, which is why the same change may be an in-place update for one resource type and a replacement for another.

terraform plan -destroy shows what terraform destroy would do, and terraform destroy is documented as a convenience for terraform apply -destroy. The plan uses the destroy graph, in which every edge is reversed: web is removed before the APIs, the APIs before the data stores, and the network last. Preview a destroy before running it, and save the plan if a pipeline will execute it.

Source: Terraform Docs — terraform plan, destroy mode.

prevent_destroy blocks a destroy plan for the protected resource with an error, and -replace cannot be combined with -destroy. See the section on targeting for why restricting a destroy is risky.

Real infrastructure changes outside Terraform: a colleague edits a setting in a console, an autoscaler changes a count, a provider API starts returning a default it did not return before. Terraform calls the difference between the state and reality drift. -refresh-only produces a plan whose only proposals are updates to state and to root module outputs; no remote object is touched.

Source: Terraform Docs — terraform plan, refresh-only mode.

terraform apply -refresh-only shows the detected differences and asks for approval before writing them to state. That is the supported replacement for the older terraform refresh command, which the documentation marks as deprecated: it wrote the changes without asking, so a mistaken credential or a wrong workspace could silently replace good state with bad. Accepting a refresh-only plan does not change the configuration, so the next normal plan will still show a diff if the recorded values no longer match what the code says. Decide for each difference whether to update the code to match reality, or to run a normal apply to push reality back to the code.

Normal plans also detect drift during the refresh step and report it in a separate "Objects have changed outside of Terraform" section, showing only changes relevant to the proposed actions, so a refresh-only run is for when you want drift reviewed and recorded on its own.

Sometimes an object is unhealthy but its configuration is unchanged: a container is wedged, a certificate was corrupted, a bootstrap script ran with the wrong input. -replace=ADDRESS asks Terraform to plan the replacement of one instance as if the provider had required it. It is available on plan and apply and can be repeated; it cannot be combined with -destroy.

Source: Terraform Docs — terraform plan, -replace.

The older way was terraform taint ADDRESS, which marks the object as tainted in state so that the next plan replaces it. The command is deprecated in favour of -replace. The reasoning in the documentation is that a replacement requested with -replace appears in a plan you can review, while a taint is written to state immediately and another user could plan against the tainted object before you have reviewed the effect. Terraform itself still marks objects as tainted when a create fails part-way (for example when a provisioner fails); terraform untaint removes the mark when you decide the object is healthy.

Replacements cascade. Replacing postgres produces new values for the attributes that other resources read, so every dependent that reads one of those attributes is also replaced or updated, and attributes that become unknown show as (known after apply). Read the whole plan, not only the object you named.

-target=ADDRESS restricts the plan to the matching resource instances or modules and everything they depend on. Dependents are not included. It can be repeated.

Source: Terraform Docs — terraform plan, -target.

The documentation says to use it "in exceptional circumstances only", and the tool reminds you every time it is used. The reasons it is discouraged follow from how state and the graph work.

Legitimate uses are recovery ones: an apply failed because a downstream object was misconfigured and you need to bring up the upstream object so you can fix it, or a dependency problem needs a first partial apply. Follow every targeted run with an untargeted terraform plan that should end with no changes.

OpenTofu adds -target-file and the inverse option -exclude (with -exclude-file), which plans everything except the matching instances and anything depending on them. Targeting and excluding cannot be mixed in one command. The OpenTofu documentation also reserves both for exceptional cases.

By default each plan first refreshes the state: it reads every managed object from its provider. For a large configuration that is the slowest part of a plan and the largest consumer of API calls. -refresh=false skips it and plans against the state exactly as recorded.

Source: Terraform Docs — terraform plan.

The cost is correctness: external changes are not noticed, so the plan can propose actions that are wrong or miss changes that are needed. The option cannot be combined with -refresh-only. A saved plan created with it is also not suitable for terraform show -json, according to the show documentation. Use it for fast feedback while editing, never as the plan that is applied.

Terraform 1.17 adds a middle path. The 1.17 changelog describes -minimal-refresh as a planning option that "will only refresh resources that have proposed changes", and the plan reference adds that it cannot be used with -refresh-only or with -refresh=false, and that a change in a resource schema version still triggers a refresh.

Source: Terraform Docs — terraform plan, -minimal-refresh and Terraform v1.17 CHANGELOG.

Unlike -refresh=false, objects that will change are still read from the provider, so the plan acts on current values for them. Objects without a proposed change are not refreshed, which means drift on those objects goes unnoticed. The exact criteria are decided by Terraform, so test it on your configuration before relying on it in a pipeline. The OpenTofu 1.13 plan documentation lists -refresh=false but not -minimal-refresh, so do not assume the option exists there.

terraform show -json tfplan converts a saved plan into a documented JSON structure. It is how policy checks, cost estimators and pull-request comment bots read a plan without parsing the human output.

Source: Terraform Docs — terraform show and Terraform Docs — JSON output format.

The main top-level properties of the plan representation are:

Source: Terraform Docs — JSON output format, plan representation.

change.actions is an array: ["no-op"], ["create"], ["read"], ["update"], ["delete"], and the two replace forms ["delete", "create"] and ["create", "delete"]. A consumer that wants every case where something disappears should test for the presence of the string delete, not for equality with a single value. Minor increments of format_version are backward compatible additions, so consumers should ignore unknown properties and refuse an unsupported major version.

terraform show -json prints sensitive values from state in cleartext, and a plan file can carry them too, so do not post unredacted JSON in a pull request comment.

The sequence below follows one terraform apply of an unsaved plan: the state is locked, refreshed, planned, approved, executed node by node, and written back. State is updated while the apply progresses, not just at the end, which is what makes a partial apply recoverable.

Source: Terraform Docs — terraform apply and Terraform Docs — Resource Graph (sequence simplified).

When an error occurs, the documentation says Terraform logs it, records in state the changes that did complete, releases the lock and exits. It does not roll back. After fixing the cause you run apply again, and Terraform plans only what is still missing.

A cycle appears when A needs B and B needs A, directly or through a chain. Terraform stops with a "Cycle" error that lists the objects involved. Typical causes:

Draw the offending part with terraform graph -type=plan -draw-cycles, then break the loop by splitting a resource in two, removing an unnecessary reference, or turning one direction into data that is passed in.

A change to a value that forces replacement does not stop at the first resource. Everything that reads an attribute of the replaced object sees a new value (often unknown) and may be replaced as well. A new database container id can replace every container that uses it, a new network can replace every container attached to it. Review -/+ entries down the whole plan, look at which attribute shows # forces replacement, and consider create_before_destroy, ignore_changes for an attribute that is changed on purpose outside Terraform, or a design that decouples the objects (for example resolving a DNS name instead of reading an id).

When a resource needs another one but receives only a literal string, Terraform sees no edge and may create them in parallel or destroy them in the wrong order. Symptoms are intermittent failures that disappear on a second apply. Prefer a reference; if that is impossible, add a commented depends_on.

A plan that proposes the same change after every apply means the value read back from the provider never equals the value in the configuration. Common sources: a provider normalises a value (case, trailing dot, ordering of a set), a field is changed by another system (tags added by a cloud policy), a computed default competes with an explicit argument, or an unknown value is used in a way that makes the plan non-deterministic. Compare terraform plan with terraform show -json for the before/after, then fix the configuration to the normalised form, add ignore_changes for the field owned by someone else, or report the provider bug. A -refresh-only apply followed by a normal plan separates drift from normalisation.

count and for_each need to know the number of instances or the keys at plan time. If the collection is derived from an attribute that is only known after apply, Terraform stops with an error about an argument that "cannot be determined until apply". Derive the keys from values that are known at plan time (static maps or variables), or apply in two steps with -target as a one-time recovery.

An apply can fail after some objects were created, because of an API error, a quota, a timeout, or the interruption of the process. State holds what completed, the failed object may be marked tainted, and the next plan proposes the rest, plus a replacement for the tainted object. If the process was killed hard or the state write itself failed, the backend may still hold the lock and an object may exist remotely without being recorded: use terraform force-unlock only when you are certain nobody else is running, then reconcile with an import. Using a remote backend with locking, and not running two applies against the same state, are the main safeguards (see State).

Applying a saved plan after the state, the configuration or the provider versions changed fails. Do not work around it with -lock=false; make the plan again. In CI, produce the plan and apply exactly that artefact in the same environment.