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\"]",
      "module": null,
      "attributes": { ... },
      "dependencies": ["aws_subnet.main", "aws_security_group.web"]
    }
  ]
}

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

By Resource Type

Filter to show only specific resource types:

Type: aws_instance

Or use MQL (join with resources table for type filtering):

SELECT i.*
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.type = 'aws_instance'

By Provider

Filter by cloud provider (join with resources table):

-- AWS resources
SELECT i.*
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.provider LIKE '%aws%'

-- Google Cloud resources
SELECT i.*
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.provider LIKE '%google%'

By Module

Find instances inside modules (join with resources table):

-- All instances in modules
SELECT i.*
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.module IS NOT NULL

-- Instances in specific module
SELECT i.*
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.module = 'module.vpc'

-- Root module only
SELECT i.*
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.module IS NULL

By State

Filter by Terraform state:

SELECT i.*, s.name as state_name
FROM instances i
JOIN states s ON i.state_id = s.id
WHERE s.name = 'networking'

By Address Pattern

Search by address:

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

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 i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.type = 'aws_instance'

Find Resources by Tag

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

Count by Instance Type

SELECT i.attributes->>'instance_type' as instance_type, count(*) as count
FROM instances i
JOIN resources 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 instance_type

Find Resources Without Tags

SELECT i.address, r.type
FROM instances i
JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id
WHERE r.type LIKE 'aws_%'
  AND (i.attributes->'tags' IS NULL
       OR i.attributes->>'tags' = '{}')

List Security Groups

SELECT
  i.address,
  i.attributes->>'name' as name,
  i.attributes->>'vpc_id' as vpc
FROM instances i
JOIN resources 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