Modules

The Modules view shows Terraform modules used across your states and the resources they contain.

Overview

Terraform modules are reusable containers for multiple resources. Stategraph tracks:

  • Module hierarchy and nesting
  • Resources within each module
  • Instance counts per module
  • Module usage across states

Accessing Modules

Via UI

  1. Navigate to Inventory > Modules in the sidebar
  2. Browse the module tree
  3. Expand modules to see nested modules and resources
  4. Click a module to view details

Via API

List modules (see instances docs for getting STATE_ID):

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

Response:

{
  "results": [
    {
      "name": "module.vpc",
      "instance_count": 25,
      "resource_count": 10
    },
    {
      "name": "module.vpc.module.subnets",
      "instance_count": 12,
      "resource_count": 4
    }
  ]
}

Module Properties

Property Description
name Full module path (e.g., module.vpc.module.private_subnets)
instance_count Total resource instances in this module
resource_count Unique resource types in this module

Understanding Module Paths

Module paths reflect the Terraform module hierarchy:

root                           # Root module (module path is null)
├── module.vpc                 # VPC module
│   ├── module.subnets        # Subnets nested in VPC
│   └── module.nat            # NAT nested in VPC
├── module.eks                # EKS module
│   └── module.node_groups    # Node groups nested in EKS
└── module.rds                # RDS module

In MQL queries (module information is on the resources table):

-- Root module resources (not in any 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 IS NULL

-- Resources in module.vpc
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'

-- Resources in any VPC-related 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 LIKE 'module.vpc%'

Module Analysis

Resources per Module

SELECT r.module, count(*) as resources
FROM resources r
WHERE r.module IS NOT NULL
GROUP BY r.module
ORDER BY r.module

Types per Module

SELECT r.module, r.type, count(*) as count
FROM resources r
WHERE r.module IS NOT NULL
GROUP BY r.module, r.type
ORDER BY r.module, r.type

Top-Level Modules

SELECT r.module, count(*) as resources
FROM resources r
WHERE r.module IS NOT NULL
  AND r.module NOT LIKE '%module.%module.%'  -- No nested modules
GROUP BY r.module
ORDER BY r.module

Nested Module Depth

Find deeply nested modules:

SELECT r.module
FROM resources r
WHERE r.module IS NOT NULL
GROUP BY r.module
ORDER BY r.module

Module Usage Patterns

Find Duplicate Module Usage

Identify where the same module is used multiple times:

-- Count module usage across states
SELECT r.module, count(DISTINCT r.state_id) as states_using
FROM resources r
WHERE r.module IS NOT NULL
GROUP BY r.module
ORDER BY r.module

Module Resource Distribution

See how resources are distributed between root and modules:

SELECT
  CASE
    WHEN r.module IS NULL THEN 'root'
    ELSE 'in_module'
  END as location,
  count(*) as count
FROM resources r
GROUP BY location
ORDER BY location

Resources by Module Type

SELECT r.module, r.type, count(*) as count
FROM resources r
WHERE r.module = 'module.vpc'
GROUP BY r.module, r.type
ORDER BY r.type

Common Module Patterns

VPC Module Resources

SELECT r.type, count(*) as count
FROM resources r
WHERE r.module LIKE '%vpc%'
GROUP BY r.type
ORDER BY r.type

EKS/Kubernetes Modules

SELECT r.module, r.type, count(*) as count
FROM resources r
WHERE r.module LIKE '%eks%' OR r.module LIKE '%kubernetes%'
GROUP BY r.module, r.type
ORDER BY r.module, r.type

Database Modules

SELECT r.module, r.type, count(*) as count
FROM resources r
WHERE r.module LIKE '%rds%'
   OR r.module LIKE '%database%'
   OR r.module LIKE '%db%'
GROUP BY r.module, r.type
ORDER BY r.module, r.type

Best Practices

Module Organization

  1. Consistent naming - Use clear, descriptive module names
  2. Shallow nesting - Avoid deeply nested modules (3+ levels)
  3. Single responsibility - Each module should have a clear purpose
  4. Version tracking - Track module versions in source control

Monitoring Module Usage

  1. Track growth - Monitor instance counts over time
  2. Identify sprawl - Watch for module proliferation
  3. Review dependencies - Understand cross-module dependencies

Module vs Root Resources

Compare resources in modules vs root:

-- Summary
SELECT
  CASE WHEN r.module IS NULL THEN 'root' ELSE 'module' END as location,
  count(*) as resources,
  count(DISTINCT r.type) as types
FROM resources r
GROUP BY location
ORDER BY location

Generally, well-organized Terraform should have: - Infrastructure modules (VPC, EKS, RDS) - Application-specific resources in root or app modules - Shared modules for common patterns

Next Steps