Monitor Private Module Version Counts in Terraform Enterprise to Prevent Performance Degradation

Introduction

This guide provides a solution for monitoring the number of versions for each private module in your Terraform Enterprise registry. Proactive monitoring helps prevent performance degradation and maintain the stability of your instance.

Problem

Terraform Enterprise instances that contain private modules with a very large number of versions may experience significant performance issues. As the version count for a module increases, queries against the PostgreSQL database backing the Private Registry become increasingly expensive. This can negatively impact both the UI and API responsiveness across the platform.

Symptoms

Common indicators of this issue include:

Slow UI and API responses, especially when browsing or interacting with the Private Module Registry
Increased CPU or memory utilization on the PostgreSQL database
PostgreSQL logs showing errors related to materialized views for the registry, such as:

ERROR: duplicate key value violates unique constraint "pg_class_relname_nsp_index"
DETAIL: Key (relname, relnamespace)=(views_module_1_versions_memoized_submodules_id_idx39001, 16476) already exists.

Warnings indicating that large modules are not being memoized due to excessive version counts, for example:

{
  "@level": "warn",
  "@message": "... GET /v1/modules/Test/mymodule/aws/versions ...",
  "module_versions_count": 438,
  "warning": "large module was not memoized, memoization created"
}

Prerequisites

Before implementing monitoring, ensure the following requirements are met:

Administrator access to the Terraform Enterprise instance
A Terraform Enterprise user or team API token with permission to read Private Registry modules
Access to an execution environment capable of making authenticated HTTPS requests and processing API responses
An alerting or monitoring system to surface threshold breaches

Cause

The performance degradation is caused by the accumulation of a high number of versions for individual private modules. The Terraform Enterprise registry API must perform complex database queries to retrieve and process version metadata. As version counts grow into the hundreds or thousands, these queries become resource-intensive and introduce contention in the PostgreSQL database, affecting registry operations and overall application performance.

Solution

Terraform Enterprise does not currently offer built-in monitoring or alerting for private module version counts. As a result, proactive detection of excessive version growth requires leveraging the Terraform Enterprise API and integrating with external monitoring or alerting systems.

This approach allows teams to monitor private module version counts and alert when predefined thresholds are exceeded, enabling early identification of problematic growth before it impacts platform performance

Step 1: Identify Modules to Monitor

Determine which private modules should be included in monitoring. Priority should be given to:

Modules that are frequently published or auto-versioned
Shared or foundational modules used across multiple workspaces
Modules maintained by CI/CD pipelines

Each module is uniquely identified by:

Organization (namespace)
Module name
Provider (for example: aws, azurerm, google)

Step 2: Query the Private Registry Versions Endpoint

Terraform Enterprise exposes an API endpoint that returns metadata for all versions of a given private module. This endpoint should be queried on a recurring basis to determine the current version count.

Terraform Enterprise Private Registry Modules API

Implementation considerations:

Authenticate using a Terraform Enterprise API token
Ensure the token has read access to the Private Registry
Retrieve version metadata for each monitored module
Extract the total number of versions returned in the response

The output of this step should be a numeric version count per module.

Step 3: Compare Version Counts Against a Threshold

Define an acceptable upper limit for the number of versions per module.

Recommended starting threshold:

100 versions per module

For each monitored module:

Compare the retrieved version count against the defined threshold
Treat threshold breaches as warnings rather than immediate failures
Escalate alerts if growth continues or accelerates over time

Step 4: Emit Metrics or Trigger Alerts

Forward version count data and threshold breaches into your existing monitoring or alerting systems.

Common alerting approaches include:

Emitting custom metrics representing module version counts
Sending structured events or logs for evaluation by alerting rules
Triggering notifications when thresholds are exceeded

Typical alert destinations include:

Email
Slack
PagerDuty or other incident management platforms

Alerts should clearly identify:

The affected module
Current version count
Defined threshold
Recommended next steps (review or cleanup)

Step 5: Schedule Regular Monitoring

Run the monitoring logic on a consistent schedule to ensure timely detection.

Typical cadences include:

Weekly for most environments
Daily for high-churn or automated publishing environments

Outcome

After implementing this solution, you will have an automated system to monitor private module version counts. This proactive approach allows you to identify modules with excessive versions before they cause performance degradation, enabling you to apply cleanup policies and maintain a healthy Terraform Enterprise instance.

Additional Information

Best Practices for Module Version Management

Monitor Regularly
Run version checks on a predictable schedule.
Establish Cleanup Policies
Define when and how older or unused module versions should be deprecated or removed.
Analyze Growth Trends
Track version counts over time to identify high-risk publishing patterns.
Automate Where Appropriate
Consider automating cleanup of unused or unpinned versions as part of release workflows.