Skip to content

Commit 4232c66

Browse files
rkoron007rkoron007
authored
Merge pull request #369 from hashicorp/RK/module-EOL
Module EOL docs
2 parents 3bdf0de + fc80ded commit 4232c66

File tree

6 files changed

+274
-0
lines changed

6 files changed

+274
-0
lines changed

‎website/data/cloud-docs-nav-data.json

+2
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@
102102
"title": "Private Registry",
103103
"routes": [
104104
{ "title": "Modules", "path": "api-docs/private-registry/modules" },
105+
{ "title": "Manage Module Versions", "path": "api-docs/private-registry/manage-module-versions" },
105106
{
106107
"title": "Providers",
107108
"path": "api-docs/private-registry/providers"
@@ -408,6 +409,7 @@
408409
"title": "Publishing Private Modules",
409410
"path": "registry/publish-modules"
410411
},
412+
{ "title": "Deprecate Module Versions", "path": "registry/manage-module-versions" },
411413
{
412414
"title": "Test-Integrated Modules",
413415
"path": "registry/test"

‎website/docs/cloud-docs/api-docs/changelog.mdx

+3
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ description: >-
99

1010
Keep track of changes to the API for HCP Terraform and Terraform Enterprise.
1111

12+
## 2024-10-15
13+
* Add new documentation for the ability to deprecate, and revert the deprecation of, module versions. Learn more about [Managing module versions](/terraform/cloud-docs/api-docs/private-registry/manage-module-versions).
14+
1215
## 2024-09-02
1316
* Add warning about the deprecation and future removal of the [Policy Checks](/terraform/cloud-docs/api-docs/policy-checks) API.
1417

‎website/docs/cloud-docs/api-docs/private-registry/manage-module-versions.mdx

+195
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
---
2+
page_title: Manage module versions - API Docs - HCP Terraform
3+
description: |-
4+
Use these module management endpoints to deprecate and revert the deprecation of module versions you published to an organization's private registry.
5+
tfc_only: true
6+
---
7+
8+
[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200
9+
10+
[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201
11+
12+
[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202
13+
14+
[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204
15+
16+
[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
17+
18+
[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
19+
20+
[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
21+
22+
[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
23+
24+
[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409
25+
26+
[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412
27+
28+
[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
29+
30+
[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429
31+
32+
[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
33+
34+
[503]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503
35+
36+
[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents
37+
38+
[JSON API error object]: https://jsonapi.org/format/#error-objects
39+
40+
# Manage module versions API
41+
42+
This topic provides reference information about API endpoints that let your deprecate module versions in your organization’s private registry.
43+
44+
## Introduction
45+
46+
When you deprecate a module version, HCP Terraform adds warnings to the module's registry page and to run outputs when anyone uses the deprecated version.
47+
48+
<!-- BEGIN: TFC:only name:pnp-callout -->
49+
@include "tfc-package-callouts/manage-module-versions.mdx"
50+
<!-- END: TFC:only name:pnp-callout -->
51+
52+
After deprecating a module version, you can revert that deprecated status to remove the warnings from that version in the registry and outputs. For more details on module deprecation, refer to [Deprecate module versions](/terraform/cloud-docs/registry/manage-module-versions).
53+
54+
@include "public-beta/manage-module-versions.mdx"
55+
56+
## Deprecate a module version
57+
58+
Use this endpoint to deprecate a module version.
59+
60+
`PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version`
61+
62+
63+
| Parameter | Description |
64+
| :---- | :---- |
65+
| `:organization_name` | The name of the organization the module belongs to. |
66+
| `:module_name` | The name of the module whose version you want to deprecate. |
67+
| `:module_provider` | Specifies the Terraform provider that this module is used for. |
68+
| `:module_version` | The module version you want to deprecate. |
69+
70+
This endpoint allows you to deprecate a specific module version. Deprecating a module version adds warnings to the run output of any consumers using this module.
71+
72+
73+
| Status | Response | Reason |
74+
| :---- | :---- | :---- |
75+
| [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | [JSON API document](http://terraform/cloud-docs/api-docs#json-api-documents) | Successfully deprecated a module version. |
76+
| [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | [JSON API error object](http://jsonapi.org/format/#error-objects) | This organization is not authorized to deprecate this module version, or the module version does not exist. |
77+
| [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Malformed request body, for example the request is missing attributes or uses the wrong types. |
78+
| [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) or [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Failure occurred while deprecating a module version. |
79+
80+
### **Sample Payload**
81+
82+
```json
83+
{
84+
"data": {
85+
"type": "module-versions",
86+
"attributes": {
87+
"deprecation": {
88+
"deprecated-status": "Deprecated",
89+
"reason": "Deprecated due to a security vulnerability issue.",
90+
"link": "https://www.hashicorp.com/"
91+
}
92+
}
93+
}
94+
}
95+
```
96+
97+
### **Sample Request**
98+
99+
```shell
100+
curl \
101+
--header "Authorization: Bearer $TOKEN" \
102+
--header "Content-Type: application/vnd.api+json" \
103+
--request PATCH \
104+
--data @payload.json \
105+
https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0
106+
```
107+
108+
### Sample Response
109+
110+
```json
111+
{
112+
"data": {
113+
"type": "module-versions",
114+
"id": "1",
115+
"relationships": {
116+
"deprecation": {
117+
"data": {
118+
"id": "2",
119+
"type": "deprecations"
120+
}
121+
}
122+
}
123+
},
124+
"included": [
125+
{
126+
"type": "deprecations",
127+
"id": "2",
128+
"attributes": {
129+
"link": "https://www.hashicorp.com/",
130+
"reason": "Deprecated due to a security vulnerability issue. Applies will be blocked in 15 days."
131+
}
132+
}
133+
]
134+
}
135+
```
136+
137+
138+
## Revert the deprecation status for a module version
139+
140+
Use this endpoint to revert the deprecation of a module version.
141+
142+
`PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version`
143+
144+
| Parameter | Description |
145+
| :---- | :---- |
146+
| `:organization_name` | The name of the organization the module belongs to. |
147+
| `:module_name` | The name of the module you want to revert the deprecation of. |
148+
| `:module_provider` | Specifies the Terraform provider that this module is used for. |
149+
| `:module_version` | The module version you want to revert the deprecation of. |
150+
151+
Deprecating a module version adds warnings to the run output of any consumers using this module. Reverting the deprecation status removes warnings from the output of consumers and fully reinstates the module version.
152+
153+
| Status | Response | Reason |
154+
| :---- | :---- | :---- |
155+
| [200](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) | [JSON API document](http:///terraform/cloud-docs/api-docs#json-api-documents) | Successfully reverted a module version’s deprecation status and reinstated that version. |
156+
| [404](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404) | [JSON API error object](http://jsonapi.org/format/#error-objects) | This organization is not authorized to revert the depreciation of this module version, or the module version does not exist. |
157+
| [422](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422) | [JSON API error object](http://jsonapi.org/format/#error-objects) | Malformed request body, for example the request is missing attributes or uses the wrong types. |
158+
| [500](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) or [503] | [JSON API error object](http://jsonapi.org/format/#error-objects) | Failure occurred while reverting the deprecation of a module version. |
159+
160+
### **Sample Request**
161+
162+
```shell
163+
curl \
164+
--header "Authorization: Bearer $TOKEN" \
165+
--header "Content-Type: application/vnd.api+json" \
166+
--request PATCH \
167+
--data @payload.json \
168+
https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0
169+
```
170+
171+
**Sample payload**
172+
173+
```json
174+
{
175+
"data": {
176+
"type": "module-versions",
177+
"attributes": {
178+
"deprecation": {
179+
"deprecated-status": "Undeprecated"
180+
}
181+
}
182+
}
183+
}
184+
```
185+
186+
### Sample Response
187+
188+
```json
189+
{
190+
"data": {
191+
"type": "module-versions",
192+
"id": "1"
193+
}
194+
}
195+
```

‎website/docs/cloud-docs/registry/manage-module-versions.mdx

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
page_title: Deprecate module versions - Private Registry - HCP Terraform
3+
description: >-
4+
Learn how to deprecate a module version and revert a module version’s deprecation. Deprecating a module version allows you to warn users of that version’s end of life, enabling consumers to upgrade their modules when it’s convenient and without disrupting their workflows.
5+
tfc_only: true
6+
---
7+
8+
# Deprecate module versions
9+
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.
10+
11+
<!-- BEGIN: TFC:only name:pnp-callout -->
12+
@include "tfc-package-callouts/manage-module-versions.mdx"
13+
<!-- END: TFC:only name:pnp-callout -->
14+
15+
You can also [deprecate module versions using the HCP Terraform API](/terraform/cloud-docs/api-docs/private-registry/manage-module-versions).
16+
17+
## Background
18+
19+
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.
20+
21+
@include "public-beta/manage-module-versions.mdx"
22+
23+
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.
24+
25+
## Requirements
26+
27+
To deprecate a module version or to revert a version’s deprecation:
28+
* you must have permission to manage [private registry modules](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#manage-private-registry)
29+
* the module must be in the [private](https://developer.hashicorp.com/terraform/cloud-docs/registry/publish-modules) registry
30+
31+
## Deprecate a module version
32+
To deprecate a module version, perform the following steps:
33+
34+
1. Navigate to your organization’s private registry and find the module you want to deprecate a version of.
35+
1. Open the **Manage module for organization** dropdown.
36+
1. Select a module version for deprecation.
37+
1. 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.
38+
1. 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.
39+
1. Click **Deprecate**.
40+
41+
If the module version you are deprecating has the [**No-code ready**](/terraform/cloud-docs/no-code-provisioning/module-design#updating-a-module-s-version) 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.
42+
43+
### Deprecation warnings
44+
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.
45+
46+
~> **Note**: Only workspaces in the [remote or agent execution modes](terraform/cloud-docs/workspaces/settings#execution-mode) can receive warnings for a module version’s deprecation.
47+
48+
If you provided a reason for a module version’s deprecation, then the warning users receive contains that reason and the following message:
49+
50+
```shell
51+
Found the following deprecated module versions, consider using an updated version.
52+
<module-name-version><optional-reason-for-module-deprecation>
53+
```
54+
55+
A run’s output mode affects where a module deprecation’s warning appears. If a run set to the default [**Structured Run Output**](/terraform/cloud-docs/workspaces/settings#user-interface) mode, then module deprecation warnings show up under a run’s Diagnostics dropdown.
56+
57+
If a run is in the **Console UI** mode, module deprecation warnings appear in the run’s logs:
58+
59+
```shell
60+
Warning: Deprecated modules found, consider installing an updating version. The following are affected:
61+
Version X.X.X of <module-name>
62+
```
63+
## Revert the deprecation of a module version
64+
65+
To revert a module version’s deprecation, perform the following steps:
66+
67+
1. Navigate to your organization’s private registry and find the deprecated module version you want to revert the deprecation of.
68+
1. Open the **Manage module for organization** dropdown.
69+
1. Select **Revert module version deprecation X.X.X**.
70+
1. Click **Revert Deprecation**.
71+
72+
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.

‎website/docs/partials/public-beta/manage-module-versions.mdx

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
~> **Note**: The ability to deprecate module versions is in public beta. All APIs and workflows are subject to change.

‎website/docs/partials/tfc-package-callouts/manage-module-versions.mdx

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
-> **Note:** Module deprecation is available in the HCP Terraform **Plus** Edition. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details.

0 commit comments

Comments
 (0)