Manage module versions

You can manage the lifecycle of module versions in your organization’s private registry by deprecating or revoking module versions as you stop maintaining and supporting those versions.

Deprecating a module version adds warnings to the module's registry page and warnings in the run outputs of any users of that version.

Revoking a module version adds warnings to the module's registry page, warnings in the run outputs of existing users, and prevents new users from consuming that version.

You can also deprecate or revoke module versions using the HCP Terraform API.

Overview

Deprecating a private module version enables platform teams and module authors to signal to consumers that a version is still maintained and supported but is not recommended. HCP Terraform urges existing and new users of deprecated versions to upgrade that version in their configuration. The private registry also denotes which module versions are deprecated, alerting new consumers to use a non-deprecated version.

You can revert a module version’s deprecation if you decide to continue supporting that version. Reverting a version’s deprecation removes all warnings from that version in both the module’s registry page and the run outputs of that version’s consumers.

You can revoke a private module to mark that you not longer support it. Revoking a module version adds similar warnings to deprecation in a module's registry page and the run outputs of current consumers. Revoking a module version also blocks the runs of any new users attempting to add that version to their configuration.

Reverting a module version’s revocation sets it back to a deprecated state, signaling that the version is still maintained and supported but not recommended.

Requirements

To deprecate a module version or to revert a version’s deprecation:

• you must have permission to manage private registry modules
• the module must be in the private registry
• you must be a member of an organization on the HCP Terraform Plus edition

To revoke or to revert a module version’s status:

• you must have permission to manage private registry modules
• the module must be in an organization's private registry
• you must be a member of an organization on the HCP Terraform Premium edition

Deprecate a module version

To deprecate a module version, perform the following steps:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to your organization.
2. Choose Registry in the sidebar then find the module you want to deprecate a version of.
3. Open the Manage module for organization dropdown.
4. Select a module version for deprecation.
5. You can optionally provide an explanation in the Reason for module deprecation field to help users understand why this module version is being deprecated. This custom message is displayed to module users in deprecation warnings.
6. You can optionally enter a URL into the Link to additional information field if there is a website where consumers can learn more about that module version’s deprecation.
7. Click Deprecate.

If the module version you are deprecating has the No-code ready pin, then HCP Terraform lets you select another version to create no-code modules from. We recommend adding the No-code ready pin to another non-deprecated module version so that users provisioning workspaces from your module can use a version that you plan to continue supporting.

Deprecation warnings

After you deprecate a module version, consumers of that version receive warnings in their operation outputs urging them to update that version in both HCP Terraform and the Terraform CLI.

If you provided a reason for a module version’s deprecation, then deprecation warnings contain that reason:

Found the following deprecated module versions, consider using an updated version.
<module-name-version><optional-reason-for-module-deprecation>

A run’s output mode affects where a version's deprecation warning appears. If a workspace is in the default Structured Run Output mode, then module deprecation warnings show up under a run’s Diagnostics dropdown.

If a run is in the Console UI mode, module deprecation warnings appear in the run’s logs:

Warning: Deprecated modules found, consider installing an updating version. The following are affected:
Version X.X.X of <module-name>

Revert the deprecation of a module version

To revert a module version’s deprecation, perform the following steps:

1. Sign in to HCP Terraform or Terraform Enterprise and navigate to your organization.
2. Choose Registry in the sidebar, then find the module version you want to revert the deprecation of.
3. Open the Manage module for organization dropdown.
4. Select Revert module version deprecation X.X.X.
5. Click Revert Deprecation.

Reverting the deprecation of a module version removes all warnings from that version in both the module’s registry page and in the run outputs of that module version’s consumers.

Revoke a module version

To revoke a module version, perform the following steps:

1. Sign in to HCP Terraform and navigate to your organization.
2. Choose Registry in the sidebar, then select the module version you want to revoke.
3. If you have not already, deprecate the module version you want to revoke.
4. Open the Manage module for organization dropdown.
5. Optionally explain why you are deprecating this module version in the Reason for module revocation field. This custom message is displayed to users in revocation run warnings and on the registry page.
6. Optionally, enter a URL into the Link to additional information field if there is a website where consumers can learn more about that module version’s revocation.
7. Click Revoke.

If the module version you are revoking has the No-code ready pin, you must select another version to create no-code modules from. This is to ensure users provisioning workspaces from your module use a version that you are currently supporting.

Revocation warnings

Like deprecation, revoking a module version displays a warning on the private registry and sends current consumers warnings in operation outputs in HCP Terraform and the Terraform CLI. The difference between deprecation and revocation is that Terraform blocks new consumers from using a revoked module version by erroring out in runs.

After you revoke a module version, current consumers of that version receive warnings in their operation outputs in HCP Terraform and the Terraform CLI. If you provided a reason for a module version’s revocation, HCP Terraform displays that reason to users in run outputs:

This run references revoked module versions, but this will proceed due to referencing a previously used module version.
Module version X.X.X of <module-name> is revoked.

<optional-custom-message>

A run’s output mode affects where a version's revocation warnings appear. If a workspace is in the default Structured Run Output mode, then module revocation warnings show up under a run’s Diagnostics dropdown.

If a run is in the Console UI mode, module revocation warnings appear in the run’s logs:

Warning: This run will continue because it references a revoked module version that was previously used in this workspace. Net new workspaces that reference this module version will be blocked from making new runs.
Version X.X.X of <module-name-version>

<optional-custom-message>

If a new user attempts to add a revoked module version to their configuration, their runs fail. If you provided a reason for a module version’s revocation, HCP Terraform displays that reason to users in run outputs:

This run references revoked module versions, this run will not proceed.
Module version <module-version> of <module-name> is revoked.
<custom-message>

A run’s output mode affects where a module revocation’s warning appears. If a run set to the default Structured Run Output mode, then module revocation warnings show up under a run’s Diagnostics dropdown.

If a run is in the Console UI mode, module revocation warnings appear in the run’s logs:

│ Alert: Revoked modules found, this run will not continue. The following modules have been revoked:
│
│ Version X.X.X of <module-name>
│
│ <custom-message>

Revert the revocation of a module version

When you revert the revocation of a module version, HCP Terraform sets that version as deprecated, signaling that it is still maintained and supported but not recommended. Deprecated module versions still produce warnings in the registry and run outputs, but new users can still use them.

To revert a module version’s revocation, perform the following steps:

1. Sign in to HCP Terraform and navigate to your organization.
2. Choose Registry in the sidebar, then find the revoked module version you want to revert.
3. Open the Manage module for organization dropdown.
4. Select Revert module version revocation X.X.X.
5. Click Revert.