Forem: Daniel Westgaard

How to Find Every Consumer of Your Terraform Module

Daniel Westgaard — Wed, 15 Apr 2026 09:30:27 +0000

You maintain a shared Terraform module. You need to make a breaking change. Which repos across your org actually source it — and at which version? Here's why the answer is harder than it should be.

You maintain an internal Terraform module. Maybe it's terraform-aws-vpc or modules/rds-cluster or a shared networking baseline that half the org builds on top of. It started as a convenience — one team wrote a good VPC module, others adopted it, and now it's load-bearing infrastructure for dozens of repos.

Then you need to change it. Maybe you're upgrading the AWS provider from v4 to v5 and the module interface needs to change. Maybe you're deprecating a variable that seemed like a good idea eighteen months ago. Maybe you're fixing a security misconfiguration and the fix requires consumers to pass a new required variable.

The question is simple: which repos across our org source this module, and at which version?

If you can't answer this, you're deploying blind. You either make the change and wait for terraform plan failures to trickle in across teams, or you don't make the change at all and let the tech debt compound. Neither option is good.

The scenario

Here's what this typically looks like. Your platform team publishes a module, and repos across the org consume it:

module "vpc" {
  source = "git::https://gitlab.company.com/infra/terraform-aws-vpc.git?ref=v2.3.0"

  cidr_block = "10.0.0.0/16"
  environment = var.environment
}

Some repos pin to a specific Git tag. Some pin to a branch. Some point at main with no ref at all, which means they're consuming whatever happens to be at HEAD when they next run terraform init. Some source the module from your internal Terraform registry instead of Git. Some use a relative path because the module lives in a monorepo alongside the consuming root module.

You need to find all of them, understand which version each one uses, and figure out which teams to notify before you push the breaking change. Right now, most teams do this by grepping, searching the Terraform registry UI, or asking in Slack. None of these give you a complete answer.

What existing tools give you (and where they stop)

Several tools address pieces of the Terraform module consumer problem. Each one is useful in its own context. None of them answer the full question.

HCP Terraform (Terraform Cloud) Module Registry

If you use HCP Terraform or Terraform Enterprise, the private module registry tracks which workspaces consume a published module. The registry UI shows a module's versions, usage statistics, and which workspaces reference it.

This works within the HCP Terraform ecosystem. The limitation is scope: it only sees modules published to its registry and consumed by its workspaces. If a team sources the module directly via a Git URL — which is extremely common, especially in orgs that adopted Terraform before the private registry existed — that consumption is invisible. If some repos use HCP Terraform and others use a different backend (local state, S3, Spacelift, env0, Atlantis), you're seeing a partial picture. It's also worth noting that the HCP Terraform free tier was discontinued in March 2026, so this option now requires a paid plan.

Spacelift / Scalr / env0

Spacelift has the most advanced module consumer tracking of the orchestration platforms. Its module registry tracks which stacks consume each module version, and trigger policies can automatically kick off runs on consumer stacks when a new module version is published. Scalr offers a modules report that shows which modules and versions are used across all workspaces, including which workspaces are running outdated versions. env0 has similar workspace-level dependency awareness.

These are genuinely useful capabilities — if all your Terraform runs flow through a single platform. The limitation is the same for all of them: they only see what's inside their own ecosystem. If your org uses Spacelift for production infrastructure but engineers run terraform plan locally for development, or if one team uses Atlantis while another uses GitHub Actions with raw terraform commands, no single orchestrator has the full picture. And none of them see the module source references in the code — they see module consumption at the workspace execution level, which is a different layer.

`terraform providers` and `terraform graph`

Terraform's built-in terraform graph command outputs a DOT-format dependency graph for a single root module. terraform providers lists the providers required by a configuration and its modules.

These commands work per-configuration, not per-org. They answer "what does this root module depend on?" They don't answer "which root modules across my org depend on that shared module?" You'd need to clone every repo, run the command in every Terraform root, and aggregate the results — which is essentially building a custom scanner.

Grep / GitHub code search

The most common approach. Clone everything (or use GitHub's code search), and search for the module source URL:

grep -r "terraform-aws-vpc" --include="*.tf" ~/repos/

This finds direct string matches. It works for a one-off audit. But it breaks down in several ways that matter:

It doesn't resolve registry sources. source = "app.terraform.io/company/vpc/aws" and source = "git::https://gitlab.company.com/infra/terraform-aws-vpc.git" might reference the same module — grep treats them as unrelated strings.
It doesn't extract versions. You can see that a repo references the module, but parsing out ?ref=v2.3.0 or the version = "~> 2.0" constraint from a registry source requires additional work per match.
The results are stale immediately. The search reflects the state of whatever you cloned. By tomorrow, three repos might have changed their module references.
At 100+ repos, it takes long enough that nobody does it proactively. It becomes an incident response activity, not a planning tool.

Renovate

Renovate understands Terraform module sources and can open pull requests when a new version is available. It parses source and version attributes in .tf files and supports Git refs, registry modules, and GitHub releases.

Like with Docker images, Renovate implicitly knows who consumes what — it's configured per-repo and has parsed the module sources. But it doesn't expose this as a queryable view. You can't ask Renovate "which repos in my org source terraform-aws-vpc?" It's a dependency updater, not a dependency mapper. It reacts after a new version exists. It doesn't give you the blast radius before you publish the new version.

Why this is harder than it looks

Terraform module sourcing is more complex than most people realise, because the same module can be referenced through at least five different source types — and each one looks completely different in the HCL.

Git sources are the most common for internal modules:

module "vpc" {
  source = "git::https://gitlab.company.com/infra/terraform-aws-vpc.git?ref=v2.3.0"
}

The URL might use HTTPS or SSH. The ref might be a tag, a branch, or a commit SHA. Some teams use the git:: prefix, others rely on Terraform's URL inference. The same module can appear as:

source = "git::https://gitlab.company.com/infra/terraform-aws-vpc.git?ref=v2.3.0"
source = "git@gitlab.company.com:infra/terraform-aws-vpc.git?ref=v2.3.0"
source = "gitlab.company.com/infra/terraform-aws-vpc?ref=v2.3.0"

These all point at the same module. A grep for one form misses the others.

Registry sources use a completely different syntax:

module "vpc" {
  source  = "app.terraform.io/company/vpc/aws"
  version = "~> 2.0"
}

This references the same underlying module, but through the registry. The version constraint is in a separate attribute, not in the source URL. Matching this to the Git-sourced references requires knowing that the registry module company/vpc/aws maps to the Git repo infra/terraform-aws-vpc.

Local paths appear when modules live alongside root configurations:

module "vpc" {
  source = "../../modules/vpc"
}

This is a dependency on an internal module, but there's no URL to grep for. The relationship is purely structural — you need to resolve the relative path within the repo's directory tree.

GitHub/GitLab shorthand sources add another variant:

module "vpc" {
  source = "github.com/company/terraform-aws-vpc?ref=v2.3.0"
}

Terraform interprets this as a Git clone from GitHub, but the syntax differs from both the explicit git:: form and the registry form.

Subdirectory references complicate things further:

module "vpc_endpoints" {
  source = "git::https://gitlab.company.com/infra/terraform-aws-vpc.git//modules/endpoints?ref=v2.3.0"
}

The // separator means "clone this repo, then use the modules/endpoints subdirectory." This is a dependency on the same repo but a different module path within it. A consumer tracking system needs to handle both the repo-level relationship and the subpath.

Then there's the transitive problem. Module A sources module B, which sources module C. If you change module C, both B and A are affected — but A never mentions C anywhere in its code. Understanding the full blast radius requires resolving the entire chain, not just direct consumers.

None of the tools in the previous section handle all of these source types and resolve them to a unified view. This is why teams keep falling back to grep and tribal knowledge — and why both keep failing at scale.

What the full answer requires

To reliably answer "who consumes this Terraform module," you need a system that:

Scans every repo in the org, not just those registered in a specific orchestration platform
Parses all five source types — Git URLs (HTTPS and SSH), registry sources, local paths, GitHub/GitLab shorthand, and subdirectory references — and normalises them to a single identity per module
Extracts version constraints from both ?ref= parameters in Git sources and version attributes in registry sources
Resolves transitive dependencies so you can see not just direct consumers but the full downstream blast radius
Keeps the graph current through scheduled or event-triggered rescans, not one-off audits
Makes the result queryable: "show me every consumer of terraform-aws-vpc, grouped by version, with the team that owns each consuming repo"

This is one of the specific problems Riftmap is built to solve. It scans a GitLab or GitHub org, parses every .tf file across every repo, resolves all five module source types to a unified dependency graph, and lets you click on any module to see every consumer — direct and transitive — with the version each one pins to.

The result: before you push the breaking change, you open the graph, click the module, and see exactly which repos and teams are affected. You know who to notify. You know who's still on v1.x and who's already on v2.x. You know which repos pin to main and will break immediately versus which pin to a tag and have time to migrate.

No grepping. No Slack polling. No "let's just push it and see who complains."

How is your team solving this today? I'd genuinely like to know — drop a comment or find me at riftmap.dev.

How to Find Every Consumer of Your Docker Base

Daniel Westgaard — Mon, 13 Apr 2026 19:16:20 +0000

You maintain a shared base image. A CVE drops. Which repos are affected? Here's why the answer is harder than it should be.

You maintain an internal Docker base image. Maybe it's platform/node-base or company/python-runtime. A dozen repos use it. Or thirty. Or you're not sure how many, because nobody's counted since the last team reorganisation.

Then a critical CVE hits the base OS layer, and you need to push a patched version. The question that matters is simple: which repos across our org pull this image, and at which version?

This should be easy to answer. It isn't.

The scenario

Here's what this looks like in practice. Your platform team builds and publishes registry.company.com/platform/base-image. Across the org, Dockerfiles reference it:

FROM registry.company.com/platform/base-image:v2.1

Some repos pin to a specific tag. Some use latest. Some have ARG-parameterized FROM statements where the tag is injected at build time. Some reference the image not in a Dockerfile but in a docker-compose.yml or a CI pipeline config.

You need to find all of them, check which version each one uses, and coordinate the update. Right now, most teams do this by grepping, asking on Slack, or checking CI logs. None of these give you a complete, current answer.

What existing tools give you (and where they stop)

Several tools address parts of the Docker base image problem. Each one is useful. None of them answer the full question.

Docker Scout

Docker Scout analyzes a built image and tells you what base image it uses, whether that base is outdated, and what vulnerabilities it contains. docker scout recommendations will suggest updated base images with fewer CVEs.

This is valuable, but it works per-image, not per-org. It answers "what base image does this image use?" It doesn't answer "which of my 200 repos use this base image?" You'd need to run Scout against every image in your registry and correlate the results back to source repos — which is a project in itself.

Renovate

Renovate detects FROM statements in Dockerfiles and can open pull requests when a newer tag is available. It implicitly knows who consumes what, because it's configured per-repo and parses the Dockerfiles.

But Renovate doesn't expose this as a queryable view. You can't ask Renovate "show me every repo that references platform/base-image." It reacts when a new version appears. It doesn't give you the pre-release blast radius: before you push the patched image, which repos and teams will need to update?

Backstage / Roadie Tech Insights

Roadie (a managed Backstage provider) has a Tech Insights feature that can parse Dockerfiles via regex, extract base image versions, and create scorecards tracking migration progress. This is the closest existing solution to the consumer-tracking problem.

The limitation is that it requires Backstage to be set up with catalog-info.yaml per repo. You're tracking Docker base images through a service catalog that depends on manual registration. If a repo isn't in the catalog, its Dockerfile is invisible.

Container registries

Your registry (Docker Hub, Harbor, ACR, ECR) knows which images have been pulled and how often. Some provide pull statistics by tag. But pull logs don't tell you which source repo initiated the pull. A CI pipeline pulling base-image:v2.1 shows up as a pull event, not as "repo frontend-api depends on this image via its Dockerfile on line 3."

Grep

The fallback everyone uses. Clone all the repos, run grep -r "platform/base-image", assemble the results. It works once. The results are stale immediately. It misses parameterized FROM statements, compose files, and CI configs. And at a hundred repos, it takes long enough that nobody does it proactively.

Why this is harder than it looks

The core difficulty is that Docker base image dependencies live in multiple places and multiple formats.

Dockerfiles are the obvious source, but FROM statements can use ARG substitution:

ARG BASE_TAG=v2.1
FROM registry.company.com/platform/base-image:${BASE_TAG}

A simple grep for the image name finds this. A simple grep for the version doesn't, because the version is in a variable.

Docker Compose files reference images differently:

services:
  api:
    image: registry.company.com/platform/base-image:v2.1

This is a dependency on the same image, declared in a completely different file format.

CI pipeline configs often pull images directly:

build:
  image: registry.company.com/platform/base-image:v2.1
  script:
    - make build

A GitLab CI image: directive or a GitHub Actions container: field is another consumption point for the same base image, and it's in yet another file.

Then there's the producer-side problem. Knowing which repos consume the image is half the story. You also need to know which repo builds it. That's usually a CI pipeline with docker build and docker push commands, not something declared in a manifest. Connecting the consumer graph to the producer requires cross-referencing multiple file types within and across repos.

No single tool today connects all of these surfaces into one view.

What the full answer requires

To reliably answer "who consumes this base image," you need a system that:

Scans every repo in the org, not just the ones registered in a catalog
Parses Dockerfiles, Compose files, and CI configs, because the same image can be referenced in all three
Handles variable substitution in FROM statements by resolving ARG defaults
Detects which repos produce which images by scanning CI configs for build and push commands
Keeps the results current through scheduled or event-triggered rescans
Makes the graph queryable: "show me every consumer of platform/base-image, grouped by version"

This is one of the specific problems I'm building Riftmap to solve. It scans a GitLab or GitHub org, parses Dockerfiles (including multi-stage builds, ARG defaults, and Compose files), detects which repos produce which images via CI config analysis, and builds a cross-repo dependency graph you can query by artifact.

The result: when that CVE drops, you click on the base image in the graph and immediately see every repo that depends on it, which version each one uses, and who owns them. No grepping. No Slack archaeology. No stale spreadsheet from last quarter.

How is your team solving this today? I'd genuinely like to know — drop a comment or find me at riftmap.dev.

Forem: Daniel Westgaard

How to Find Every Consumer of Your Terraform Module

The scenario

What existing tools give you (and where they stop)

HCP Terraform (Terraform Cloud) Module Registry

Spacelift / Scalr / env0

terraform providers and terraform graph

Grep / GitHub code search

Renovate

Why this is harder than it looks

What the full answer requires

How to Find Every Consumer of Your Docker Base

The scenario

What existing tools give you (and where they stop)

Docker Scout

Renovate

Backstage / Roadie Tech Insights

Container registries

Grep

Why this is harder than it looks

What the full answer requires

`terraform providers` and `terraform graph`