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 or search for resources
  3. The dependency graph renders automatically

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

Filtering

Filter the graph by:

  • Resource type: Show only specific types
  • Module: Focus on a module
  • Search: Find resources by name

Understanding the Visualization

Node Representation

Element Meaning
Node color Resource type category
Node size Number of connections
Node label Resource address
Node icon Resource type icon (when available)

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

Resources are color-coded by category:

Color Category Examples
Blue Compute aws_instance, aws_lambda_function
Green Network aws_vpc, aws_subnet, aws_security_group
Yellow Storage aws_s3_bucket, aws_ebs_volume
Orange Database aws_rds_cluster, aws_dynamodb_table
Purple IAM aws_iam_role, aws_iam_policy
Gray Other Miscellaneous resources

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. Filter to relevant resources
  2. Arrange the layout
  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 \
  -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 MQL

-- 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 force-directed layout by default:

  • Related resources cluster together
  • Minimizes edge crossings
  • Spreads nodes evenly

Manual Arrangement

For complex graphs:

  1. Drag nodes to desired positions
  2. Layout adjusts around manual placements
  3. Reset to automatic layout if needed

Tips

  1. Start with filters - Large graphs can be overwhelming
  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

  • Very large states (10,000+ resources) may have rendering performance issues
  • Some dependencies may not be visible if they're implicit
  • Module dependencies are shown, but module internals require expanding

Next Steps