Skip to main content
Terraform·7 min read

Terraform's Dependency Graph — How the DAG Drives Apply Order

How Terraform builds a Directed Acyclic Graph of your resources, the difference between implicit and explicit dependencies, how the graph powers parallelism, and how to visualize it with terraform graph and Graphviz.

DT

DevOps Engineer & Technical Writer

The Problem

You never tell Terraform "create the VPC first, then the subnet, then the instance." You just declare resources in whatever order you like. Yet Terraform always builds the subnet after the VPC and the instance after its security group — and it does the independent work in parallel. The mechanism behind this is a Directed Acyclic Graph (DAG): Terraform figures out dependencies for you, then walks the graph in the only valid order.

RESOURCE DEPENDENCY GRAPH (DAG) — ARROWS POINT TO THE DEPENDENCY aws_vpc.main aws_subnet.app aws_security_group.web aws_instance.web aws_s3_bucket.logs no edges → created in parallel solid = implicit (attribute reference) dashed = direct ref subnet_id on instance

Each arrow points from a resource to the thing it depends on. Terraform creates leaves first (the VPC) and works outward; on destroy it walks the graph in reverse.

How Terraform Builds the Graph

During plan, Terraform parses every resource, data source, module, and output, then connects them with edges wherever one references another. The result is a directed graph (edges have direction) that is acyclic (no resource may depend on itself through a cycle). If you accidentally create a cycle, Terraform refuses to proceed:

Error: Cycle: aws_security_group.a, aws_security_group.b

The DAG is not just for ordering — it is also how Terraform knows what can run at the same time.

Implicit Dependencies

Most dependencies are implicit: you reference one resource's attribute in another, and Terraform infers the edge automatically. This is the preferred style.

resource "aws_vpc" "main" {

cidr_block = "10.0.0.0/16"

}

resource "aws_subnet" "app" {

vpc_id = aws_vpc.main.id # implicit edge: subnet depends on vpc

cidr_block = "10.0.1.0/24"

}

resource "aws_instance" "web" {

subnet_id = aws_subnet.app.id # implicit edge: instance depends on subnet

ami = "ami-0abc123"

instance_type = "t3.small"

}

Because aws_subnet.app reads aws_vpc.main.id, Terraform knows the VPC must exist first. You wrote no ordering instructions at all.

Explicit Dependencies with <code class="inline-code">depends_on</code>

Sometimes a dependency exists but is not expressed through an attribute — for example, an application needs an IAM policy attached before it starts, even though it never references the policy's ID. For those cases use depends_on:

resource "aws_instance" "web" {

ami = "ami-0abc123"

instance_type = "t3.small"

subnet_id = aws_subnet.app.id

depends_on = [aws_iam_role_policy.web_access]

}

Use depends_on sparingly. It is a manual override; overusing it serializes work that could have run in parallel and hides the real relationships. Prefer passing an attribute reference whenever one exists.

Parallelism and Apply Order

The graph defines a partial order: anything with no edge between it can run concurrently. In the diagram above, aws_s3_bucket.logs shares no edges with the VPC chain, so Terraform creates it in parallel with the VPC. By default Terraform runs up to 10 operations concurrently; you can tune this:

# Reduce concurrency (e.g. to respect an API rate limit)

terraform apply -parallelism=2

Lowering parallelism never changes correctness — the graph still forces dependent resources to wait. It only changes how many independent branches execute at once.

The <code class="inline-code">terraform graph</code> Command

Terraform can emit the graph in Graphviz DOT format:

terraform graph

The raw output is DOT text. Pipe it into Graphviz's dot tool to render an image:

# Render the dependency graph to a PNG

terraform graph | dot -Tsvg > graph.svg

# Or produce a PNG

terraform graph | dot -Tpng > graph.png

You can also scope the graph to a specific operation to cut noise:

# Graph just the plan (the apply-time resource graph)

terraform graph -type=plan

For large configurations the full graph is overwhelming. In practice people render it occasionally to debug an ordering surprise or a cycle, not as a routine step.

Reading Plan Order

You rarely need the DOT graph day to day — the plan already reflects the ordering. When you read a plan, resources are shown grouped by action, and the apply log prints creations in dependency order:

aws_vpc.main: Creating...

aws_s3_bucket.logs: Creating... # parallel, no dependency on the VPC

aws_vpc.main: Creation complete

aws_subnet.app: Creating... # waited for the VPC

aws_subnet.app: Creation complete

aws_instance.web: Creating... # waited for the subnet + SG

If something applies in an order you did not expect, that is a signal to inspect the graph — usually a missing or accidental reference.

Common Mistakes to Avoid

  • Overusing depends_on. It serializes work and masks real relationships. Reach for an attribute reference first; use depends_on only when no attribute links the resources.
  • Creating accidental cycles. Two security groups each referencing the other's ID is the classic case. Break the loop with a separate aws_security_group_rule resource.
  • Assuming declaration order matters. The order of blocks in your .tf files has no effect — only references do.
  • Cranking parallelism up to "go faster." You will hit provider API rate limits and get throttling errors. The default of 10 is sensible for most providers.
  • Rendering the whole graph for a huge project. It is unreadable. Scope with -type or focus on the subgraph you are debugging.

FAQ

What does "acyclic" mean and why does it matter?

Acyclic means the graph has no cycles — no resource can depend on itself through a chain of other resources. It matters because a cycle has no valid creation order (A needs B, B needs A), so Terraform cannot decide what to build first and errors out. You must break the cycle, often by splitting a resource into finer-grained pieces.

How does Terraform decide what to run in parallel?

Any two resources with no path between them in the graph are independent and can run concurrently, up to the parallelism limit (10 by default). Resources connected by an edge always run in dependency order. The graph, not your file layout, determines this.

When should I use <code class="inline-code">depends_on</code>?

Only when a real dependency exists that is not captured by an attribute reference — for example, an application that requires an IAM policy or a provisioner that needs another resource ready first. If you can instead reference an attribute of the dependency, do that; it is clearer and lets Terraform maximize parallelism.

Do I need Graphviz to use Terraform?

No. terraform graph outputs DOT text on its own; Graphviz's dot tool is only needed to turn that text into an image. The dependency graph works internally whether or not you ever visualize it — rendering is purely a debugging aid.