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.
Note: Module deprecation is available in the HCP Terraform Plus Edition. Refer to HCP Terraform pricing for details.
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.
Note: The ability to deprecate module versions is in public beta. All APIs and workflows are subject to change.
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:
- Navigate to your organization’s private registry and find the module you want to deprecate a version of.
- Open the Manage module for organization dropdown.
- Select a module version for deprecation.
- 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.
- 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.
- 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.
Note: Only workspaces in the remote or agent execution modes can receive warnings for a module version’s deprecation.
If you provided a reason for a module version’s deprecation, then the warning users receive contains that reason and the following message:
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:
Revert the deprecation of a module version
To revert a module version’s deprecation, perform the following steps:
- Navigate to your organization’s private registry and find the deprecated module version you want to revert the deprecation of.
- Open the Manage module for organization dropdown.
- Select Revert module version deprecation X.X.X.
- 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.