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 *
FROM resources
WHERE module IS NULL

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

Module Analysis

Resources per Module

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

Types per Module

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

Top-Level Modules

List all modules and identify top-level ones (those without nested module. segments):

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

Nested Module Depth

Find deeply nested modules:

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

Module Usage Patterns

Find Duplicate Module Usage

Identify where the same module is used multiple times:

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

Module Resource Distribution

See how resources are distributed between root and modules:

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

Resources by Module Type

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

Common Module Patterns

VPC Module Resources

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

EKS/Kubernetes Modules

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

Database Modules

SELECT module, type, count(*) as count
FROM resources
WHERE module = 'module.rds'
GROUP BY module, type
ORDER BY module, 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 module IS NULL THEN 'root' ELSE 'module' END as location,
  count(*) as resources,
  count(DISTINCT type) as types
FROM resources
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