Graph Explorer

Graph Explorer draws one resource instance and every block that a change to it reaches, as an interactive graph. The graph follows references into modules and linked states.

In the console, Graph Explorer is under Insights.

How dependencies work

A reference from one block to another creates a dependency. Terraform orders its operations by these dependencies.

resource "aws_instance" "web" {
  ami           = "ami-12345"
  instance_type = "t3.micro"
  subnet_id     = aws_subnet.main.id  # Creates dependency
}

A chain of references makes a chain of dependencies:

resource "aws_security_group" "web" {
  vpc_id = aws_vpc.main.id  # Depends on VPC
}

resource "aws_instance" "web" {
  security_groups = [aws_security_group.web.id]  # Depends on SG
}

Dependencies form a directed acyclic graph (DAG):

aws_vpc.mainaws_subnet.publicaws_security_group.webaws_instance.web
aws_subnet.public and aws_security_group.web depend on aws_vpc.main.
aws_instance.web depends on both.

The graph has an edge for each reference to a value, each read of a file or a tfvar, and each module call that fills a child module variable. A depends_on has no edge, because a change does not travel along it.

Scoping the graph

Graph Explorer shows the graph around one instance, not the full state. If the root has more than 40 direct dependents or the graph has more than 50 nodes, Graph Explorer does not draw it. For a larger graph, use Blast Radius.

Understanding the visualization

Element Meaning
Root node The selected instance, larger and in the accent color
Rectangle A resource, a data source (dashed border), or a module call
Pill A local value, a variable, or an output
Node label Block address
Arrow A → B means that B depends on A
Dashed edge A module call that fills a child module variable

Hover over a node to highlight its direct dependencies (blue edges) and direct dependents (purple edges). The hierarchical layout (dagre) puts nodes in dependency tiers, from top to bottom. Edges go in one direction, and related blocks stay near their dependencies.

Common patterns

Hub resources

A hub has many dependents:

aws_vpc.main
  • aws_instance.web1
  • aws_instance.web2
  • aws_rds_cluster.db

Three dependents.

A hub: aws_instance.web1, aws_instance.web2, and aws_rds_cluster.db depend on aws_vpc.main.

A change to a hub affects many resources. Use Blast Radius to see the impact.

Leaf resources

A leaf has no dependents:

aws_security_group.web
  • aws_instance.webleaf

No dependents.

aws_instance.web depends on aws_security_group.web.
Nothing depends on aws_instance.web, so it is a leaf.

A leaf is safer to change: it has fewer downstream effects.

Module clusters

The resources of a module form a cluster:

module.vpc
vpcsubnet
→
module.compute
instance
Two clusters: the vpc and the subnet of module.vpc, and the instance of module.compute.
module.compute depends on module.vpc.

Use cases

  • Architecture: find the major resource groups and follow the data flow.
  • Change planning: see the dependents of a resource before you change it.
  • Documentation: frame a root, then take a screenshot.
  • Debugging: see the dependencies that set the order of operations.
  • Comparison: view the graphs of different workspaces side by side.

CLI access

Get instances with dependencies

stategraph states instances query returns the dependencies that the state records. The QUERY argument is a filter of space-separated key:value terms (type, module, provider, address, resource_address, attr:<key>:<value>). -i gets every page:

stategraph states instances query \
  --state a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --format json \
  -i "type:aws_instance"

The response includes the dependencies:

{
  "results": [
    {
      "address": "aws_instance.web",
      "type": "aws_instance",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "dependencies": [
        "aws_subnet.main",
        "aws_security_group.web"
      ]
    }
  ]
}

Query dependencies with SQL

Find all dependencies of a resource:

SELECT dependencies FROM instances
WHERE address = 'aws_instance.web'

Find resources that depend on a specific resource:

SELECT address FROM instances
WHERE to_jsonb(dependencies) @> '["aws_vpc.main"]'::jsonb

Next steps