Graph Explorer

Graph Explorer provides interactive visualization of dependency relationships between resources in your Terraform state.

Overview

Terraform tracks dependencies between resources to determine the order of operations. Stategraph parses these dependencies and provides interactive visualization to help you understand your infrastructure.

How Dependencies Work

Explicit Dependencies

Resources declare dependencies in Terraform configuration:

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

Implicit Dependencies

Terraform creates dependencies when resources reference each other:

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
}

Dependency Chain

Dependencies form a directed acyclic graph (DAG):

aws_vpc.main
    │
    ├── aws_subnet.public
    │       │
    │       └── aws_instance.web
    │
    └── aws_security_group.web
            │
            └── aws_instance.web

Accessing Graph Explorer

Via UI

  1. Navigate to Insights > Graph in the sidebar
  2. Select a state, then choose a specific resource instance to root the graph
  3. Stategraph renders a focused dependency graph around that instance

Via State Page

  1. Navigate to a state in the UI
  2. Click the Graph or Visualization tab
  3. Explore the state's dependency graph

Graph Interaction

  • Pan: Click and drag the background
  • Zoom: Mouse wheel or pinch gesture
  • Reset: Double-click background to reset view

Node Selection

  • Click node: Select and highlight
  • Double-click: Expand/collapse connected nodes
  • Right-click: Context menu with actions

Scoping the Graph

Graph Explorer is root-centric: it renders the dependency graph around a single instance you select, not the entire state at once. To keep graphs readable, it enforces a connection-count limit. When the graph around your chosen instance would be too densely connected, Graph Explorer refuses to render it and points you to the Blast Radius page instead, which is built for large impact sets.

Understanding the Visualization

Node Representation

Element Meaning
Node color Relationship to the selected root (root, dependency, or dependent)
Node size Number of connections
Node label Resource address

Edge Representation

Element Meaning
Arrow direction Dependency direction (A → B means A depends on B)
Edge thickness Can indicate relationship strength
Edge color Dependency type

Color Coding

Nodes are colored by their relationship to the selected root instance, not by resource-type category:

Color Node Meaning
Accent Root The instance you selected to focus the graph
Neutral (dependency shade) Dependency A resource the root depends on
Neutral (dependent shade) Dependent A resource that depends on the root

Common Patterns

Hub Resources

Resources with many dependents (high in-degree):

       ┌── aws_instance.web1
       │
aws_vpc.main ── aws_instance.web2
       │
       └── aws_rds_cluster.db

These are critical resources - changes affect many others. Use Blast Radius to assess impact.

Leaf Resources

Resources with no dependents (zero out-degree):

aws_security_group.web ── aws_instance.web (leaf)

These are safer to modify - fewer downstream effects.

Module Clusters

Resources within modules form natural clusters:

┌─────────────────────────┐
│  module.vpc             │
│  ┌───────┐  ┌────────┐  │
│  │ vpc   │──│ subnet │  │
│  └───────┘  └────────┘  │
└─────────────────────────┘
           │
           ▼
┌─────────────────────────┐
│  module.compute         │
│  ┌──────────┐           │
│  │ instance │           │
│  └──────────┘           │
└─────────────────────────┘

Use Cases

Understanding Architecture

See how your infrastructure is organized:

  1. Open the graph for a state
  2. Identify major resource groups
  3. Trace data flow through components

Change Planning

Before modifying a resource:

  1. Select the resource in the graph
  2. View all dependent resources
  3. Assess impact of the change
  4. See Blast Radius for detailed analysis

Documentation

Generate architecture diagrams:

  1. Select a root resource
  2. Pan and zoom to frame the relationships
  3. Export or screenshot

Debugging

Understand why operations happen in certain order:

  1. Select a resource
  2. View its dependencies
  3. Understand the execution graph

CLI Access

Get Instances with Dependencies

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

Response includes dependency information:

{
  "results": [
    {
      "address": "aws_instance.web",
      "type": "aws_instance",
      "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 'aws_vpc.main' = ANY(dependencies)

Graph Layout

The graph uses a hierarchical (dagre) layout:

  • Nodes are arranged in dependency tiers (top-to-bottom or left-to-right)
  • Edges flow in a consistent direction
  • Related resources stay near their dependencies

Pan and zoom to navigate. The layout is computed automatically and cannot be rearranged by dragging nodes.

Tips

  1. Start from a focused root - Pick a single instance to anchor the graph
  2. Focus on modules - Module boundaries provide natural groupings
  3. Follow the arrows - Dependencies point from dependent to dependency
  4. Use blast radius - For detailed impact analysis
  5. Compare states - View graphs for different workspaces side by side

Limitations

  • Densely connected graphs are refused rather than rendered; use Blast Radius for large impact sets
  • Some dependencies may not be visible if they're implicit
  • Module dependencies are shown, but module internals require expanding

Next Steps