Dependency Graph

Terraform never asks you what order to do things in, and it ignores the order you wrote them in. It derives the order from a graph it builds out of your references. This page is what puts an edge in that graph, what therefore runs in parallel and what queues behind something else, and how to walk the graph backwards from an ordering surprise to the line of configuration that caused it.

Prerequisites: The Plan/Apply Lifecycle

What & Why

The dependency graph is a directed acyclic graph Terraform constructs from your configuration, where nodes are things that must be created, read or destroyed, and an edge from A to B means A must complete before B starts. Terraform walks it to plan, and walks it again to apply.

The bad practice it replaces

Ordered scripts, and the ordering bugs that come with them. In a shell script, order is whatever you typed, which means correctness depends on the author remembering that the subnet needs the network and the policy needs the bucket — and it means the script is serial even where it needn't be, because expressing "these six things can happen at once, and then this seventh thing" is genuinely awkward in bash and nobody does it.

Terraform's answer is that you don't declare order at all. You declare relationships, by referring to one resource from another, and the order falls out. This is why file ordering is irrelevant and why a resource can reference one declared eighty lines below it. It also means an ordering bug in Terraform is nearly always a missing reference, not a missing instruction — which is a much better class of bug, because the fix makes the configuration more correct rather than more elaborate.

Where it sits

The graph is phase four of the six in The Plan/Apply Lifecycle. That page said "a graph is built" and moved on; this one is what's in it. What it deliberately leaves out: how count and for_each expand one configuration block into many graph nodes, and how create_before_destroy rewrites edges — both are Meta-Arguments, because both are easier to understand once the plain graph is clear.

Three things it's confused with

It is not the order things appear in your files. Nothing about textual position affects anything. Two resources in the same file with no reference between them are unrelated and will run concurrently.

It is not a graph of resource types. The nodes are instances and configuration objects — providers, variables, locals, outputs and data sources are all in there, not just resources. A great many ordering questions are actually questions about where a provider or a data source sits.

depends_on is not how you express a dependency. It's how you express the rare dependency that isn't already visible in a reference. If a resource uses another resource's attribute, the edge already exists; adding depends_on as well is noise, and adding it instead of a reference is worse than either.

When NOT to reach for it

• Don't use depends_on to fix an ordering problem you haven't diagnosed. It works often enough to be dangerous. It's coarse — it makes the whole resource wait for the whole other resource, rather than for a specific value — and it's invisible to the reader as an explanation. If ordering is wrong, the first question is which reference is missing.
• Don't reach for -parallelism to make applies faster. The default is usually fine, and the serialisation you're experiencing is almost always the shape of your graph or a provider rate limit, neither of which more concurrency helps.
• Don't use terraform graph to understand a large configuration. Its output is a DOT document that becomes unreadable at about thirty nodes. It's a debugging tool for a specific question, not a documentation tool. See Ecosystem for what to use instead.

Core Concepts

Directed acyclic graph (DAG) — a set of nodes with one-way arrows and no loops. Directed because dependency has a direction; acyclic because a cycle would mean two things each waiting for the other, which has no valid execution order. Terraform rejects cycles outright rather than guessing.

Node — one thing in the graph. Resource instances, data sources, provider configurations, variables, locals, outputs, and module expansion nodes. Not all nodes do work — some exist only to express ordering.

Edge — a "must happen first" relationship. Created by references, depends_on, module input/output wiring, and provider relationships. Never created by textual proximity.

Implicit dependency — an edge Terraform infers from a reference. Writing aws_s3_bucket.logs.arn inside another resource creates an edge from the logs bucket to that resource. The normal and preferred kind.

Explicit dependency — an edge you declare by hand. depends_on = [aws_s3_bucket.logs]. For relationships real in the cloud but invisible in the configuration — typically IAM permissions that must exist before an action is attempted.

Hidden dependency — a real-world ordering requirement with no edge at all. The failure this whole topic exists to prevent: a resource that genuinely needs another to exist first, but references it by a hardcoded string, so Terraform sees no relationship and runs them concurrently. Fails intermittently, which is the worst way for anything to fail.

Graph walk — executing the graph. Terraform visits nodes whose dependencies are all satisfied, several at a time, repeating until none remain.

Parallelism — how many nodes are visited concurrently. Ten by default, ⚠️ verify; controlled by -parallelism=N. It's a cap on concurrency, not a target.

Critical path — the longest chain of dependent nodes. The lower bound on apply duration: no amount of parallelism makes a five-deep chain faster than the sum of its five resources.

Destroy edge — a reversed edge. During destroy, dependencies invert — if the bucket policy depended on the bucket at create time, the bucket must wait for the policy at destroy time. Terraform handles this by reversing the graph, which is why destroy order is create order backwards.

Cycle — a loop, and a hard error. Reported as Error: Cycle: followed by the addresses involved. Always a configuration problem; never something to work around with -target.

Provider node — the configured provider a resource uses. Every resource depends on its provider being configured. When a provider's own configuration references a resource attribute, that provider node acquires a dependency, and everything using the provider inherits it — the source of the bootstrapping problem in In Practice.

How It Works

What creates an edge

Four sources, and only four.

1 · A reference in an expression. By far the most common, and the one you should want. Any reference to another resource's attribute — anywhere, including inside a string interpolation, a for expression, or a nested block — creates an edge:

resource "aws_s3_bucket" "logs" {
  bucket = "tf-graph-demo-logs-0725"
}

resource "aws_s3_bucket_policy" "logs" {
  bucket = aws_s3_bucket.logs.id   # ← this reference is the edge
  policy = data.aws_iam_policy_document.logs.json
}

Terraform now knows the bucket must exist before the policy is attached. You wrote no ordering instruction. Identical in azurerm and google.

2 · depends_on. For dependencies that exist in the cloud but not in your expressions:

resource "aws_s3_bucket" "app" {
  bucket = "tf-graph-demo-app-0725"

  # The role's policy must exist before this bucket is created, but nothing
  # about the bucket's configuration mentions it.
  depends_on = [aws_iam_role_policy.bucket_writer]
}

It accepts only static references to whole resources or modules — not attributes, and not expressions — because it's evaluated when the graph is built, before any values exist.

3 · A module boundary. Passing a value into a module creates edges from whatever produced that value to the nodes inside the module that use it; reading a module output creates edges the other way. So module composition is graph composition. Modules.

4 · The provider relationship. Every resource depends on its provider configuration node. This is invisible and free — until the provider's own configuration depends on a resource, at which point everything using that provider waits for it.

What parallelises, and what doesn't

Terraform walks the graph visiting every node whose dependencies are satisfied, up to the parallelism cap. So:

Two consequences worth holding onto. Apply duration has a floor set by the critical path, not by resource count: a hundred independent buckets is fast, a five-deep chain is not, and no flag changes that. And a widely-referenced resource is a serialisation point — if two hundred resources reference the network, none of them start until it finishes, and the graph is effectively "one thing, then everything".

Destroy runs the graph backwards

This is the part people are surprised by exactly once. Dependency edges reverse for destroy: if the policy depended on the bucket, then at destroy time the bucket depends on the policy being gone first. Terraform reverses the graph rather than asking you to think about it.

The practical implication is that destroy ordering problems are also missing-reference problems, and they surface later — a destroy that fails because a resource still has a dependent attached usually means Terraform didn't know about the relationship. The other implication is that create_before_destroy locally inverts edges, which is how a single lifecycle setting on one resource can produce a cycle error somewhere else entirely; that's Meta-Arguments.

Cycles

A cycle is two or more nodes each waiting for the other. Terraform detects it while building the graph and refuses to plan:

# UNVERIFIED — confirm against a real run
Error: Cycle: aws_s3_bucket.a, aws_s3_bucket_policy.a, aws_s3_bucket.b

Three usual causes, in rough order of frequency: mutual references, where two resources each refer to an attribute of the other — the honest fix is usually a third resource, or moving one side's value into a local that neither computes from the other; a depends_on pointing back up a chain that already flows down, often added while debugging an unrelated problem and never removed; and create_before_destroy interacting with a reference, where the inverted edge closes a loop.

The error names the nodes in the cycle, which is enough to find it by hand in a small configuration. In a large one, terraform graph filtered to those addresses is faster than reading.

The minimal graph differs by cloud

Terraform's edge rules are identical everywhere. What differs is the shape of the smallest useful graph, because Azure's hierarchy is mandatory: a storage account cannot exist without a resource group, so every Azure configuration has a layer that AWS and GCP configurations don't.

```hcl
# Two nodes, one edge.
resource "aws_s3_bucket" "demo" {
  bucket = "tf-graph-demo-0725"
}

resource "aws_s3_bucket_versioning" "demo" {
  bucket = aws_s3_bucket.demo.id        # edge: bucket → versioning

  versioning_configuration {
    status = "Enabled"
  }
}
```
AWS splits bucket features into separate resources, so a "configure a bucket
properly" configuration has many nodes all depending on the one bucket — a
fan-out from a single serialisation point.

```hcl
# Three nodes, two edges — the resource group is unavoidable.
resource "azurerm_resource_group" "demo" {
  name     = "tf-graph-demo"
  location = "westeurope"
}

resource "azurerm_storage_account" "demo" {
  name                     = "tfgraphdemo0725"
  resource_group_name      = azurerm_resource_group.demo.name   # edge
  location                 = azurerm_resource_group.demo.location
  account_tier             = "Standard"
  account_replication_type = "LRS"
}

resource "azurerm_storage_container" "demo" {
  name                  = "data"
  storage_account_name  = azurerm_storage_account.demo.name     # edge
  container_access_type = "private"
}
```
Every Azure graph starts with a resource group, and containers sit below the
storage account — so the critical path is one node longer than the equivalent
AWS or GCP configuration before you've added anything of your own.

```hcl
# Two nodes, one edge.
resource "google_storage_bucket" "demo" {
  name     = "tf-graph-demo-0725"
  location = "EUROPE-WEST1"

  versioning {
    enabled = true                      # nested block, not a separate resource
  }
}

resource "google_storage_bucket_iam_member" "demo" {
  bucket = google_storage_bucket.demo.name   # edge
  role   = "roles/storage.objectViewer"
  member = "allAuthenticatedUsers"
}
```
GCP tends to keep configuration in nested blocks rather than separate
resources, so its graphs are typically flatter and wider than AWS's for the
same intent.

The generalisation worth carrying: the same intent produces differently-shaped graphs on different clouds — AWS deep and fanned-out because features are separate resources, Azure one layer deeper because of the resource group, GCP flatter because features are nested blocks. This matters when you compare apply durations across clouds and conclude one provider is slow, when actually one graph has a longer critical path. The canonical scoping comparison is in Providers & the Registry.

Getting Started

Three demonstrations: parallelism, serialisation, and a cycle. Shown in AWS; identical in azurerm and google except for the graph shapes noted above.

Independent resources run concurrently

# main.tf
terraform {
  required_version = ">= 1.5"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}

provider "aws" {
  region = "eu-west-1"
}

resource "aws_s3_bucket" "one" {
  bucket = "tf-graph-demo-one-0725"
}

resource "aws_s3_bucket" "two" {
  bucket = "tf-graph-demo-two-0725"
}

resource "aws_s3_bucket" "three" {
  bucket = "tf-graph-demo-three-0725"
}

terraform init && terraform apply

# UNVERIFIED — confirm against a real run
aws_s3_bucket.two: Creating...
aws_s3_bucket.one: Creating...
aws_s3_bucket.three: Creating...
aws_s3_bucket.two: Creation complete after 2s [id=tf-graph-demo-two-0725]
aws_s3_bucket.three: Creation complete after 2s [id=tf-graph-demo-three-0725]
aws_s3_bucket.one: Creation complete after 3s [id=tf-graph-demo-one-0725]

All three Creating... lines appear before any completes, and not in the order you wrote them. That interleaving is the graph walk, and the arbitrary order is the lesson: there is no relationship between these resources, so Terraform is free to do them in any order, and it does.

Now add a reference

resource "aws_s3_bucket_versioning" "one" {
  bucket = aws_s3_bucket.one.id

  versioning_configuration {
    status = "Enabled"
  }
}

terraform apply

# UNVERIFIED — confirm against a real run
aws_s3_bucket_versioning.one: Creating...
aws_s3_bucket_versioning.one: Creation complete after 1s [id=tf-graph-demo-one-0725]

One reference, one edge, and the versioning resource waited for a bucket that already existed. To see it serialise properly, destroy and re-apply everything.

Look at the graph

terraform graph | head -20

# UNVERIFIED — confirm against a real run
digraph {
  compound = "true"
  newrank = "true"
  subgraph "root" {
    "[root] aws_s3_bucket.one (expand)" -> "[root] provider[\"registry.terraform.io/hashicorp/aws\"]"
    "[root] aws_s3_bucket_versioning.one (expand)" -> "[root] aws_s3_bucket.one (expand)"
    ...
  }
}

Two things are visible even in this fragment. The versioning resource points at the bucket — that's the edge your reference created. And every resource points at the provider node, which is the invisible fourth edge source doing its work.

Render it if you have Graphviz:

terraform graph | dot -Tsvg > graph.svg

Break it on purpose

Add a mutual reference — a tag on each bucket naming the other:

resource "aws_s3_bucket" "one" {
  bucket = "tf-graph-demo-one-0725"
  tags   = { peer = aws_s3_bucket.two.id }
}

resource "aws_s3_bucket" "two" {
  bucket = "tf-graph-demo-two-0725"
  tags   = { peer = aws_s3_bucket.one.id }
}

terraform plan

# UNVERIFIED — confirm against a real run
Error: Cycle: aws_s3_bucket.one, aws_s3_bucket.two

No plan is produced at all — the graph couldn't be built, so phases five and six never happened. Remove the cycle, then:

terraform destroy

Watch the destroy output: the versioning resource goes before the bucket it referenced. The graph, reversed.

In Practice

Reference, never hardcode. This is the most important habit on the page. These two are not equivalent:

# Correct: creates an edge. Terraform waits for the bucket.
resource "aws_s3_bucket_versioning" "app" {
  bucket = aws_s3_bucket.app.id
}

# Broken: no edge. Terraform may attach versioning to a bucket that doesn't exist yet.
resource "aws_s3_bucket_versioning" "app" {
  bucket = "tf-app-bucket-0725"
}

The second works most of the time, which is what makes it dangerous — it depends on the graph walk happening to visit the bucket first, and it will fail on a fresh apply to a new environment, in CI, at the worst moment. Every hardcoded value that could have been a reference is a hidden dependency. This is also the strongest practical argument for referencing over hardcoding, stronger than tidiness.

Provider configurations that depend on resources are the bootstrapping trap. The pattern looks reasonable: create a Kubernetes cluster, then configure the Kubernetes provider with its endpoint. But the provider node now depends on the cluster, and every resource using that provider inherits the dependency — so Terraform cannot even build a usable plan for those resources until the cluster exists, and you get errors about unknown values during planning rather than a clean ordering. The same shape appears whenever a provider's credentials or endpoint come from a resource in the same configuration.

The fix is separation rather than cleverness: create the platform in one configuration, consume it in another, with the second reading the first's outputs. That's a state-splitting decision, and it's Repo & Environment Structure.

depends_on belongs in a small number of real situations, and it's worth knowing them so you can recognise when you're outside them. IAM permissions that must exist before a resource is created, even though the resource's arguments don't mention the policy. Resources whose relationship is enforced by the cloud but invisible in configuration — a service that must be enabled on a GCP project before an API-backed resource can be created. And ordering across a module boundary that the module's inputs don't express. Outside those, treat it as a symptom. Full argument in Meta-Arguments.

Shape the graph deliberately when apply time matters. Two levers, and neither is a flag. Shorten the critical path: if the chain is bucket → versioning → policy → notification, ask whether any of those genuinely depend on each other or whether they all just depend on the bucket — fan-out is fast, chains are slow. And reduce fan-in on shared resources: if everything references one network, nothing starts until the network finishes, and moving the network into its own configuration removes it from the graph entirely.

What a reviewer should look for in a diff touching this topic:

• A hardcoded name, ARN or ID that duplicates a resource in the same configuration. That's a removed edge and an intermittent failure waiting to happen. Ask for the reference.
• A new depends_on. Every one needs a sentence saying which real-world requirement it encodes and why no reference expresses it. "It didn't work without it" means the diagnosis isn't done.
• A depends_on alongside a reference to the same resource. Redundant; delete it.
• A provider configuration that references a resource in the same configuration. Raise it as a design question, not a nit.
• A reference that was removed — replaced by a variable or literal. That silently deletes an edge, and the plan won't show it. This is the one a reviewer is most likely to miss.

Blast radius and rollback. The graph itself is not a runtime risk, but it determines how far a failure spreads: a failure on a node with many dependents stops all of them, so a broken shared resource halts the apply broadly, while a leaf failure is contained. Reverting a commit that changed references restores the previous graph, but any resources already created remain — the graph is recomputed from scratch each run and has no memory of the previous shape.

Ecosystem

terraform graph. Emits the graph as DOT for Graphviz. Genuinely useful for a specific question about a small configuration or a named cycle; unreadable past roughly thirty nodes. -type=plan and its siblings select which graph to emit — ⚠️ verify current supported values, as these have changed.

terraform apply -parallelism=N. Caps concurrent node visits. Worth lowering to diagnose suspected rate-limiting, or when a provider misbehaves under concurrency. Raising it rarely helps and often triggers throttling. Not a performance strategy.

Graphviz (dot). The renderer. terraform graph | dot -Tsvg > graph.svg is the whole integration.

Rover, and similar visualisers. Interactive graph and plan visualisation, which is what terraform graph output stops being at any real size. Worth a look when onboarding onto an unfamiliar repository. ⚠️ verify current maintenance status before recommending — this category of tool has a poor survival rate.

terraform show -json for dependency data. The plan JSON includes each resource change and its dependencies, which is a more reliable programmatic source than parsing DOT. Useful for custom checks — "nothing in this state may depend on that module" is a policy you can write. Governance & Policy as Code.

TF_LOG=DEBUG. Logs the graph walk, so you can see which node the walker was visiting when something failed and which nodes were in flight concurrently. The practical use is confirming that two things you believed were ordered actually were.

Provider behaviour. Edge construction is Terraform's and identical everywhere. What differs is graph shape for equivalent intent, per the tab set above, and how tolerant each provider's API is of concurrency — which is what you're actually tuning when -parallelism appears to help.

Production

Security

Mostly indirect, with one direct case: depends_on is frequently the only thing ensuring an IAM policy or role exists before the resource that needs it, and a missing edge there produces a resource created without its intended permissions — which sometimes fails loudly and sometimes leaves something functioning with broader access than designed. The other consideration is that graph output reveals architecture; a rendered graph in a public repository is a free network diagram for anyone interested.

Blast radius

The graph decides propagation. A failure on a high-fan-in node — the network, the resource group, the shared key — stops everything downstream, so blast radius is a graph property before it's a permissions property. This is a concrete argument for extracting shared foundational resources into their own configuration: it doesn't just reduce plan time, it removes them from this graph so they cannot halt an application apply.

Scale

The graph is cheap to build and walk; that's essentially never the bottleneck. Apply duration is governed by the critical path and by provider rate limits, in that order. Two thousand resources in a wide graph apply far faster than four hundred in a deep one, and this is why "how many resources" predicts apply time poorly. The levers are structural — shorten chains, reduce fan-in, split state — rather than -parallelism. Scale & Performance.

Team workflow

Graph shape is a review concern, and mostly an invisible one: adding a reference is visible in a diff, while removing one — replacing aws_s3_bucket.app.id with a literal — deletes an edge silently and produces an intermittent failure weeks later on a fresh environment. Worth naming explicitly in a review checklist, because no tool will flag it. A newly-added depends_on is the other item worth challenging every time.

Reliability

Ordering failures split into two kinds. Cycles are safe — a hard error before anything happens, no infrastructure touched. Missing edges are not — they produce race conditions that pass in one environment and fail in another, and they're the reason a configuration that has worked for months fails on its first apply into a new region. The insurance is a periodic apply from empty into a throwaway environment: it's the only thing that exercises the graph from nothing, and it's the same drill as Failure & Recovery.

Interview Questions

Conceptual

Technical depth

Scenario and design

Commands & Gotchas

terraform graph                                  # emit the graph as DOT
terraform graph | dot -Tsvg > graph.svg          # render it
terraform graph | grep aws_s3_bucket.app         # the edges touching one address
terraform apply -parallelism=1                   # serialise, to isolate an ordering problem
terraform apply -parallelism=30                  # widen — rarely helps, often throttles
TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform apply  # which nodes ran concurrently, and when
terraform show -json | jq '.values.root_module.resources[].depends_on'  # recorded dependencies
terraform state list                             # the addresses the graph is built from

← Back to The Machinery · Next: Meta-Arguments →

⚠️ Verification checklist (delete before publishing)

Command output

• The concurrent-creation output for three buckets — confirm Creating... lines really interleave before completions, and capture real timings. The parallelism lesson depends on this block.
• terraform graph DOT output — the exact header (digraph {, compound, newrank), the [root] prefix, and whether nodes still carry the (expand) suffix. ⚠️ verify; this format has changed between versions and my excerpt may be from an older one.
• The cycle error format. I wrote Error: Cycle: aws_s3_bucket.one, aws_s3_bucket.two — confirm the exact rendering, and whether it lists nodes on one line or several.
• Confirm the mutual-tag-reference example actually produces a cycle rather than some other error.
• Destroy output ordering, showing the versioning resource destroyed before its bucket.
• terraform show -json | jq '...depends_on' — verify that path exists in the state JSON and returns what's implied.

Behavioural claims

• Default parallelism is 10 — flagged inline, same item as the lifecycle page. Verify once.
• That depends_on accepts only static references to whole resources/modules, no attributes and no expressions.
• That create_before_destroy inverts edges and can produce a cycle elsewhere. Asserted twice and used in an interview answer, but it's really Meta-Arguments' claim — verify there and keep both pages consistent.
• That lowering -parallelism can improve throughput under provider rate limiting. Plausible and widely repeated; ⚠️ verify before stating it as fact in an interview answer.
• terraform graph -type= supported values. Flagged inline — these have changed and some are removed.
• That the provider-configured-from-a-resource case produces unknown-value errors at plan time rather than merely ordering awkwardly. This claim carries two interview answers.

Provider-specific claims in the tab set

• AWS: that bucket features (versioning, policy, encryption, lifecycle) are genuinely separate resources in the current provider version, and that aws_s3_bucket_versioning is the right resource name.
• Azure: that azurerm_storage_container still takes storage_account_name — ⚠️ verify, this may have moved to storage_account_id in azurerm 4.x.
• GCP: that versioning is a nested block on google_storage_bucket, and that google_storage_bucket_iam_member is correct.
• The generalisation that AWS graphs are deep/wide, Azure one layer deeper, GCP flatter. Reasonable but sweeping — confirm against real graphs for the three configurations shown.
• ⚠️ The GCP example grants allAuthenticatedUsers object-viewer access. That's a public-ish grant in a teaching example and a reviewer will flag it. Change it to a specific principal before publishing.

Versions and syntax

• ~> 5.0 aws constraint — stale, fix across all five pages in one pass.
• Rover's maintenance status before recommending it.

Rendering and structure

• One <Tabs> block, for minimal-graph shape. Confirm the AWS/GCP tabs being shorter than Azure's reads as the point being made rather than as an omission — prose above the block says so, check it's prominent enough.
• All relative links resolve.