diff --git a/content/terraform-docs-common/data/cloud-docs-nav-data.json b/content/terraform-docs-common/data/cloud-docs-nav-data.json index 2251ba1d76..5a8b227486 100644 --- a/content/terraform-docs-common/data/cloud-docs-nav-data.json +++ b/content/terraform-docs-common/data/cloud-docs-nav-data.json @@ -24,7 +24,7 @@ { "title": "Get started", "href": "https://learn.hashicorp.com/collections/terraform/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS" - }, + }, { "title": "Migrate to HCP Terraform", "path": "migrate" @@ -792,6 +792,7 @@ { "title": "Private registry", "routes": [ + { "title": "GPG keys", "path": "api-docs/private-registry/gpg-keys" }, { "title": "Modules", "path": "api-docs/private-registry/modules" }, { "title": "Manage module versions", "path": "api-docs/private-registry/manage-module-versions" }, { @@ -802,7 +803,7 @@ "title": "Private provider versions and platforms", "path": "api-docs/private-registry/provider-versions-platforms" }, - { "title": "GPG keys", "path": "api-docs/private-registry/gpg-keys" }, + { "title": "Stack component configurations", "path": "api-docs/private-registry/stack-component-configurations" }, { "title": "Tests", "path": "api-docs/private-registry/tests" } ] }, diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/changelog.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/changelog.mdx index c57f566950..81d0cca0ed 100644 --- a/content/terraform-docs-common/docs/cloud-docs/api-docs/changelog.mdx +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/changelog.mdx @@ -9,6 +9,13 @@ description: >- Keep track of changes to the API for HCP Terraform and Terraform Enterprise. + + +## 2025-12-18 +* Document the new `/registry-components` endpoints that let you read, publish, update, and delete Stack component configurations in your organization's private registry. For more details, refer to the [Stack component configurations API reference](/terraform/cloud-docs/api-docs/private-registry/stack-component-configurations). + + + ## 2025-10-31 * Document API filtering parameters when [`listing projects`](/terraform/cloud-docs/api-docs/projects) diff --git a/content/terraform-docs-common/docs/cloud-docs/api-docs/private-registry/stack-component-configurations.mdx b/content/terraform-docs-common/docs/cloud-docs/api-docs/private-registry/stack-component-configurations.mdx new file mode 100644 index 0000000000..bfb81cff30 --- /dev/null +++ b/content/terraform-docs-common/docs/cloud-docs/api-docs/private-registry/stack-component-configurations.mdx @@ -0,0 +1,740 @@ +--- +page_title: Stack component configurations API reference for HCP Terraform +description: >- + Use the HCP Terraform API's `/registry-components` endpoint to read, publish, update, and delete Stack component configuration versions in your organization's private registry. +tfc_only: true +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Stack component configurations API reference + +Publish a Stack component configuration to the HCP Terraform private registry to share Stacks across your organization. When you publish a component configuration, other teams can use it to create a Stack by defining a `stack` block in their own `.tfcomponent.hcl` file. + +Refer to [Publish a Stack](/terraform/cloud-docs/registry/publish-stack-configuration) to learn more publishing a Stack component configuration. To learn more about Stacks, refer to the [Stacks overview](/terraform/cloud-docs/stacks). + +## Overview + +The following table lists all the endpoints for managing Stack component configurations in your organization's private registry: + +| Method | Path | Action | +|--------|------|--------| +| GET | `/organizations/:organization_name/registry-components` | [List Stack component configurations](#list-stack-component-configurations-for-an-organization) for an organization. | +| POST | `/organizations/:organization_name/registry-components` | [Create a Stack component configuration](#create-a-stack-component-configuration), with or without VCS. | +| POST | `/api/v2/registry-components/:component_id/versions` | [Create a new version](#create-a-component-configuration-version) of a Stack component configuration. | +| PUT | `https://archivist.terraform.io/v1/object/` | [Add a Stack component configuration version](#add-a-component-configuration-version). | +| GET | `/api/v2/registry-components/:component_id` | [Get details about a Stack component configuration](#get-a-stack-component-configuration). | +| DELETE | `/api/v2/registry-components/:component_id/versions/:version` | [Delete a specific version](#delete-a-component-configuration-version) of a Stack component configuration. | +| DELETE | `/api/v2/registry-components/:component_id` | [Delete an entire Stack component configuration](#delete-a-stack-component-configuration). | + +## List Stack component configurations for an organization + +`GET /organizations/:organization_name/registry-components` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to list available component configurations from. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/cloud-docs/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `q` | **Optional.** A search query string. Component configurations are searchable by name and namespace fields. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 component configurations per page. | + +### Sample request + +The following example request lists Stack component configurations for the `my-organization` organization: + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-components +``` + +### Sample response + +The following response example lists Stack component configurations for the `my-organization` organization: + +```json +{ + "data": [ + { + "id": "comp-wed33EBTz4w8XeSS", + "type": "registry-components", + "attributes": { + "name": "hashibank-app-security", + "namespace": "my-organization", + "description": "Stack component configuration for HashiBank application security", + "status": "completed", + "created-at": "2024-11-11T11:20:21Z", + "updated-at": "2024-11-11T11:20:24Z", + "latest-version": "1.0.0", + "published-at": "2024-11-11T11:20:30.126135Z", + "providers": [ + { + "name": "aws", + "namespace": "hashicorp", + "source": "hashicorp/aws" + } + ] + }, + "relationships": { + "organization": { + "data": { + "id": "org-rT5Smhs7tBfjGnsZ", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/registry-components/comp-wed33EBTz4w8XeSS" + } + }, + { + "id": "comp-hGqAHmU28NE2hnjA", + "type": "registry-components", + "attributes": { + "name": "eks-cluster", + "namespace": "my-organization", + "description": "Stack component configuration for EKS cluster setup", + "status": "completed", + "created-at": "2024-11-26T13:45:28Z", + "updated-at": "2024-11-26T13:45:30Z", + "latest-version": "1.0.5", + "published-at": "2024-11-26T13:45:33.719842Z", + "providers": [ + { + "name": "aws", + "namespace": "hashicorp", + "source": "hashicorp/aws" + }, + { + "name": "random", + "namespace": "hashicorp", + "source": "hashicorp/random" + } + ] + }, + "relationships": { + "organization": { + "data": { + "id": "org-rT5Smhs7tBfjGnsZ", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/registry-components/comp-hGqAHmU28NE2hnjA" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-components?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-components?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-components?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Create a Stack component configuration + +`POST /organizations/:organization_name/registry-components` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create a component configuration in. The organization must already exist, and the token authenticating the API request must belong to a team member with [**Manage Stack component configurations**](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-stack-component-configurations) permissions. | + +You can use this endpoint to publish a component configuration using the [API-only workflow](#api-only-workflow) or [VCS-backed workflow](#vcs-backed-workflow). + + +| Status | Response | Reason | +| ------- | ----------------------------------------------------------- | ------------------------------------------------------------ | +| [201][] | [JSON API document][] (`type: "registry-components"`) | Successfully published component configuration | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### VCS-backed workflow + +VCS-backed publishing sources a component configuration directly from a VCS repository. The publishing process fetches all SemVer version tags with the optional `v` prefix. + +For each version, HCP Terraform clones the tag and parses the configuration to create different versions of the component configuration. Each component configuration version details the required input and output variables, `README` documentation, providers, and other related information. + +#### Request body + +This `POST` endpoint requires a `JSON` object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-components"`. | +| `data.attributes.name` | string | (optional) | The name of this component configuration. If not specified, HCP Terraform uses the repository name. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters. | +| `data.attributes.vcs-repo.identifier` | string | | The repository from which to ingress the configuration. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS connection (OAuth connection + token) to use. Get this ID from the [`oauth-tokens` endpoint](/terraform/cloud-docs/api-docs/oauth-tokens). You can not specify this value if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The GitHub App installation connection to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.display_identifier` | string | | The display identifier for the repository. For most VCS providers outside of Bitbucket Cloud, this identifier matches the `data.attributes.vcs-repo.identifier` string. | +| `data.attributes.vcs-repo.source-directory` | string | (optional) | The directory in the repository where the component configuration is located. Useful for monorepo setups where multiple component configurations exist in different directories. | +| `data.attributes.vcs-repo.tag-prefix` | string | (optional) | A prefix to filter tags for versioning. Only tags matching this prefix will be considered as versions. Useful for monorepo setups where multiple component configurations share the same repository but use different tag prefixes. | + +A VCS repository identifier, `data.attributes.vcs-repo.identifier`, is a reference to your VCS repository. Use the syntax `:org/:repo`, where `:org` and `:repo` refer to the organization and repository in your VCS provider. If you are using Bitbucket Data Center, use the syntax `:project_key/:repo`. If you are using Azure DevOps, use the syntax `:org/:project/_git/:repo`. + +The OAuth token ID identifies the VCS connection, and therefore the organization, that HCP Terraform creates the component configuration in. + +#### Sample payload + +The following example payload sources a VCS-backed component configuration from the `my-org` organization in the `terraform-component-eks-cluster` repository: + +```json +{ + "data": { + "type": "registry-components", + "attributes": { + "vcs-repo": { + "identifier": "my-org/terraform-component-eks-cluster", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "display_identifier": "my-org/terraform-component-eks-cluster", + } + } + } +} +``` + +The following example payload sources a VCS-backed component configuration from the `my-org` organization in the `hashibank-monorepo` repository with a source directory and tag prefix: + +```json +{ + "data": { + "type": "registry-components", + "attributes": { + "name": "hashibank-app-security", + "vcs-repo": { + "identifier": "my-org/hashibank-monorepo", + "github-app-installation-id": "ghain-abc123xyz456", + "source-directory": "components/security", + "tag-prefix": "security/" + } + } + } +} +``` + + +#### Sample response + +The following example response body returns the VCS-backed component configuration's details: + +```json +{ + "data": { + "id": "comp-UnpBkfLQJZUXARc6", + "type": "registry-components", + "attributes": { + "name": "hashibank-app-security", + "namespace": "my-organization", + "status": "completed", + "created-at": "2024-12-03T10:31:53Z", + "updated-at": "2024-12-03T10:31:53Z", + "version-statuses": [ + { + "version": "1.0.0", + "status": "completed" + } + ], + "vcs-repo": { + "identifier": "my-org/hashibank-app-security", + "display-identifier": "my-org/hashibank-app-security", + "source-directory": null, + "tag-prefix": null, + "oauth-token-id": "ot-eNzYfKyB11MMTqEx" + } + }, + "relationships": { + "organization": { + "data": { + "id": "org-rT5Smhs7tBfjGnsZ", + "type": "organizations" + } + }, + "registry-component-versions": { + "links": { + "related": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6/versions" + } + } + }, + "links": { + "self": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6" + } + } +} +``` + +### API-only workflow + +API-only publishing creates a component configuration without a backing VCS repository. After creating the component configuration, you must explicitly create and upload subsequent versions using the [Create a component configuration version endpoint](#create-a-component-configuration-version). + +#### Request body + +This `POST` endpoint requires a `JSON` object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-components"`. | +| `data.attributes.name`| string | | The name of this component configuration. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters. | + +#### Sample payload + +The following example payload creates an API-only component configuration named `eks-cluster`: + +```json +{ + "data": { + "type": "registry-components", + "attributes": { + "name": "eks-cluster" + } + } +} +``` + +#### Sample request + +The following example request creates an API-only component configuration in the `my-organization` organization: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-components +``` + +#### Sample response + +The following example response body returns the API-only component configuration's details: + +```json +{ + "data": { + "id": "comp-fZn7uHu99ZCpAKZJ", + "type": "registry-components", + "attributes": { + "name": "eks-cluster", + "namespace": "my-organization", + "status": "pending", + "created-at": "2024-01-15T19:36:56.288Z", + "updated-at": "2024-01-15T19:36:56.288Z", + "version-statuses": [] + }, + "relationships": { + "organization": { + "data": { + "id": "org-rT5Smhs7tBfjGnsZ", + "type": "organizations" + } + }, + "registry-component-versions": { + "links": { + "related": "/api/v2/registry-components/comp-fZn7uHu99ZCpAKZJ/versions" + } + } + }, + "links": { + "self": "/api/v2/registry-components/comp-fZn7uHu99ZCpAKZJ" + } + } +} +``` + +## Create a component configuration version + +`POST /api/v2/registry-components/:component_id/versions` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:component_id` | The ID of the component configuration to create, such as `comp-UnpBkfLQJZUXARc6`. The token authenticating the API request must belong to a team member with [**Manage Stack component configurations**](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-stack-component-configurations) permissions. | + +Creates a new version for component configurations that do not source from a VCS repository. VCS-backed component configurations automatically create new versions for new tags. After creating a version for an [API-published component configuration](#api-only-workflow), you can upload subsequent configurations to the link that HCP Terraform returns. + +| Status | Response | Reason | +| ------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-component-versions"`) | Successfully published component configuration version | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### Request body + +This `POST` endpoint requires a `JSON` object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------ | ------ | ------- | -------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-component-versions"`. | +| `data.attributes.version` | string | | A valid SemVer version string. | + +### Sample payload + +The following example payload creates a component configuration version for `1.2.3`: + +```json +{ + "data": { + "type": "registry-component-versions", + "attributes": { + "version": "1.2.3" + } + } +} +``` + +### Sample request + +The following example request creates a new version for the `comp-UnpBkfLQJZUXARc6` component configuration: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/registry-components/comp-UnpBkfLQJZUXARc6/versions +``` + +### Sample response + +The following example response body returns the details of the new component configuration version: + +```json +{ + "data": { + "id": "compver-Ecdq2uaNUXNHNHcA", + "type": "registry-component-versions", + "attributes": { + "source": "api", + "status": "pending", + "version": "1.0.0", + "readme": null, + "description": null, + "published-at": null, + "error-message": null, + "source-url": null + }, + "relationships": { + "registry-component": { + "links": { + "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY" + } + }, + "resources": { + "links": { + "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/resources" + } + }, + "variables": { + "links": { + "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/variables" + } + }, + "outputs": { + "links": { + "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/outputs" + } + }, + "providers": { + "links": { + "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/providers" + } + }, + "subcomponents": { + "links": { + "related": "/api/v2/registry-components/comp-FRxdjivJqVVfi2SY/versions/1.0.0/subcomponents" + } + } + }, + "links": { + "self": "/api/v2/registry-components/compver-Ecdq2uaNUXNHNHcA/versions/1.0.0", + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6Q1JjVWM5ZHBFRXZzdWZTKy80NUh3bDRMREd4QkxRaXZ0bXE3QXYzRHFMcFE0NVVhVmRmSE43K0dTUlp1aUsxQ253VmN6SFoyM1pLWU4vbGxsVW8wUkh4UzZ3S1ZmYXljRHhKM1gxR0RIdTJiSlNMbGYzYmo5ejVlUHZPQlArRUJHa1h3WUFLemhuOUhsS3pXZnRvbHppbVJYZEJCUjl6TlZLdEhqT29DdjY4U3RQRW51MkptTCsvUUlWK2xKNDhjK2NaT1JCbjNLYWtGZFh1UGtJL2V4YVFYbjVEVXdScEpJNzdrR2ZKSXgvNjd6UkVEZDBDZElBQnljK0Y2YnhVeUpUV1BvRWdkY0hPajhyWHdKNW1QTS93bnNHK0lSSUVoQ05OTGJaR09MMnRzeHl4ZzBST2VVaG9PQzV6YjR5WXprU0REMldPSUxTV0xRVlBRbldvaGtRVUFtUWU3QitrWERoOUUwaFczOG1rTG4xc21KZ240ZU40PQ" + } + } +} +``` + +## Add a component configuration version + +`PUT https://archivist.terraform.io/v1/object/` + +HCP Terraform provides a URL in the `upload` links attribute in the `registry-component-versions` resource. + +### Expected archive format + +HCP Terraform expects the component configuration version uploaded to be a `gzip tarball` with the component configuration in the root directory. + +Given the following example folder structure: + +```shell-session +terraform-component-eks-cluster +├── README.md +├── examples +│ └── default +│ ├── README.md +│ └── main.tf +└── components.tfcomponent.hcl +``` + +Package the files in an archive format by running `tar zcvf component.tar.gz *` in the component configuration's directory: + +```shell-session +$ cd terraform-component-eks-cluster +terraform-component-eks-cluster +$ tar zcvf component.tar.gz * +a README.md +a examples +a examples/default +a examples/default/main.tf +a examples/default/README.md +a components.tfcomponent.hcl +``` + +### Sample request + +The following example request uploads a component configuration version archive: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @component.tar.gz \ + https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox... +``` + +After the Stack component configuration version is successfully parsed, its status changes to `"completed"`. + +## Get a Stack component configuration + +`GET /api/v2/registry-components/:component_id` + +### Parameters + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------- | +| `:component_id` | The ID of the component configuration to retrieve, such as `comp-7GjfsTX1Yc5E1boD`. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-components"`) | The request was successful | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### Sample request + +The following example request gets details about a Stack component configuration: + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/registry-components/comp-7GjfsTX1Yc5E1boD +``` + +### Sample response for an API-published configuration + +The following example response body returns an API-published component configuration's details: + +```json +{ + "data": { + "id": "comp-7GjfsTX1Yc5E1boD", + "type": "registry-components", + "attributes": { + "name": "test-stacks-1764762762", + "namespace": "hashicorp", + "status": "completed", + "created-at": "2025-12-03T11:52:43Z", + "updated-at": "2025-12-03T11:52:44Z", + "version-statuses": [ + { + "version": "1.0.0", + "status": "completed" + } + ], + "vcs-repo": null + }, + "relationships": { + "organization": { + "data": { + "id": "org-rT5Smhs7tBfjGnsZ", + "type": "organizations" + } + }, + "registry-component-versions": { + "links": { + "related": "/api/v2/registry-components/comp-7GjfsTX1Yc5E1boD/versions" + } + } + }, + "links": { + "self": "/api/v2/registry-components/comp-7GjfsTX1Yc5E1boD" + } + } +} +``` + +### Sample response for a VCS-backed configuration + +The following example response body returns the VCS-backed component configuration's details: + +```json +{ + "data": { + "id": "comp-UnpBkfLQJZUXARc6", + "type": "registry-components", + "attributes": { + "name": "hashibank-app-security", + "namespace": "my-organization", + "status": "completed", + "created-at": "2024-12-03T10:31:53Z", + "updated-at": "2024-12-03T10:31:53Z", + "version-statuses": [ + { + "version": "1.0.0", + "status": "completed" + }, + { + "version": "1.1.0", + "status": "completed" + } + ], + "vcs-repo": { + "identifier": "my-org/hashibank-app-security", + "display-identifier": "my-org/hashibank-app-security", + "source-directory": "components/security", + "tag-prefix": "security/", + "oauth-token-id": "ot-eNzYfKyB11MMTqEx" + } + }, + "relationships": { + "organization": { + "data": { + "id": "org-rT5Smhs7tBfjGnsZ", + "type": "organizations" + } + }, + "registry-component-versions": { + "links": { + "related": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6/versions" + } + } + }, + "links": { + "self": "/api/v2/registry-components/comp-UnpBkfLQJZUXARc6" + } + } +} +``` + +## Delete a component configuration version + +`DELETE /api/v2/registry-components/:component_id/versions/:version` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:component_id` | The ID of the version of the component configuration to delete, such as `comp-jKXTSGwC8uV6vACK`. The token authenticating the API request must belong to a team member with [**Manage Stack component configurations**](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-stack-component-configurations) permissions. | +| `:version` | The version number to delete, such as `2.0.0`. | + +You can delete a specific version of a component configuration, or the entire component configuration. This endpoint deletes a specific version of a component configuration from your private registry. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------ | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### Sample request + +The following example request deletes a specific version of a component configuration: + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/registry-components/comp-jKXTSGwC8uV6vACK/versions/2.0.0 +``` + +## Delete a Stack component configuration + +`DELETE /api/v2/registry-components/:component_id` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:component_id` | The ID of the version of the component configuration to delete, such as `comp-jKXTSGwC8uV6vACK`. The token authenticating the API request must belong to a team member with [**Manage Stack component configurations**](/terraform/cloud-docs/users-teams-organizations/permissions/organization#manage-stack-component-configurations) permissions. | + +You can delete a specific version of a component configuration, or the entire component configuration. This endpoint deletes the entire component configuration from your private registry. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------ | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | + +### Sample request + +The following example deletes an entire component configuration from the private registry: + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/registry-components/comp-YF7Avu8dHpJev9Cc +``` diff --git a/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json b/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json index 5d1ba42f94..f3ce375df6 100644 --- a/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json +++ b/content/terraform-enterprise/1.1.x/data/enterprise-nav-data.json @@ -675,17 +675,17 @@ "title": "Overview", "path": "deploy/manage/product-report" }, - { + { "title": "Automated product usage reports", "path": "deploy/manage/product-report/automated" }, - { + { "title": "Manual product usage reports", "path": "deploy/manage/product-report/manual" } ] }, - { + { "title": "Enable automated license utilization reports", "path": "deploy/manage/license-report" } @@ -846,7 +846,7 @@ { "title": "Organization permissions", "path": "users-teams-organizations/permissions/organization" }, { "title": "Project permissions", "path": "users-teams-organizations/permissions/project" }, { "title": "Workspace permissions", "path": "users-teams-organizations/permissions/workspace" } - ] + ] }, { "title": "Two-factor Authentication",