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:

SELECT *
FROM instances
WHERE type = 'aws_instance'

By Provider

Filter by cloud provider:

-- AWS resources
SELECT *
FROM instances
WHERE provider = 'aws'

-- Google Cloud resources
SELECT *
FROM instances
WHERE provider = 'google'

By Module

Find instances inside modules:

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

-- Instances in specific module
SELECT *
FROM instances
WHERE module = 'module.vpc'

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

By State

Filter by Terraform state:

SELECT *
FROM instances
WHERE state_id = 'networking'

By Address Pattern

Search by address:

SELECT * FROM instances WHERE address = 'aws_db_instance.database'
SELECT * FROM instances WHERE module IS NOT NULL

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 address, attributes->>'instance_type' as instance_type
FROM instances
WHERE 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 attributes->>'instance_type' as instance_type, count(*) as count
FROM instances
WHERE type = 'aws_instance'
GROUP BY attributes->>'instance_type'
ORDER BY instance_type

Find Resources Without Tags

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

List Security Groups

SELECT
  address,
  attributes->>'name' as name,
  attributes->>'vpc_id' as vpc
FROM instances
WHERE 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