Deprecate module versions

Deprecating a module version in your organization’s private registry adds warnings to the module's registry page and warnings in the run outputs of any users of that version. Once you have deprecated a module version, you can revert it back to remove the warnings from that version.

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

Background

Deprecating a module version allows platform teams and module authors to mark the end-of-life for specific private module versions. Deprecating module versions helps consumers recognize versions that are still maintained and supported but not recommended.

You can deprecate a private module version to warn existing users to upgrade that version in their configuration. The private registry also denotes which module versions are deprecated, alerting new consumers that they should use a non-deprecated version instead.

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

Deprecate a module version

To deprecate a module version, perform the following steps:

1. Navigate to your organization’s private registry and find the module you want to deprecate a version of.
2. Open the Manage module for organization dropdown.
3. Select a module version for deprecation.
4. 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.
5. 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.
6. 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 the warning users receive contains that reason and the following message:

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 module deprecation’s warning appears. If a run set to 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. Navigate to your organization’s private registry and find the deprecated module version you want to revert the deprecation of.
2. Open the Manage module for organization dropdown.
3. Select Revert module version deprecation X.X.X.
4. 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.