Q: What is `terraform graph`?
terraform graph prints Terraform's internal dependency graph in DOT format, which Graphviz can render as an image.
Want to master this scenario in a live sandbox? KodeKloud's HashiCorp Certified Terraform Associate (003) Interactive Labs covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: <code>terraform graph</code> prints Terraform's internal dependency graph in DOT format, which Graphviz can render as an image. Terraform builds this graph from references between resources, modules, variables and providers, and uses it to decide ordering and parallelism. Interviewers ask about it because it shows whether you understand how Terraform orders operations, and because it is the first tool to reach for when you see a dependency cycle error or an unexpected apply order. A good answer covers the command, rendering, the <code>-type</code> options and its limits.
How Terraform builds the dependency graph
Every reference creates an edge, and edges decide ordering. Understanding this model makes the output of the graph command easy to read, because every line is simply one of these relationships.
- Implicit edges: referencing
aws_subnet.a.idinside another resource makes that resource depend on the subnet, so the subnet is created first and destroyed last. - Explicit edges:
depends_onadds dependencies that Terraform cannot infer from references. - Parallelism: nodes with no path between them run concurrently, limited by
-parallelism(default 10). - Graph is a DAG: a directed acyclic graph. If your references form a loop, Terraform reports a cycle and refuses to continue.
- Walk order: Terraform walks the graph from nodes with no dependencies outward, and walks it in reverse for destroys, which is why a subnet is deleted only after everything inside it.
Hands-on: terraform graph with Graphviz
Generate DOT text, then render it with the dot tool. Graphviz is a separate install and is not bundled with Terraform, so a missing dot binary is the most common first stumble.
terraform init
terraform graph > graph.dot
terraform graph | dot -Tsvg > graph.svg
# graph of a specific saved plan
terraform plan -out=tfplan
terraform graph -plan=tfplan | dot -Tpng > plan-graph.png
- Prerequisite: run
terraform initin the root module first; the command needs the configuration and providers loaded. - Render: pipe the output into
dotfrom Graphviz to produce SVG or PNG. Install Graphviz with your package manager. - Graph types:
-type=plan,-type=plan-destroyand-type=applyshow different phases; the default is plan style. - From a saved plan:
terraform graph -plan=tfplangraphs the exact operations in a plan file.
Using the graph to debug cycle errors
A cycle means resource A needs B while B needs A.
terraform graph -draw-cycles | dot -Tsvg > cycles.svg
# fix: break the loop with standalone rule resources
resource "aws_vpc_security_group_ingress_rule" "a_from_b" {
security_group_id = aws_security_group.a.id
referenced_security_group_id = aws_security_group.b.id
ip_protocol = "tcp"
from_port = 8080
to_port = 8080
}
- Symptom:
Error: Cycle: aws_security_group.a, aws_security_group.blisting the participating nodes. - Visualise:
terraform graph -draw-cycles | dot -Tsvghighlights the cycle edges in colour. - Typical cause: two security groups referencing each other inline. Move the rules into separate
aws_vpc_security_group_ingress_ruleresources so the groups no longer depend on each other. - Also check: module outputs feeding inputs of a module that the first one depends on, and
depends_onthat points back. - Cross-checking: after breaking a cycle, re-run
terraform validateandterraform plan; the cycle error disappears at graph construction time, so it is caught early.
Limits and edge cases
The raw graph is accurate but hard to read at scale. Knowing these limits keeps you from over-trusting a diagram when the plan is the real authority.
- Noise: large configurations produce graphs with provider and root nodes that drown the useful edges. Filter with tools such as
grep, or use a dedicated visualiser. - No values: the graph shows structure, not attribute values or whether a change will happen. Use
terraform planfor that. - Expansion:
countandfor_eachinstances are not necessarily shown the same way in every graph type, so compare the plan-type and apply-type views when in doubt. - Format: output is plain DOT text; if
dotis missing you will only see text, so verify Graphviz is installed withdot -V. - Large stacks: split the root module or generate per-module graphs, because a single image of hundreds of resources is rarely readable in a review.
Where it fits in daily work
Use it for explanation and troubleshooting, not as the source of truth for architecture. Used sparingly, the graph is a cheap way to turn an opaque ordering question into a visible one.
- Documentation: attach a rendered graph artifact in CI for large stacks to help reviews.
- Refactors: compare graphs before and after splitting modules to confirm dependencies did not change unexpectedly.
- Ordering questions: if resources apply in a surprising order, inspect the graph before adding
depends_on. - Teaching tool: showing a new teammate the graph for a small module is a fast way to explain why Terraform created resources in parallel and why one waited for another.
- Pair with plan: use the graph for why an order exists and the plan for what will change; together they answer most ordering questions without guessing.
- terraform graph prints the dependency graph as DOT text, which Graphviz renders into an image.
- I verify structure with plan or apply type graphs and use -draw-cycles to debug cycle errors.
- I generate graph images in CI for large stacks and compare them across refactors.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Running it without terraform init The command needs initialised providers and modules to build the graph.
- Expecting a ready made picture The output is DOT text; you must render it with Graphviz.
- Fixing cycles with more depends_on Extra edges make cycles more likely; the fix is to remove a circular reference.
- Reading the graph as proof a change is safe It shows relationships, not what will actually change; use terraform plan.