Instances

The Instances view provides a comprehensive catalog of all resource instances across all your Terraform states.

Overview

Instances are individual resources managed by Terraform. For example, if you have:

resource "aws_instance" "web" {
  count = 3
  # ...
}

This creates three instances: aws_instance.web[0], aws_instance.web[1], aws_instance.web[2].

Accessing Instances

Via UI

  1. Navigate to Inventory > Instances in the sidebar
  2. Browse the list of all instances
  3. Use filters to narrow results
  4. Click an instance to view details

Via API

First, get your state ID:

export STATEGRAPH_API_KEY="<your-api-key>"
TENANT_ID=$(curl -s -H "Authorization: Bearer $STATEGRAPH_API_KEY" \
  http://localhost:8080/api/v1/user/tenants | jq -r '.results[0].id')
STATE_ID=$(curl -s -H "Authorization: Bearer $STATEGRAPH_API_KEY" \
  "http://localhost:8080/api/v1/tenants/$TENANT_ID/states" | jq -r '.results[0].id')

Then list instances:

curl "http://localhost:8080/api/v1/states/$STATE_ID/instances" \
  -H "Authorization: Bearer $STATEGRAPH_API_KEY"

Response:

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

A root-module resource has address, type, provider, attributes, and dependencies. The
module and sensitive_attributes keys are included only when they have a value, so they are
omitted for root resources and appear only for resources inside a module (or with sensitive
attributes).

Instance Properties

Property Description
address Full Terraform address (e.g., module.vpc.aws_subnet.private[0])
type Resource type (e.g., aws_instance, google_compute_instance)
provider Provider that manages this resource
module Module path if inside a module, null for root
attributes JSON object of all resource attributes
dependencies List of resources this instance depends on

Filtering Instances

When querying with SQL, note that the instances table holds per-instance data
(attributes, dependencies, status). Resource type, provider, and module live on the
resources table — query resources directly, or join on resource_address (see
Query). (The REST /instances response above includes
type/provider/module for convenience.)

By Resource Type

Filter to show only specific resource types:

Type: aws_instance

Or use SQL (resource type lives on resources):

SELECT * FROM resources
WHERE type = 'aws_instance'

By Provider

Filter by cloud provider. The provider value is the full Terraform provider source address
(e.g. provider["registry.terraform.io/hashicorp/aws"]), so match it with LIKE:

-- AWS resources
SELECT * FROM resources
WHERE provider LIKE '%hashicorp/aws%'

-- Google Cloud resources
SELECT * FROM resources
WHERE provider LIKE '%hashicorp/google%'

By Module

Find resources inside modules (the module column is on resources):

-- All resources in modules
SELECT * FROM resources
WHERE module IS NOT NULL

-- Resources in a specific module
SELECT * FROM resources
WHERE module = 'module.vpc'

-- Root module only
SELECT * FROM resources
WHERE module IS NULL

By State

Filter by Terraform state. state_id is the state's UUID (look it up by name in the states table):

SELECT * FROM instances
WHERE state_id = '550e8400-e29b-41d4-a716-446655440000'

To filter by state name instead, join to states:

SELECT * FROM instances AS i
INNER JOIN states AS s ON i.state_id = s.id
WHERE s.name = 'networking'

By Address Pattern

Search by address:

SELECT * FROM instances WHERE address = 'aws_db_instance.database'
SELECT * FROM instances WHERE address LIKE 'module.vpc.%'

Instance Details

Clicking an instance shows:

Overview

  • Resource address
  • Resource type
  • Provider
  • Module path
  • State name and workspace

Attributes

  • Full JSON attributes from Terraform state
  • Nested attribute navigation
  • Attribute search

Dependencies

  • Resources this instance depends on (upstream)
  • Resources that depend on this instance (downstream)
  • Visual dependency graph

Common Use Cases

Find All EC2 Instances

SELECT i.address, i.attributes->>'instance_type' AS instance_type
FROM instances AS i
INNER JOIN resources AS r
  ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.type = 'aws_instance'

Find Resources by Tag

SELECT address, attributes->'tags'->>'Name' as name
FROM instances
WHERE attributes->'tags'->>'Environment' = 'production'

Count by Instance Type

SELECT i.attributes#>>'{instance_type}' AS instance_type, count(*) AS instance_count
FROM instances AS i
INNER JOIN resources AS r
  ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.type = 'aws_instance'
GROUP BY i.attributes#>>'{instance_type}'
ORDER BY i.attributes#>>'{instance_type}'

Find Resources Without Tags

SELECT address, resource_address
FROM instances
WHERE attributes->'tags' IS NULL
   OR attributes->>'tags' = '{}'

List Security Groups

SELECT
  i.address,
  i.attributes->>'name' AS name,
  i.attributes->>'vpc_id' AS vpc
FROM instances AS i
INNER JOIN resources AS r
  ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.type = 'aws_security_group'

Bulk Operations

Export to CSV

  1. Run a query in the Query view
  2. Click Export > CSV
  3. Download the results

Export to JSON

curl "http://localhost:8080/api/v1/mql?q=SELECT%20*%20FROM%20instances" \
  -H "Authorization: Bearer $STATEGRAPH_API_KEY" \
  > instances.json

Best Practices

  1. Use filters - Don't browse all instances at once for large deployments
  2. Leverage types - The Types view is better for understanding resource distribution
  3. Save queries - Use Dashboards to save frequently used instance filters
  4. Check dependencies - Use blast radius analysis before changing resources

Next Steps