From 82f973929efdc5c69fd77b96630eae9a9ddf78f0 Mon Sep 17 00:00:00 2001 From: tfe-release-bot Date: Tue, 27 May 2025 20:10:56 +0000 Subject: [PATCH] Automated Docs DIFF PR --- .../docs/enterprise/api-docs/changelog.mdx | 15 +- .../docs/enterprise/api-docs/index.mdx | 28 +- .../enterprise/api-docs/organizations.mdx | 1 + .../manage-module-versions.mdx | 303 ++++++++++++++++-- .../api-docs/project-team-access.mdx | 6 +- .../docs/enterprise/api-docs/projects.mdx | 21 +- .../run-tasks/run-tasks-integration.mdx | 26 +- .../api-docs/run-tasks/run-tasks.mdx | 183 ++++++----- .../docs/enterprise/api-docs/team-access.mdx | 2 +- .../docs/enterprise/api-docs/team-members.mdx | 2 +- .../docs/enterprise/api-docs/team-tokens.mdx | 279 +++++++++++++++- .../docs/enterprise/api-docs/workspaces.mdx | 15 +- .../integrations/kubernetes/setup.mdx | 38 +-- .../service-now/service-graph/index.mdx | 2 +- .../docs/enterprise/migrate/index.mdx | 6 +- .../manage-policy-sets/index.mdx | 10 +- .../docs/enterprise/projects/manage.mdx | 6 +- .../docs/enterprise/registry/add.mdx | 2 +- .../registry/manage-module-versions.mdx | 190 +++++++++-- .../docs/enterprise/registry/test.mdx | 12 +- .../docs/enterprise/run/modes-and-options.mdx | 2 +- .../docs/enterprise/run/run-environment.mdx | 12 +- .../v202504-1/docs/enterprise/run/ui.mdx | 2 + .../users-teams-organizations/2fa.mdx | 2 +- .../users-teams-organizations/api-tokens.mdx | 10 +- .../organizations/index.mdx | 1 + .../users-teams-organizations/permissions.mdx | 14 +- .../enterprise/vcs/azure-devops-server.mdx | 10 +- .../vcs/azure-devops-services-pat.mdx | 116 +++++++ .../enterprise/vcs/azure-devops-services.mdx | 10 +- .../enterprise/vcs/bitbucket-data-center.mdx | 2 +- .../v202504-1/docs/enterprise/vcs/index.mdx | 11 +- .../enterprise/workspaces/best-practices.mdx | 6 +- .../docs/enterprise/workspaces/index.mdx | 4 +- .../enterprise/workspaces/settings/access.mdx | 4 +- .../enterprise/workspaces/settings/index.mdx | 5 +- .../workspaces/settings/run-tasks.mdx | 11 +- 37 files changed, 1117 insertions(+), 252 deletions(-) create mode 100644 content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services-pat.mdx diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/changelog.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/changelog.mdx index 3fec8bba90..7cda177f5a 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/changelog.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/changelog.mdx @@ -11,13 +11,26 @@ source: terraform-docs-common Keep track of changes to the API for HCP Terraform and Terraform Enterprise. +## 2025-05-1 + +- Add `agent-pool` relationship to the [run task API](/terraform/enterprise/api-docs/run-tasks/run-tasks), which you can use to assign a run task to an agent pool. +- Add `private-run-tasks` to [feature entitlements](/terraform/enterprise/api-docs#feature-entitlements). + +- You can now revoke, and revert the revocation of, module versions. Learn more about [Managing module versions](/terraform/enterprise/api-docs/private-registry/manage-module-versions). + + +## 2025-03-20 + +- Add API documentation for multiple [team tokens](/terraform/enterprise/api-docs/api-tokens), and update documentation around [legacy team tokens](/terraform/enterprise/api-docs/team-tokens##legacy-team-tokens-api-reference). +- Update existing API documentation for [team tokens](/terraform/enterprise/api-docs/team-tokens) to distinguish multiple team tokens from [legacy team tokens](/terraform/enterprise/api-docs/team-tokens##legacy-team-tokens-api-reference). + ## 2025-3-10 - Document unique pagination metadata given in the response of [Organization Runs Index API](/terraform/enterprise/api-docs/run##list-runs-in-an-organization). ## 2025-03-10 -- Add new field `current_rum_count` to the [explorer API](/terraform/enterprise/api-docs/explorer) in the `workspaces` view type that lists a workspace's current resources under management. +- Add new field `current_rum_count` to the [explorer API](/terraform/enterprise/api-docs/explorer) in the `workspaces` view type that lists a workspace's current resources under management. ## 2024-11-19 diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/index.mdx index 9615d628e4..10cd7559c3 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/index.mdx @@ -61,7 +61,7 @@ You can use the following types of tokens to authenticate: ### Blob Storage Authentication -HCP Terraform relies on a HashiCorp-developed blob storage service for storing statefiles and multiple other pieces of customer data, all of which are documented on our [data security page](/terraform/enterprise/architectural-details/data-security). +HCP Terraform relies on a HashiCorp-developed blob storage service for storing statefiles and multiple other pieces of customer data, all of which are documented on our [data security page](/terraform/cloud-docs/architectural-details/data-security). Unlike the HCP Terraform API, this service does not require that a bearer token be submitted with each request. Instead, each URL includes a securely generated secret and is only valid for 25 hours. @@ -90,10 +90,14 @@ The following entitlements are available: - `cost-estimation` — Allows an organization to access [cost estimation][]. - `global-run-tasks` — Allows an organization to apply [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) to every workspace. Affects the [run tasks][] endpoints. This feature is currently in beta. - `module-tests-generation` - Allows an organization to generate tests for private registry modules. This feature is currently in beta. +- `module-deprecations` - Allows an organization to mark a module version from the Private Registry as deprecated. +- `module-revocations` - Allows an organization to mark a deprecated module version from the Private Registry as revoked. - `operations` — Allows an organization to perform runs within HCP Terraform. Affects the [runs][], [plans][], and [applies][] endpoints. - `policy-enforcement` — Allows an organization to use [Sentinel][]. Affects the [policies][], [policy sets][], and [policy checks][] endpoints. - `private-module-registry` — Allows an organization to publish and use modules with the [private module registry][]. Affects the [registry modules][] endpoints. - `private-policy-agents` - Allows an organization to ensure that HTTP enabled [Sentinel][] and OPA [policies][] can communicate with isolated, private, or on-premises infrastructure. +- `private-run-tasks` - Allows an organization to ensure that [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) can communicate with isolated, private, or on-premises infrastructure. +- `private-vcs` - Allows a self-hosted HCP Terraform agent to [connect to a private VCS provider](/terraform/enterprise/vcs/private) without having to expose that provider to the public internet. - `run-tasks` — Allows an organization to use [run tasks](/terraform/enterprise/workspaces/settings/run-tasks). Affects the [run tasks][] endpoints. - `self-serve-billing` — Allows an organization to pay via credit card using the in-app billing UI. - `sentinel` - **DEPRECATED** Use `policy-enforcement` instead. @@ -336,9 +340,9 @@ $ curl \ ## Rate Limiting -You can make up to 30 requests per second to the API as an authenticated or unauthenticated request. If you reach the rate limit then your access will be throttled and an error response will be returned. Some endpoints have lower rate limits to prevent abuse, including endpoints that poll Terraform for a list of runs and endpoints related to user authentication. The adjusted limits are unnoticeable under normal use. If you receive a rate-limited response, the limit is reflected in the `x-ratelimit-limit` header once triggered. +You can make up to 30 requests per second to most API endpoints as an authenticated or unauthenticated request. If you reach the rate limit then your access will be throttled and an error response will be returned. -Authenticated requests are allocated to the user associated with the authentication token. This means that a user with multiple tokens will still be limited to 30 requests per second, additional tokens will not allow you to increase the requests per second permitted. +Requests are per user, not per token. As a result, you cannot use multiple tokens to make more than 30 requests per second. Unauthenticated requests are associated with the requesting IP address. @@ -358,6 +362,24 @@ Unauthenticated requests are associated with the requesting IP address. } ``` +### Lower rate limits for some endoints + +To prevent abuse, some endpoints have lower rate limits. The lower limits are unnoticeable under normal use. If you trigger a rate-limited response, you can see that limit in the `x-ratelimit-limit` header. + +The following endpoints have lower rate limits: + +| Method and endpoint | Purpose | Limit | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------- | +|

`POST /session/two-factor-send-sms`

`POST /api/v2/account/actions/two-factor-enable`

`POST /api/v2/account/actions/two-factor-resend-verification-code`

| Send SMS message | 5 requests per minute per user | +|

`POST /api/v2/account/actions/two-factor-enable`

`POST /api/v2/account/actions/two-factor-resend-verification-code`

| Send SMS message | 10 requests per hour per user | +|

`POST /api/v2/account/actions/two-factor-enable`

`POST /api/v2/account/actions/two-factor-resend-verification-code`

| Send SMS message | 100 requests per day per IP address | +|

`POST /session/two-factor`

`POST /session/two-factor-recovery`

| Submit 2FA code | 5 requests per minute per user | +|

`POST` and `PATCH /api/v2/account/create`

`POST` and `PATCH /api/v2/account/update`

`POST` and `PATCH /api/v2/account/password`

`POST` and `PATCH /api/v2/account/reconfirm`

`POST /session`

| Send emails | 100 per minute | +|

`POST` and `GET /sso/link-new-account`

`POST` and `GET /sso/link-account`

`POST` and `GET /sso/link-existing-account`

`POST /sso/saml/{SAML_CONFIGURATION_EXTERNAL_ID}/acs`

| Send emails | 20 per minute | +|

`POST /api/v2/notification-configurations/{EXTERNAL_ID}/actions/verify`

`DELETE /api/v2/oauth-tokens`

| Send emails | 10 per minute | +|

`POST /account/reconfirm`

| Send emails | 40 per hour | +|

`POST /auth`

| Send emails | 40 per hour per email address | + ## Client libraries and tools HashiCorp maintains [go-tfe](https://github.com/hashicorp/go-tfe), a Go client for HCP Terraform's API. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/organizations.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/organizations.mdx index 186f708b53..dc7e999e44 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/organizations.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/organizations.mdx @@ -813,6 +813,7 @@ curl \ "policy-set-limit": 1, "private-module-registry": true, "private-policy-agents": false, + "private-run-tasks": true, "private-vcs": false, "run-task-limit": 1, "run-task-mandatory-enforcement-limit": 1, diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx index 0b7f06da40..7fe7e2a61b 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx @@ -1,8 +1,8 @@ --- page_title: Manage module versions API reference for Terraform Enterprise description: >- - Use the module management endpoints to deprecate and revert the deprecation of - module versions you published to an organization's private registry. + Use these module management endpoints to deprecate, revoke, and revert the + status of module versions you published to an organization's private registry. source: terraform-docs-common --- @@ -40,11 +40,9 @@ source: terraform-docs-common # Manage module versions API reference -This topic provides reference information about API endpoints that let your deprecate module versions in your organization’s private registry. +Use the module version management API endpoints to deprecate, revoke, and revert of status of module versions in your organization’s private registry. -## Introduction - -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. +<>{/* TODO: remove revoke references here */} @@ -52,7 +50,21 @@ When you deprecate a module version, HCP Terraform adds warnings to the module's -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/enterprise/registry/manage-module-versions). +## Overview + +<>{/* TODO: remove revoke references here */} + +As part of the module lifecycle, you can deprecate or revoke older module versions as you stop supporting them, signaling to module consumers that they need to upgrade to newer versions. + +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. After deprecating a module version, you can revert that deprecated status to remove the warnings from that version in the registry and outputs. + + + +Revoking a module version adds warnings to the module's registry page, warnings in the run outputs of existing users, and blocks new users from using that version. Reverting a module version’s revocation sets the module version back to a deprecated state. + + + +For more details on deprecating or revoking module versions, refer to [Manage module versions](/terraform/enterprise/registry/manage-module-versions). ## Deprecate a module version @@ -60,14 +72,14 @@ Use this endpoint to deprecate a module version. `PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version` -| Parameter | Description | -| :------------------- | :------------------------------------------------------------- | -| `:organization_name` | The name of the organization the module belongs to. | -| `:module_name` | The name of the module whose version you want to deprecate. | -| `:module_provider` | Specifies the Terraform provider that this module is used for. | -| `:module_version` | The module version you want to deprecate. | +| Parameter | Description | +| :------------------- | :---------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:module_name` | The name of the module whose version you want to deprecate. | +| `:module_provider` | Specifies the Terraform provider that this module uses. | +| `:module_version` | The module version you want to deprecate. | -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. +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. | Status | Response | Reason | | :----------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- | @@ -139,14 +151,14 @@ Use this endpoint to revert the deprecation of a module version. `PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version` -| Parameter | Description | -| :------------------- | :------------------------------------------------------------- | -| `:organization_name` | The name of the organization the module belongs to. | -| `:module_name` | The name of the module you want to revert the deprecation of. | -| `:module_provider` | Specifies the Terraform provider that this module is used for. | -| `:module_version` | The module version you want to revert the deprecation of. | +| Parameter | Description | +| :------------------- | :------------------------------------------------------------ | +| `:organization_name` | The name of the organization the module belongs to. | +| `:module_name` | The name of the module you want to revert the deprecation of. | +| `:module_provider` | Specifies the Terraform provider that this module uses. | +| `:module_version` | The module version you want to revert the deprecation of. | -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. +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. | Status | Response | Reason | | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | @@ -194,7 +206,7 @@ https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private ## Fetch a module version’s deprecation data -Send a `GET` request to the `/modules/:GitHub-organization/:module/:provider/versions` endpoint to retrieve data about private registry modules, including the module's deprecation status. Refer to the [private registry module API example](/terraform/enterprise/api-docs/private-registry/modules#sample-registry-request-private-module) for additional information. +Send a `GET` request to the `/modules/:github-organization/:module/:provider/versions` endpoint to retrieve data about private registry modules, including the module's deprecation status. Refer to the [private registry module API example](/terraform/enterprise/api-docs/private-registry/modules#sample-registry-request-private-module) for additional information. For example, if you want to know the deprecation status of v0.0.1 of the `aws` provider’s `consul` module in your `my-cloud-org` organization, you could perform the following API call: @@ -270,3 +282,250 @@ The response includes multiple versions, and each version has a `deprecation` ke ] } ``` + + + +## Revoke a module version + +Use this endpoint to revoke a module version. You must [deprecate a module version](#deprecate-a-module-version) before you can revoke it. + +`PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version` + +| Parameter | Description | +| :------------------- | :------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:module_name` | The name of the module whose version you want to revoke. | +| `:module_provider` | Specifies the Terraform provider that this module uses. | +| `:module_version` | The module version you want to revoke. | + +This endpoint allows you to revoke a specific module version. Revoking a module version adds warnings to the run output of current consumers of this version and blocks new users from trying to use that version. + +| Status | Response | Reason | +| :----------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | +| [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 revoked a module version. | +| [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 revoke this module version, or the module version does not exist. | +| [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. | +| [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 revoking a module version. | + +### Sample Payload + +```json +{ + "data": { + "type": "module-versions", + "attributes": { + "revocation": { + "status": "Revoked", + "message": "Revoked due to a security vulnerability issue.", + "link": "https://www.hashicorp.com/" + } + } + } +} +``` + +### Sample Request + +```shell-session +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ +https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0 +``` + +### Sample Response + +```json +{ + "data": { + "id": "modver-uKQCVs5vAKDmUMyw", + "type": "registry-module-versions", + "attributes": { + "source": "tfe-api", + "status": "ok", + "version": "11.0.0", + "commit-sha": null, + "branch": null, + "created-at": "2024-08-28T20:48:05.206Z", + "updated-at": "2024-08-28T20:48:09.175Z", + "revocation": { + "status": "Revoked", + "message": "Revoked due to a security vulnerability issue.", + "link": "https://www.hashicorp.com/" + } + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-yDKMcmJYx9oFrGao", + "type": "registry-modules" + } + } + }, + "links": { + "upload": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6eElWekF3RH" + } + } +} +``` + +## Revert the revocation status for a module version + +Use this endpoint to revert the revocation of a module version. + +`PATCH /api/v2/organizations/:organization_name/registry-modules/private/:organization_name/:module_name/:module_provider/:module_version` + +| Parameter | Description | +| :------------------- | :----------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:module_name` | The name of the module you want to revert the revocation of. | +| `:module_provider` | Specifies the Terraform provider that this module uses. | +| `:module_version` | The module version you want to revert the revocation of. | + +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 produce warnings in the registry and run outputs, but new users can still use them. + +| Status | Response | Reason | +| :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | +| [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 revocation status and deprecated that version. | +| [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 revocation of this module version, or the module version does not exist. | +| [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. | +| [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 revocation of a module version. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ +https://app.terraform.io/api/v2/organizations/hashicorp/registry-modules/private/hashicorp/lb-http/google/11.0.0 +``` + +### Sample payload + +```json +{ + "data": { + "type": "module-versions", + "attributes": { + "revocation": { + "status": "Unrevoked" + } + } + } +} +``` + +### Sample Response + +```json +{ + "data": { + "id": "modver-uKQCVs5vAKDmUMyw", + "type": "registry-module-versions", + "attributes": { + "source": "tfe-api", + "status": "ok", + "version": "11.0.0", + "commit-sha": null, + "branch": null, + "created-at": "2024-08-28T20:48:05.206Z", + "updated-at": "2024-08-28T20:48:09.175Z", + "revocation": { + "status": "Unrevoked", + } + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-yDKMcmJYx9oFrGao", + "type": "registry-modules" + } + } + }, + "links": { + "upload": "https://app.terraform.io/_archivist/v1/object/dmF1bHQ6djE6eElWekF3RH" + } + } +} +``` + +## Fetch data about a module version’s revocation + +Send a `GET` request to the `/organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` endpoint to retrieve data about private registry modules, including the module's revocation status. Refer to the [private registry module API example](/terraform/enterprise/api-docs/private-registry/modules#get-a-module) for additional information. + +For example, if you want to know the revocation status of v0.0.1 of the `aws` provider’s `consul` module in your `my-cloud-org` organization, you could perform the following API call: + +```shell-session +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-cloud-org/registry-modules/private/my-cloud-org/consul/aws/version?module_version=1.0.0 +``` + +If the module is revoked, your response includes a `revocation` key with the details of that module version’s revocation. + +```json +{ + "data": { + "id": "modver-3tKAXyRnpGYCxW7d", + "type": "registry-module-versions", + "attributes": { + "source": "github", + "status": "ok", + "version": "1.0.0", + "commit-sha": "ea18e73d8da502870fdcbfc54155046bc0cf2679", + "branch": null, + "created-at": "2024-10-11T19:53:35.082Z", + "updated-at": "2024-10-11T19:53:38.782Z", + "revocation": { + "status": "revoked", + "message": "please upgrade to version 1.0.1", + "link": "https://github.com" + } + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-u8BFFruSTSz8dN4C", + "type": "registry-modules" + } + } + }, + "links": { + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djQ6V1pZWWwra1" + } + } +} +``` + +To check the revocation status of all of the `consul` module’s versions, you could perform the following API call: + +```shell-session +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-cloud-org/registry-modules/private/my-cloud-org/consul/aws +``` + +The response includes the revoked versions of this module in the `revoked-versions` key. + +```json +{ + "data": { + "id": "mod-u8BFFruSTSz8dN4C", + "type": "registry-modules", + "attributes": { + "name": "module", + "namespace": "my-cloud-org", + // ... // + "revoked-versions": [ + "1.0.0" + ], + // ... // + }, +} +``` + + diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/project-team-access.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/project-team-access.mdx index e77d497747..84b479ca00 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/project-team-access.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/project-team-access.mdx @@ -42,7 +42,7 @@ source: terraform-docs-common --> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing). +@include 'tfc-package-callouts/project-permissions.mdx' @@ -181,9 +181,9 @@ $ curl \ As mentioned in [Add Team Access to a Project](#add-team-access-to-a-project) and [Update to a Project](#update-team-access-to-a-project), several permission attributes are not editable unless you set `access` to `custom`. If you set `access` to `read`, `plan`, `write`, or `admin`, certain attributes are read-only and reflect the _implicit permissions_ granted to the current access level. -For example, if you set `access` to `read`, the implicit permission level for project settings and workspace run is "read". Conversely, if you set the access level to `admin`, the implicit permission level for the project settings is "delete", while the workspace runs permission is "apply". +For example, if you set `access` to `read`, the implicit permission level for project settings and workspace run is "read". Conversely, if you set the access level to `admin`, the implicit permission level for the project settings is "delete", while the workspace runs permission is "apply". -Several permission attributes are not editable unless `access` is set to `custom`. When access is `read`, `plan`, `write`, or `admin`, these attributes are read-only and reflect the implicit permissions granted to the current access level. +Several permission attributes are not editable unless `access` is set to `custom`. When access is `read`, `plan`, `write`, or `admin`, these attributes are read-only and reflect the implicit permissions granted to the current access level. For example, when access is `read`, the implicit level for the project settings and workspace runs permissions are "read". Conversely, when the access level is `admin`, the implicit level for the project settings is "delete" and the workspace runs permission is "apply". To see all of the implied permissions at different access levels, see [Implied Custom Permission Levels](#implied-custom-permission-levels). diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/projects.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/projects.mdx index 211c0b3ee0..ef2f797665 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/projects.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/projects.mdx @@ -70,8 +70,6 @@ You can also provide an organization API token to call project API endpoints. Re | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `:organization_name` | The name of the organization to create the project in. The organization must already exist in the system, and the user must have permissions to create new projects. | --> **Note:** Project creation is restricted to the owners team, teams with the "Manage Projects" permission, and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). - ### Request Body This POST endpoint requires a JSON object with the following properties as a request payload. @@ -559,17 +557,18 @@ $ curl \ ## Add or update tag bindings on a project -This endpoint can be used to add key-value Tag Bindings to an existing resource, or to update -existing Tag Binding values on the resource. It cannot be used to remove any tag bindings from the resource. -This endpoint is useful when you want to ensure a modification is additive. +Use this endpoint to add key-value tag bindings to an existing resource or to update +existing tag binding values on the resource. You cannot use this endpoint to remove tag bindings from the resource. This endpoint is useful for ensuring that a modification is additive. -Tag Bindings have special constraints: +Tag bindings have the following constraints and behaviors: -- Up to 10 tags can be applied to a project -- All workspaces belonging to the project will inherit the Tag Bindings applied to this project. -- Keys must be no more than 128 characters, allowing all alphanumeric characters plus the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. -- Values allow the same characters, but can be up to 256 characters. -- Certain key prefixes, including `hc:` and `hcp:` are not allowed. +- A project can have up to 10 tags. +- All workspaces within the project inherit its tag bindings. +- Keys can have up to 128 characters. +- Keys support all alphanumeric characters and the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. +- Values can have up to 256 characters. +- Values support all alphanumeric characters and the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. +- You cannot use `hc:` and `hcp:` as key prefixes. `PATCH /projects/:project_id/tag-bindings` diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx index 4a285f56e3..eaa3fe1fca 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx @@ -30,6 +30,8 @@ Refer to [run tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) for the ## Run Task Request When a run reaches the appropriate phase and a run task is triggered, HCP Terraform will send a request to the run task's URL. + +Either HCP Terraform itself, or a self-hosted HCP Terraform agent using [request forwarding](/terraform/cloud-docs/agents/request-forwarding) can make the request to a run task's URL. Your organization [must be entitled to `private-run-tasks`](/terraform/enterprise/api-docs#feature-entitlements) to use request forwarding. The service receiving the run task request should respond with `200 OK`, or HCP Terraform will retry to trigger the run task. `POST :url` @@ -190,7 +192,7 @@ A run task result may optionally contain one or more detailed outcomes, which im | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `outcome-id` | string | A partner supplied identifier for this outcome. | | `description` | string | A one-line description of the result. | -| `body` | string | (Optional) A detailed message for the result in Markdown format. It is recommended to keep it under 1MB, with a maximum allowable limit of 5MB. | +| `body` | string | (Optional) A detailed message for the result in markdown format. We recommend limiting messages to under 1MB with a maximum allowable limit of 5MB. | | `url` | string | (Optional) A URL that a user can navigate to for more information about this result. | | `tags` | object | (Optional) An object containing tag arrays, named by the property key. | | `tags.key` | string | The two or three word name of the header tag. [Special handling](#severity-and-status-tags) is given to `severity` and `status` keys. | @@ -210,18 +212,18 @@ Run task outcomes with tags named "severity" or "status" are enriched within the "tags": { "Status": [ { - "label": "Denied", - "level": "error" + "label": "Denied", + "level": "error" } ], "Severity": [ { - "label": "High", - "level": "error" + "label": "High", + "level": "error" }, { "label": "Recoverable", - "level": "info" + "level": "info" } ], "Cost Centre": [ @@ -260,18 +262,18 @@ The example below shows a complete payload explaining the data structure of a ca "tags": { "Status": [ { - "label": "Denied", - "level": "error" + "label": "Denied", + "level": "error" } ], "Severity": [ { - "label": "High", - "level": "error" + "label": "High", + "level": "error" }, { - "label": "Recoverable", - "level": "info" + "label": "Recoverable", + "level": "info" } ], "Cost Centre": [ diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx index a2c11e17c7..c0b0a8fcc7 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx @@ -81,18 +81,19 @@ This POST endpoint requires a JSON object with the following properties as a req Properties without a default value are required unless otherwise specified. -| Key path | Type | Default | Description | -| -------------------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `data.type` | string | | Must be `"tasks"`. | -| `data.attributes.name` | string | | The name of the task. Can include letters, numbers, `-`, and `_`. | -| `data.attributes.url` | string | | URL to send a run task payload. | -| `data.attributes.description` | string | | The description of the run task. Can be up to 300 characters long including spaces, letters, numbers, and special characters. | -| `data.attributes.category` | string | | Must be `"task"`. | -| `data.attributes.hmac-key` | string | | (Optional) HMAC key to verify run task. | -| `data.attributes.enabled` | bool | true | (Optional) Whether the task will be run. | -| `data.attributes.global-configuration.enabled` | bool | false | (Optional) Whether the task will be associated on all workspaces. | -| `data.attributes.global-configuration.stages` | array | | (Optional) An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | -| `data.attributes.global-configuration.enforcement-level` | string | | (Optional) The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | +| Key path | Type | Default | Description | +| -------------------------------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"tasks"`. | +| `data.attributes.name` | string | | The name of the task. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.url` | string | | URL to send a run task payload. | +| `data.attributes.description` | string | | The description of the run task. Can be up to 300 characters long including spaces, letters, numbers, and special characters. | +| `data.attributes.category` | string | | Must be `"task"`. | +| `data.attributes.hmac-key` | string | | (Optional) HMAC key to verify run task. | +| `data.attributes.enabled` | bool | true | (Optional) Whether the task will be run. | +| `data.attributes.global-configuration.enabled` | bool | false | (Optional) Whether the task will be associated on all workspaces. | +| `data.attributes.global-configuration.stages` | array | | (Optional) An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | +| `data.attributes.global-configuration.enforcement-level` | string | | (Optional) The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | +| `data.relationships.agent-pool.data.id` | string | | (Optional) The agent pool that HCP Terraform uses to make requests for the run task. Requires the [`private_run_tasks` feature entitlement](/terraform/enterprise/api-docs#feature-entitlements) and a self-hosted HCP Terraform agent with [request forwarding](/terraform/cloud-docs/agents/request-forwarding). | ### Sample Payload @@ -112,6 +113,14 @@ Properties without a default value are required unless otherwise specified. "stages": ["pre_plan"], "enforcement-level": "mandatory" } + }, + "relationships": { + "agent-pool": { + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools" + } + } } } } @@ -134,34 +143,40 @@ curl \ { "data": { "id": "task-7oD7doVTQdAFnMLV", - "type": "tasks", - "attributes": { - "category": "task", - "name": "my-run-task", - "url": "http://example.com", - "description": "Simple description", - "enabled": "true", - "hmac-key": null, - "global-configuration": { - "enabled": true, - "stages": ["pre_plan"], - "enforcement-level": "mandatory" + "type": "tasks", + "attributes": { + "category": "task", + "name": "my-run-task", + "url": "http://example.com", + "description": "Simple description", + "enabled": "true", + "hmac-key": null, + "global-configuration": { + "enabled": true, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" } }, - "relationships": { - "organization": { - "data": { - "id": "hashicorp", - "type": "organizations" - } - }, - "tasks": { - "data": [] - } + "tasks": { + "data": [] }, - "links": { - "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + "agent-pool": { + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools" + } } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } } } ``` @@ -201,56 +216,58 @@ curl \ ```json { - "data": [ - { - "id": "task-7oD7doVTQdAFnMLV", - "type": "tasks", - "attributes": { - "category": "task", - "name": "my-task", - "url": "http://example.com", - "description": "Simple description", - "enabled": "true", - "hmac-key": null, - "global-configuration": { - "enabled": true, - "stages": ["pre_plan"], - "enforcement-level": "mandatory" - } - }, - "relationships": { - "organization": { - "data": { - "id": "hashicorp", - "type": "organizations" - } - }, - "tasks": { - "data": [] - } - }, - "links": { - "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" - } + "data": [ + { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks", + "attributes": { + "category": "task", + "name": "my-task", + "url": "http://example.com", + "description": "Simple description", + "enabled": "true", + "hmac-key": null, + "global-configuration": { + "enabled": true, + "stages": [ + "pre_plan" + ], + "enforcement-level": "mandatory" } - ], - "links": { - "self": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", - "first": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", - "prev": null, - "next": null, - "last": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?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": 1 + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [] } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?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": 1 + } + } } ``` diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-access.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-access.mdx index 8d873b5c3f..54ed8a467c 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-access.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-access.mdx @@ -43,7 +43,7 @@ source: terraform-docs-common --> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). +@include 'tfc-package-callouts/team-management.mdx' diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-members.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-members.mdx index b3cf58069b..310dfa6121 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-members.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-members.mdx @@ -42,7 +42,7 @@ source: terraform-docs-common --> **Note:** Team management is available in HCP Terraform **Standard** Edition. Free organizations can also use this API, but can only manage membership of their owners team. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). +-> **Note:** Team management is available in HCP Terraform **Standard**, **Plus**, and **Premium** editions. Free organizations can also use this API, but can only manage membership of their owners team. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-tokens.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-tokens.mdx index ed5921623e..9db2a1196a 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-tokens.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/team-tokens.mdx @@ -1,8 +1,8 @@ --- -page_title: /teams/authentication-token API reference for Terraform Enterprise +page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise' description: >- - Use the Terraform Enterprise API's `/teams/authentication-token` endpoint to - generate, delete, and list a team's API tokens. + Use the Terraform Enterprise API's `/teams/:team_id/authentication-tokens` + endpoint to generate, delete, and list a team's API tokens. source: terraform-docs-common --- @@ -40,7 +40,266 @@ source: terraform-docs-common # Team tokens API reference -Team API tokens grant access to a team's workspaces. Each team can have an API token that is not associated with a specific user. You can create and delete team tokens and list an organization's team tokens. +Team API tokens grant access to a team's workspaces. Teams are not limited to a single token, and can have multiple tokens at a time. Team tokens are not associated with a specific user. + +Teams relying on the [**legacy**](/terraform/enterprise/api-docs/team-tokens#legacy-team-tokens-api-reference) team token API (`/teams/:team_id/authentication-token`), can only create a **single**, valid token at a time. Generating a new legacy token when one already exists for the team revokes the existing legacy token, replacing it with a new team token. + +You can create and delete team tokens and list an organization's team tokens. + +## Generate a new team token + +Generates a new team token. + +| Method | Path | +| :----- | :------------------------------------ | +| POST | /teams/:team_id/authentication-tokens | + +This endpoint returns the secret text of the new authentication token. You can only access the secret text when you create it and cannot recover it later. + +### Parameters + +- `:team_id` (`string: `) - specifies the team ID for generating the team token + +### Request body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"authentication-tokens"`. | +| `data.attributes.description` | string | | The description of the team token. Each description **must** be unique within the context of the team. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the Team Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | + +### Sample payload + +```json +{ + "data": { + "type": "authentication-tokens", + "attributes": { + "description": "Team API token for team ABC", + "expired-at": "2023-04-06T12:00:00.000Z" + } + } +} +``` + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/team-BUHBEM97xboT8TVz/authentication-tokens +``` + +### Sample response + +```json +{ + "data": { + "id": "4111797", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + } + } + } +} + +``` + +## Delete a team token + +| Method | Path | +| :----- | :------------------------------- | +| DELETE | /authentication-tokens/:token_id | + +### Parameters + +- `:token_id` (`string: `) - specifies the token_id from which to delete the token + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` + +## List team tokens + +Lists the team tokens for the team. + +`GET /organizations/:organization_id/team-tokens` + +| Parameter | Description | +| ------------------ | -------------------------------------------------------------- | +| `:organization_id` | The ID of the organization whose team tokens you want to list. | + +This endpoint returns object metadata and does not include secret authentication details of tokens. You can only view a token when you create it and cannot recover it later. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-tokens"`) | The request was successful. | +| [200][] | Empty [JSON API document][] | The specified team has no team tokens. | +| [404][] | [JSON API error object][] | Team not found. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters) and searching with the `q` parameter. Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 tokens per page. | +| `q` | **Optional.** A search query string. You can search for a team authentication token using the team name. | +| `sort` | **Optional.** Allows sorting the team tokens by `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. If omitted, the default sort order ascending. | + +### Sample response + +```json +{ + "data": [ + { + "id": "at-TLhN8cc6ro6qYDvp", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-Y7RyjccPVBKVEdp7", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629sszLJBpY", + "type": "users" + } + } + } + }, + { + "id": "at-qfc2wqqJ1T5sCamM", + "type": "authentication-tokens", + "attributes": { + "created-at": "2024-06-19T18:44:44.051Z", + "last-used-at": null, + "description": "Team API token for team XYZ", + "token": null, + "expired-at": "2024-07-19T18:44:43.818Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-58pFiBffTLMxLphR", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-ccU6h629hhzLJBpY", + "type": "users" + } + } + } + }, + ] +} +``` + +## Show a team token + +Use this endpoint to display a particular [team token](/terraform/enterprise/users-teams-organizations/teams#api-tokens). + +`GET /authentication-tokens/:token_id` + +| Parameter | Description | +| ----------- | ------------------------- | +| `:token_id` | The ID of the Team Token. | + +The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Token not found, or unauthorized to view the Team Token | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/authentication-tokens/at-6yEmxNAhaoQLH1Da +``` + +### Sample response + +```json +{ + "data": { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": "Team API token for team ABC", + "token": "QnbSxjjhVMHJgw.atlasv1.gxZnWIjI5j752DGqdwEUVLOFf0mtyaQ00H9bA1j90qWb254lEkQyOdfqqcq9zZL7Sm0", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-LnREdjodkvZFGdXL", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +# Legacy team tokens API reference + +Legacy team API tokens grant access to a team's workspaces. Each team can have a single legacy API token that is not associated with a specific user. +You can create and delete team tokens and list an organization's team tokens. +The [team tokens API](/terraform/enterprise/api-docs/team-tokens) includes the same functionality as legacy team tokens, and allows you to provision multiple tokens with descriptions per team. ## Generate a new team token @@ -50,7 +309,7 @@ Generates a new team token and overrides existing token if one exists. | :----- | :----------------------------------- | | POST | /teams/:team_id/authentication-token | -This endpoint returns the secret text of the new authentication token. You can only access this token when you create it and can not recover it later. +This endpoint returns the secret text of the new authentication token. You can only access the secret when you create it and cannot recover it later. ### Parameters @@ -235,21 +494,21 @@ This endpoint supports pagination [with standard URL query parameters](/terrafor Use this endpoint to display a [team token](/terraform/enterprise/users-teams-organizations/teams#api-tokens) for a particular team. -`GET /teams/:team-id/authentication-token` +`GET /teams/:team_id/authentication-token` | Parameter | Description | | ---------- | ------------------- | -| `:team-id` | The ID of the Team. | +| `:team_id` | The ID of the Team. | You can also fetch a team token directly by using the token's ID with the `authentication-tokens/` endpoint. -`GET /authentication-tokens/:token-id` +`GET /authentication-tokens/:token_id` | Parameter | Description | | ----------- | ------------------------- | -| `:token-id` | The ID of the Team Token. | +| `:token_id` | The ID of the Team Token. | -The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret test is only shown upon creation, and cannot be recovered later. +The object returned by this endpoint only contains metadata, and does not include the secret text of the authentication token. A token's secret text is only shown upon creation, and cannot be recovered later. | Status | Response | Reason | | ------- | ------------------------------------------------------- | ------------------------------------------------------------ | diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/workspaces.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/workspaces.mdx index 57e82778fd..b29e7c83d8 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/workspaces.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/api-docs/workspaces.mdx @@ -1526,12 +1526,15 @@ This endpoint adds keys and values or updates values of tag-bindings on an exist It does not remove any keys from the collection. This endpoint is useful when you want to ensure a modification is additive. -Tag Bindings have special constraints: - -- Up to 10 tags can be applied to a workspace, but an additional 10 tags may be inherited from its project. -- Keys must be no more than 128 characters, allowing all alphanumeric characters plus the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. -- Values allow the same characters, but can be up to 256 characters. -- Certain key prefixes, including `hc:` and `hcp:` are not allowed. +Tag bindings have special constraints and behaviors: + +- You can apply up to 10 tags per workspace. +- Workspaces can inherit an additional 10 tags from its project. +- Keys can have up to 128 characters. +- Keys can contain all alphanumeric characters and the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. +- values can have up to 256 characters. +- Values can contain all alphanumeric characters and the symbols `_`, `.`, `=`, `+`, `-`, `@`, `:`. +- You cannot use `hc:` and `hcp:` as key prefixes. `PATCH /workspaces/:workspace_id/tag-bindings` diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx index fa9517afbf..42d6ca5277 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/integrations/kubernetes/setup.mdx @@ -18,7 +18,7 @@ All HCP Terraform users can use the HCP Terraform Operator for Kubernetes. You c ## Networking requirements -The HCP Terraform Operator for Kubernetes makes outbound requests over HTTPS (TCP port 443) to the HCP Terraform application APIs. This may require perimeter networking as well as container host networking changes, depending on your environment. Refer to [HCP Terraform IP Ranges](/terraform/enterprise/architectural-details/ip-ranges) for more information about IP ranges. Below, we list the services that run on specific IP ranges. +The HCP Terraform Operator for Kubernetes makes outbound requests over HTTPS (TCP port 443) to the HCP Terraform application APIs. This may require perimeter networking as well as container host networking changes, depending on your environment. Refer to [HCP Terraform IP Ranges](/terraform/cloud-docs/architectural-details/ip-ranges) for more information about IP ranges. Below, we list the services that run on specific IP ranges. | Hostname | Port/Protocol | Directionality | Purpose | | ------------------ | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | @@ -59,40 +59,36 @@ The HCP Terraform Operator for Kubernetes supports the following versions: helm repo add hashicorp https://helm.releases.hashicorp.com -8. Install the [HCP Terraform Operator for Kubernetes with Helm](https://github.com/hashicorp/hcp-terraform-operator). By default, the operator communicates with `app.terraform.io`. When deploying in a self-managed Terraform Enterprise, you must set the `operator.tfeAddress` to the specific hostname of the Terraform Enterprise instance. +8. Install the [HCP Terraform Operator for Kubernetes with Helm](https://github.com/hashicorp/hcp-terraform-operator). By default, the operator communicates with HCP Terraform at `app.terraform.io`. The following example command installs the Helm chart for HCP Terraform: - - The following example command installs the Helm chart for HCP Terraform Cloud, which is the default: - - ```shell-session - $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator - ``` + ```shell-session + $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator + ``` - - To install the Helm chart for self-managed Terraform Enterprise, specify your instance's hostname: + When deploying in self-managed Terraform Enterprise, you must set the `operator.tfeAddress` to the specific hostname of the Terraform Enterprise instance: - ```shell-session - $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator \ - --set operator.tfeAddress="TERRAFORM_ENTERPRISE_HOSTNAME" - ``` + ```shell-session + $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator \ + --set operator.tfeAddress="TERRAFORM_ENTERPRISE_HOSTNAME" + ``` - - Alternatively, you can set this configuration in the [value.yaml](https://github.com/hashicorp/hcp-terraform-operator/blob/main/charts/hcp-terraform-operator/values.yaml) file. + Alternatively, you can set the `tfeAddress` configuration for Terraform Enterprise in the [value.yaml](https://github.com/hashicorp/hcp-terraform-operator/blob/main/charts/hcp-terraform-operator/values.yaml) file. ```yaml operator: tfeAddress: ``` - - Use the following command to apply the values.yaml file: + Run the following command to apply the value.yaml file: - ```shell-session - $ helm install --namespace ${NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator -f value.yaml - ``` + ```shell-session + $ helm install --namespace ${NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator -f value.yaml + ``` -9. To create a Terraform workspace, agent pool or etc, you can find different [examples](https://github.com/hashicorp/hcp-terraform-operator/tree/main/docs/examples) of the YAML manifests. +9. To create a Terraform workspace, agent pool, or other object, refer to the example YAML manifests in the [operator repository on GitHub](https://github.com/hashicorp/hcp-terraform-operator/tree/main/docs/examples). ### Upgrade When a new version of the HCP Terraform Operator for Kubernetes Helm Chart is available from the HashiCorp Helm repository, you can upgrade with the following command. -```shell-session -$ helm upgrade --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator -``` + helm upgrade --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx index e625181e1e..96b511744b 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/integrations/service-now/service-graph/index.mdx @@ -8,7 +8,7 @@ source: terraform-docs-common # ServiceNow Service Graph Connector for Terraform overview --> **Integration version:** v1.2.0 +-> **Integration version:** v1.3.0 Use the Service Graph Connector for Terraform to securely import HCP Terraform resources into your ServiceNow instance. The ServiceNow Service Graph for Terraform is a certified scoped application available in the [ServiceNow Store](https://store.servicenow.com/sn_appstore_store.do#!/store/application/0b0600891b52c150c216ebd56e4bcb32). diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/migrate/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/migrate/index.mdx index de34c14ddb..e7d1fdb635 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/migrate/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/migrate/index.mdx @@ -18,7 +18,7 @@ Perform the following actions to migrate existing resources to one or more works 1. Stop all Terraform operations associated with the state files. 2. Migrate Terraform state files using either the Terraform CLI or the HCP Terraform or Terraform Enterprise API. -Use one of the following methods to migrate your state: +You have three options to migrate your state: 1. Manually using the Terraform CLI 2. Automatically using `tf-migrate` @@ -89,3 +89,7 @@ You can use the Terraform migrate CLI tool to automatically migrate state to HCP Refer to the following external article for an example of how to create a script in Python to automate multiple state files: [Migrating A Lot of State with Python and the HCP Terraform (previously Terraform Cloud) API](https://medium.com/hashicorp-engineering/migrating-a-lot-of-state-with-python-and-the-terraform-cloud-api-997ec798cd11). The example uses the [Workspaces API](/terraform/enterprise/api-docs/workspaces#create-a-workspace) to create the necessary workspaces in HCP Terraform and the [State Versions API](/terraform/enterprise/api-docs/state-versions) to migrate the state files to those workspaces. + +## Migrate state using Terraform migrate + +You can use the Terraform migrate CLI tool to automatically migrate state to HCP Terraform and Terraform Enterprise. The tool does not ship with HCP Terraform. You must download and install the binary for the CLI tool separately. Refer to the [Terraform migrate documentation](/terraform/enterprise/migrate/tf-migrate) for more information. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx index c5cf8a8a88..c64a99593a 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx @@ -34,7 +34,15 @@ Only Sentinel policies can run as policy checks. Checks can access cost estimati ### Policy evaluations -OPA policy sets can only run as policy evaluations, and you can enable policy evaluations for Sentinel policy sets by selecting the `Agent` policy set type. Policy evaluations run within the [HCP Terraform agent](/terraform/cloud-docs/agents) in HCP Terraform's infrastructure. +OPA policy sets can only run as policy evaluations, and you can enable policy evaluations for Sentinel policy sets by selecting the `Agent` policy set type. + +HCP Terraform runs a workspace's policy evaluation in your self-managed agent pool if you meet the following requirements: + +- You are on the HCP Terraform **Premium** edition. +- You configure the workspace to run Terraform operations in your self-managed agent pool. Refer to [Configure Workspaces to use the Agent](/terraform/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for more information. +- You configure at least one agent in the agent pool to accept `policy` jobs. Refer to the [HCP Terraform agent reference](/terraform/cloud-docs/agents/agents#accept) for more information. + +If you do not meet all of the above requirements, then policy evaluations run within HCP Terraform's infrastructure. For Sentinel policy sets, using policy evaluations lets you: diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/projects/manage.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/projects/manage.mdx index 3cc40daf60..3ad84ad7e5 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/projects/manage.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/projects/manage.mdx @@ -66,7 +66,7 @@ team access to the project. You can configure HCP Terraform to automatically destroy each workspace's infrastructure in a project after a period of inactivity. A workspace -is _inactive_ if the workspace's state has not changed within your designated +is inactive if the workspace's state has not changed within your designated time period. If you configure a project to auto-destroy its infrastructure when inactive, @@ -74,7 +74,9 @@ any run that updates Terraform state further delays the scheduled auto-destroy time by the length of your designated timeframe. -HCP Terraform and Terraform Enterprise do not prompt you to approve automated destroy plans. We recommend only using this setting for development environments. + +The user interface does not prompt you to approve automated destroy plans. We recommend only using this setting for development environments. + To schedule an auto-destroy run after a period of workspace inactivity: diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/registry/add.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/registry/add.mdx index 72fbd0d5d4..50b3130f06 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/registry/add.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/registry/add.mdx @@ -34,7 +34,7 @@ To add a public provider or module: 3. Click **Search public registry**. The **Public Registry Search** page appears. -4. Enter any combination of namespaces, such as `hashicorp`, and module or provider names into the search field. You can click **Providers** and **Modules** to toggle between lists of providers and modules that meet the search criteria. +4. Enter any combination of namespaces (such as hashicorp), and module or provider names into the search field. You can click **Providers** and **Modules** to toggle between lists of providers and modules that meet the search criteria. 5. Do one of the following to add a provider or module to your private registry: - Hover over the provider or module and click **+ Add**. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/registry/manage-module-versions.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/registry/manage-module-versions.mdx index e43344db22..2c83eeefec 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/registry/manage-module-versions.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/registry/manage-module-versions.mdx @@ -1,16 +1,18 @@ --- -page_title: Deprecate module versions in Terraform Enterprise +page_title: Manage module versions in Terraform Enterprise description: >- - 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. + Learn how to deprecate and revoke module versions to signal the end of support + for those versions. Deprecating a module version warns users to upgrade soon, + and revoking a module version signals you no longer maintain support for a + module version and blocks new consumers. source: terraform-docs-common --- -# Deprecate module versions +# Manage 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. +<>{/* TODO: remove revoke references here */} + +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. @@ -18,65 +20,199 @@ Deprecating a module version in your organization’s private registry adds warn -You can also [deprecate module versions using the HCP Terraform API](/terraform/enterprise/api-docs/private-registry/manage-module-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](/terraform/enterprise/api-docs/private-registry/manage-module-versions). + +<>{/* TODO: remove revoke references here */} + +## 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. -## Background +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. -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. +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](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/permissions#manage-private-registry) -- the module must be in the [private](https://developer.hashicorp.com/terraform/cloud-docs/registry/publish-modules) registry +- you must have permission to manage [private registry modules](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) +- the module must be in the [private](/terraform/enterprise/registry/publish-modules) 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](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) +- the module must be in an organization's [private registry](/terraform/enterprise/registry/publish-modules) +- you must be a member of an organization on the HCP Terraform **Premium** edition + + +<>{/* TODO: don't forget to exclude PNP above when remove tags */} ## Deprecate a module version To deprecate a module version, perform the following steps: 1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. -2. Choose **Registry** in the sidebar to navigate to your organization’s private registry, 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. +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**](/terraform/enterprise/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. +If the module version you are deprecating has the [**No-code ready**](/terraform/enterprise/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. ### 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. +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](/terraform/enterprise/workspaces/settings#execution-mode) can receive warnings for a module version’s deprecation. -~> **Note**: Only workspaces in the [remote or agent execution modes](/terraform/enterprise/workspaces/settings#execution-mode) can receive warnings for a module version’s deprecation. +If you provided a reason for a module version’s deprecation, then deprecation warnings contain that reason: -If you provided a reason for a module version’s deprecation, then the warning users receive contains that reason and the following message: + ```shell Found the following deprecated module versions, consider using an updated version. ``` -A run’s output mode affects where a module deprecation’s warning appears. If a run set to the default [**Structured Run Output**](/terraform/enterprise/workspaces/settings#user-interface) mode, then module deprecation warnings show up under a run’s Diagnostics dropdown. + + +A run’s output mode affects where a version's deprecation warning appears. If a workspace is in the default [**Structured Run Output**](/terraform/enterprise/workspaces/settings#user-interface) 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: + + ```shell Warning: Deprecated modules found, consider installing an updating version. The following are affected: Version X.X.X of ``` + + ## Revert the deprecation of a module version To revert a module version’s deprecation, perform the following steps: 1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. -2. Choose **Registry** in the sidebar to navigate to your organization’s private registry, then find the deprecated 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**. +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. +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. + +<>{/* TODO: add TFE to bullet points */} + + + +## Revoke a module version + +To revoke a module version, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) 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](#deprecate-a-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**](/terraform/enterprise/no-code-provisioning/module-design#updating-a-module-s-version) 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. + +~> **Note**: Only workspaces in the [remote or agent execution modes](/terraform/enterprise/workspaces/settings#execution-mode) can receive warnings for a module version’s revocation. + +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: + + + +```shell +This run references revoked module versions, but this will proceed due to referencing a previously used module version. +Module version X.X.X of is revoked. + + +``` + + + +A run’s output mode affects where a version's revocation warnings appear. If a workspace is in the default [**Structured Run Output**](/terraform/enterprise/workspaces/settings#user-interface) 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: + + + +```shell +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 + + +``` + + + +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: + + + +```shell +This run references revoked module versions, this run will not proceed. +Module version of is revoked. + +``` + + + +A run’s output mode affects where a module revocation’s warning appears. If a run set to the default [**Structured Run Output**](/terraform/enterprise/workspaces/settings#user-interface) 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: + + + +```shell +│ Alert: Revoked modules found, this run will not continue. The following modules have been revoked: +│ +│ Version X.X.X of +│ +│ +``` + + + +## 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](https://app.terraform.io/) 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**. + + diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/registry/test.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/registry/test.mdx index 9b2f7084f9..377e7f3402 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/registry/test.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/registry/test.mdx @@ -27,9 +27,9 @@ To enable testing after you publishing your branch-based module: ## Run tests remotely from the CLI -After publishing and enabling testing for your module, you can use the Terraform CLI locally to trigger remotely-executed tests in HCP Terraform. This lets you test your module changes using the credentials configured in HCP Terraform without committing your changes to version control. +After publishing and enabling testing for your module, you can use the Terraform CLI locally to trigger remotely-executed tests in HCP Terraform. This lets you test your module changes using the credentials configured in HCP Terraform without committing your changes to version control. -To run your tests remotely, use the `-cloud-run` flag with the path to your module in your private registry. +To run your tests remotely, use the `-cloud-run` flag with the path to your module in your private registry. ```shell terraform test -cloud-run=app.terraform.io/:ORG/:MODULE_NAME/:PROVIDER @@ -37,12 +37,12 @@ terraform test -cloud-run=app.terraform.io/:ORG/:MODULE_NAME/:PROVIDER ## Configure environment variables -You can define test-specific environment variables that HCP Terraform will use for testing. If your tests provision infrastructure, you must configure provider credentials for the module. +You can define test-specific environment variables that HCP Terraform will use for testing. If your tests provision infrastructure, you must configure provider credentials for the module. To add environment variables to your module's tests: -1. On the module overview screen, click **Configure Tests**. -2. In the **Variables** section on the **Tests Settings** screen, click **+ Add variable**. +1. On the module overview screen, click **Configure Tests**. +2. In the **Variables** section on the **Tests Settings** screen, click **+ Add variable**. 3. Provide a **Key** and **Value** for your environment variable, and if you want to protect the variable's value, click the **Sensitive** checkbox. `TF_VAR_x` variables of a string type that are not defined in a config must be wrapped in double-quotes. 4. Click **Add variable** to save it. @@ -50,7 +50,7 @@ To add environment variables to your module's tests: ## Generated module tests -~> **Note**: Generated module tests are available in HCP Terraform **Plus** Edition and are in public beta. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. +@include 'tfc-package-callouts/tests.mdx' HCP Terraform can generate [test files](/terraform/language/tests) for any private module in your registry. You can only generate tests one time per module. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/run/modes-and-options.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/run/modes-and-options.mdx index 136e6d374d..9a1e6a0f8d 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/run/modes-and-options.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/run/modes-and-options.mdx @@ -12,7 +12,7 @@ HCP Terraform runs support many of the same modes and options available in the T ## Plan and Apply (Standard) -The default run mode of HCP Terraform is to perform a plan and then apply it. If you have enabled auto-apply, a successful plan applies immediately. Otherwise, the run waits for user confirmation before applying. +The default run mode of HCP Terraform is to perform a plan and then apply it. If you have enabled auto-apply and are using a VCS or API workflow, a successful plan applies immediately. Otherwise, the run waits for user confirmation before applying. - **CLI:** Use `terraform apply` (without providing a saved plan file). - **API:** Create a run without specifying any options that select a different mode. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/run/run-environment.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/run/run-environment.mdx index 03955a60e3..ccae094a3f 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/run/run-environment.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/run/run-environment.mdx @@ -25,9 +25,15 @@ Changes made to the worker during a run are not persisted to subsequent runs, si ## Network Access to VCS and Infrastructure Providers -In order to perform Terraform runs, HCP Terraform needs network access to all of the resources being managed by Terraform. +In order to perform Terraform runs, HCP Terraform needs network access to all of the resources Terraform is going to manage. -If you are using the SaaS version of HCP Terraform, this means your VCS provider and any private infrastructure providers you manage with Terraform (including VMware vSphere, OpenStack, other private clouds, and more) _must be internet accessible._ +If you are using the cloud version of HCP Terraform, your VCS provider and any private infrastructure providers you manage with Terraform must be internet accessible. + + + +If you are on the HCP Terraform **Premium** edition, you can use a self-hosted HCP Terraform agent to connect to private VCS providers. Refer to [Connect to private VCS providers](/terraform/enterprise/vcs/private) for more information. + + Terraform Enterprise instances must have network connectivity to any connected VCS providers or managed infrastructure providers. @@ -41,7 +47,7 @@ If the global queue has more runs than the workers can handle at once, some of t - Normal plans have the next highest priority. - Speculative plans have the lowest priority. -HCP Terraform can also delay some runs in order to make performance more consistent across organizations. If an organization requests a large number of runs at once, HCP Terraform queues some of them immediately, and delays the rest until some of the initial batch have finished; this allows every organization to continue performing runs even during periods of especially heavy load. +HCP Terraform can also delay some runs in order to make performance more consistent across organizations. If an organization requests a large number of runs at once, HCP Terraform queues some of them immediately, and delays the rest until some of the initial batch have finished. Queuing and delaying runs lets organizations continue performing runs even during periods of especially heavy load. Your HCP Terraform edition limits the maximum run concurrency for your organization. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing?product_intent=terraform) for details. ## State Access and Authentication diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/run/ui.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/run/ui.mdx index bf1f468aa0..36fb9b192b 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/run/ui.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/run/ui.mdx @@ -41,6 +41,8 @@ A workspace will not process a webhook if the workspace previously processed a w You can manually trigger a run using the UI. Manual runs let you apply configuration changes when you update variable values but the configuration in version control is unchanged. You must manually trigger an initial run in any new VCS-driven workspace. +-> **Note:** When you trigger a manual run, HCP Terraform does not fetch the latest commit from your VCS repository, and instead uses the current [configuration version](/terraform/enterprise/workspaces/configurations) associated with the workspace. HCP Terraform uses [VCS Webhooks](/terraform/enterprise/vcs#webhooks) to monitor changes in your VCS repository and update your configuration version. + To start a run: 1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to start a run in. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx index e344aa94df..f9377e882c 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/2fa.mdx @@ -40,7 +40,7 @@ Click the button "Require two-factor". Please remember that all organization own ## Requiring Two-factor Authentication for Users with HashiCorp Cloud Platform -When you require two-factor authentication for all users and have users who [sign in with their HashiCorp Cloud Platform account](/terraform/enterprise/users-teams-organizations/users#log-in-with-your-hashicorp-cloud-platform-account), the required configuration for each organization member depends on their linked HashiCorp Cloud identity: +When you require two-factor authentication for all users and have users who [sign in with their HashiCorp Cloud Platform Account](/terraform/enterprise/users-teams-organizations/users#log-in-with-your-hashicorp-cloud-platform-account), the required configuration for each organization member depends on their linked HashiCorp Cloud identity: - **Email**: Follow the instructions in the [HashiCorp Cloud MFA](/hcp/docs/hcp/admin/iam/mfa) docs. - **GitHub**: Follow the instructions in the [Configuring GitHub two-factor authentication](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication) docs. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx index 54b269b565..5aa5db1023 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -16,15 +16,19 @@ Refer to [Team Token API](/terraform/enterprise/api-docs/team-tokens) and [Organ ## User API Tokens -API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/enterprise/users-teams-organizations/users#api-tokens) documentation. +API tokens may belong directly to a user. User tokens are the most flexible token type because they inherit permissions from the user they are associated with. For more information on user tokens and how to generate them, see the [Users](/terraform/enterprise/users-teams-organizations/users#tokens) documentation. ## Team API Tokens API tokens may belong to a specific team. Team API tokens allow access to the workspaces that the team has access to, without being tied to any specific user. -Navigate to the **Organization settings > API Tokens > Team Token** tab to manage API tokens for a team or create new team tokens. +Navigate to the **Organization Settings > API Tokens > Team Tokens** tab to manage API tokens for a team or create new team tokens. -Each team can have **one** valid API token at a time. When a token is regenerated, the previous token immediately becomes invalid. +Teams can have multiple valid tokens at a time, so long as the tokens' descriptions are unique within the context of the given team. A token without a description is considered a legacy token, and only one legacy token can exist at a given time. + +The [**legacy API**](/terraform/enterprise/api-docs/team-tokens#legacy-team-tokens-api-reference) will only operate on the legacy token, and generating a new legacy token invalidates the previous legacy token. + +The [**non-legacy API**](/terraform/enterprise/api-docs/team-tokens#team-tokens-api-reference) will support the existence of multiple, valid team tokens, meaning that when a new, non-legacy token is generated, existing tokens will remain valid. Owners and users with [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permissions have the ability to enable and disable team token management for a team, which limits the actions that team members can take on a team token. Refer to [Allow Member Token Management](/terraform/enterprise/users-teams-organizations/permissions#allow-member-token-management) for more information. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx index 60d193bf5e..543f10aaa0 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/organizations/index.mdx @@ -80,6 +80,7 @@ You can view your organization's managed resource count on the **Usage** page. ## Create and manage reserved tag keys +~> **Reserved tag keys are in beta**: We do not recommend using beta features in production environments. You can define reserved tag keys that appear as suggested labels when managers want to add tags to their projects and workspaces in the organization. Refer to [Create and manage reserved tag keys](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for instructions. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx index 26e3e065f2..b57deb14a8 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/users-teams-organizations/permissions.mdx @@ -20,11 +20,15 @@ source: terraform-docs-common HCP Terraform's access model is team-based. In order to perform an action within an HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. -The permissions model is split into organization-level, project-level, and workspace-level permissions. Additionally, every organization has a special team named "owners", whose members have maximal permissions within the organization. +The HCP Terraform permissions model is split into three levels: you can set organization-level, project-level, and workspace-level permissions. Each permission level is additive, granting a user the highest level of permissions possible, regardless of which level set that permission. + +A team's _effective permissions_ is the sum of the permissions granted to that team from all permission levels. For example, if a team has the **View all workspaces** permission at the organization-level and **Admin** permission on a specific workspace, then users on that team have the effective permission of **Admin** on that workspace. An organization-level permission does not take precedence over a workspace-level permission. + +We recommend following the principle of least privilege when configuring permissions, only giving teams access to the resources they need for their job function. When configuring permissions at a particular level, remember that a team may have permissions above or below in the hierarchy that grant a higher level of permission than what you are currently configuring. ## Organization Owners -Every organization has a special "owners" team. Members of this team are often referred to as "organization owners". +Every organization has a special team called the **Owners** team, whose members have the maximum available permissions within the organization. Members of this team are often referred to as "organization owners". Organization owners have every available permission within the organization. This includes all organization-level permissions, and the highest level of workspace permissions on every workspace. @@ -326,7 +330,7 @@ Allows members to publish and delete providers, modules, or both providers and m ### Team Management Permissions -HCP Terraform has three levels of team management permissions: manage membership, manage teams, and manage organization access. Each permission level grants users the ability to perform specific actions and each progressively requires prerequisite permissions. +HCP Terraform has three levels of team management permissions: manage membership, manage teams, and manage organization access. Each permission level grants users the ability to perform specific actions and each progressively requires prerequisite permissions. For example, to grant a user the manage teams permission, that user must already have manage membership permissions. To grant a user the manage organization access permission, a user must have both manage teams and manage membership permissions. @@ -343,7 +347,7 @@ In order to remove a user from the organization, the holder of this permission m #### Manage Teams -Allows members to create, update, and delete teams, and generate, regenerate, and revoke tokens. +Allows members to create, update, and delete teams, and generate, and revoke tokens. This permission grants the ability to update a team's names, SSO IDs, and token management permissions, but does not allow access to organization settings. On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams. @@ -359,7 +363,7 @@ Allows members to update a team's organization access settings. On its own, this permission does not allow users to create, update, delete, or otherwise access secret teams. This permission confers all of the permissions granted by the manage teams and manage membership permissions. -This permission allows owners of large organizations to delegate team management to another trusted team. You should only grant it to teams of trusted users. +This permission allows owners of large organizations to delegate team management to another trusted team. You should only grant it to teams of trusted users. ~> **Assign with caution:** Members with this permission can update all organization access settings for any team visible to them. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx index 841d8e7ecb..1995aa8bc4 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-server.mdx @@ -1,20 +1,22 @@ --- page_title: Set up the Azure DevOps Server VCS provider description: >- - Learn how to use an on-premises installation of Azure DevOps Server 2019 with + Learn how to use an on-premises installation of Azure DevOps Server with workspaces and private registry modules in Terraform Enterprise. source: terraform-docs-common --- # Set up the Azure DevOps Server VCS provider -These instructions are for using an on-premises installation of Azure DevOps Server 2019 for HCP Terraform's VCS features. [Azure DevOps Services has separate instructions,](/terraform/enterprise/vcs/azure-devops-services) as do the [other supported VCS providers.](/terraform/enterprise/vcs) +These instructions describe how to connect to on-premise installations of Azure DevOps Server so that you can use HCP Terraform's VCS features. For instructions on how to set up Azure DevOps Services using OAuth, refer to [Set up the Azure DevOps Services VCS provider using OAuth](/terraform/enterprise/vcs/azure-devops-services). For information about other supported VCS providers, refer to [Connect to VCS Providers](/terraform/enterprise/vcs). -Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) +## Requirements + +You must have permission to manage VCS settings for the organization to configure a new VCS provider. Refer to [Permission model](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. [permissions-citation]: #intentionally-unused---keep-for-maintainers -## Important Notes About Authentication +### Personal access token maintenance HCP Terraform uses personal access tokens to connect to Azure DevOps Server. This access method requires some additional configuration and ongoing maintenance: diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services-pat.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services-pat.mdx new file mode 100644 index 0000000000..1da6dc1123 --- /dev/null +++ b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services-pat.mdx @@ -0,0 +1,116 @@ +--- +page_title: Set up the Azure DevOps Services VCS provider using personal access tokens +description: >- + Learn how to use Azure DevOps Services with workspaces and private registry + modules in Terraform Enterprise using personal access tokens. +source: terraform-docs-common +--- + +# Set up the Azure DevOps Services VCS provider using personal access tokens + +These instructions describe how to use a personal access token to connect HCP Terraform to Azure DevOps Services VCS, which is hosted at `dev.azure.com`. Connecting to Azure DevOps Services VCS lets you take advantage of HCP Terraform's VCS features. + +If you do not intend to use personal access tokens to connect to Azure DevOps Services, refer to [Set up the Azure DevOps Server VCS provider](/terraform/enterprise/vcs/azure-devops-server). For information about other supported VCS providers, refer to [Connect to VCS Providers](/terraform/enterprise/vcs). + +## Requirements + +Configuring a new VCS provider requires permission to [manage VCS settings](/terraform/enterprise/users-teams-organizations/permissions#manage-vcs-settings) for the organization. + +To connect HCP Terraform to your repositories, your account must have **Project Collection Administrator** access enabled for all projects containing Terraform configurations. This permission is required to create webhooks because Microsoft doesn't allow you to create custom roles with lower-level access for this purpose. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Personal access token maintenance + +HCP Terraform uses personal access tokens to connect to Azure DevOps Services. This access method requires some additional configuration and ongoing maintenance: + +- Personal access tokens have a maximum lifetime of one year. When the token expires, HCP Terraform cannot connect to Azure DevOps Services until the token is replaced. To avoid a gap in service, do one of the following actions before the token expires: + - Update the expiration date of the existing token within Azure DevOps Services. + - Create a new token and update the VCS configuration in HCP Terraform VCS connection to use it. + +Refer to the [Azure DevOps documentation](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?toc=%2Fazure%2Fdevops%2Forganizations%2Ftoc.json&view=azure-devops&tabs=Windows) for instructions on working with personal access tokens. + +## Step 1: Add a new VCS provider in HCP Terraform + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add the VCS provider. + +2. Choose **Settings** from the sidebar, then click **Providers**. + +3. Click **Add VCS Provider**. The **VCS Providers** page appears. + +4. Select **Azure DevOps** and then select **Azure DevOps Services** from the menu. The page moves to the next step. + +5. Select **Configure with Personal Access Token** + +Leave the page open in a browser tab. In the next step you will copy values from this page, and in later steps you will continue configuring HCP Terraform. + +## Step 2: Create a new personal access token in Azure DevOps Services + +1. In a new browser tab, open your Azure DevOps Services instance and log in as whichever account you want HCP Terraform to act as. Many organizations use a dedicated service user but a personal account is acceptable. + +2. Navigate to User settings -> Security -> Personal access tokens. + +3. Click the **New Token** button to generate a new personal access token with **Code (Read)** and **Code (Status)** scopes. We recommend also granting access to **All accessible organizations** and setting an expiration that meets your requirements. + +4. Click **Create**. + +5. Copy the generated token to your clipboard so that you can use it in the next step. Leave this page open in a browser tab. + +## Step 3: Add the personal access token on HCP Terraform + +1. Return to the browser window you opened in [Step 1: Add a new VCS provider in HCP Terraform](#step-1-add-a-new-vcs-provider-in-hcp-terraform). +2. In the second step under **Set up provider**, specify a name for your VCS provider a name in the **Name** field. This field is optional. +3. In the second step under **Set up provider**, paste the Azure DevOps Services personal access token you copied in [step 2](#step-2-create-a-new-personal-access-token-in-azure-devops-services) into the **Personal Access Token** field. +4. Click **Connect and continue\*\*** to continue. + +## Step 4: Configure advanced settings in HCP Terraform (optional) + +It is optional, but you can configure the following settings in the **Advanced Settings** screen: + +- In the **Scope of VCS Provider** setting, enable workspaces to use repositories from this VCS provider. **All Projects** is enabled by default. This setting lets all workspaces in the organization use the VCS provider. +- In the **Set up SSH Keypair** setting, you can add or update an SSH key and OAuth credentials so that HCP Terraform can access Git submodules in repositories that require them. You configure these settings later. + +If you don't need to configure either of the advanced settings, click **Skip and Finish** to complete the setup and return to HCP Terraform's VCS Provider page, which includes your new Azure DevOps Services client. Otherwise, complete the following steps. + +### Limit the scope of this VCS provider + +1. Enable **Selected Projects** and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. + +2. Click **Update VCS Provider** to save your selections. + +3. Click the **Update VCS Provider** button to save your selections. + +### Add an SSH key pair + +HCP Terraform only uses SSH to clone Git submodules and uses HTTPS for all other Git operations. +Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services. You should generate a new key or use an existing key reserved for service access. + +In the following steps, you must provide HCP Terraform with the private key. Although HCP Terraform does not display the text of the key to users after it is entered, HCP Terraform retains the key and uses for authenticating with Azure DevOps Services. + + + +Follow security best practices and your organization's policies for protecting important credentials when handing and storing a private key. Someone with access to the key can use it to push code to the repositories you use to manage your infrastructure. + + + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to the Azure DevOps Services domain. The following example uses the `ssh-keygen` command to create a `service_terraform` file with the private key and a `service_terraform.pub` file with the public key: + + ```shell-session + $ ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise" + ``` + + + + The passphrase for the SSH key must be empty. HCP Terraform cannot use SSH keys that require a passphrase. + + + +2. Log into the Azure DevOps Services account you want HCP Terraform to act as and navigate to the **SSH Keys** settings page. + +3. Add a new SSH key and paste the value of the SSH public key you just created. + +4. In HCP Terraform's **Add VCS Provider** page, paste the text of the **SSH private key** you just created, and click the **Add SSH Key** button. + +## Next steps + +Azure DevOps Services access for HCP Terraform is fully configured. You can create Terraform workspaces based on your organization's repositories. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx index 959b1c6208..023a60d8b7 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/azure-devops-services.mdx @@ -1,12 +1,14 @@ --- -page_title: Set up the Azure DevOps Services VCS provider +page_title: Set up the Azure DevOps Services VCS provider using OAuth description: >- Learn how to use Azure DevOps Services with workspaces and private registry - modules in Terraform Enterprise. + modules in Terraform Enterprise using OAuth. source: terraform-docs-common --- -# Set up the Azure DevOps Services VCS provider +# Set up the Azure DevOps Services VCS provider using OAuth + +~> **Important:** Starting April 2025, Microsoft will no longer allow new Azure DevOps OAuth app registrations—see the [official announcement](https://devblogs.microsoft.com/devops/no-new-azure-devops-oauth-apps-beginning-february-2025/) for details. Until [Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) support is shipped in HCP Terraform, we recommend using [personal access tokens](/terraform/enterprise/vcs/azure-devops-services-pat). These instructions are for using `dev.azure.com` for HCP Terraform's VCS features. [Other supported VCS providers](/terraform/enterprise/vcs) have separate instructions. @@ -104,7 +106,7 @@ The settings in this section are optional. The Advanced Settings you can configu ### If You Need to Limit the Scope of this VCS Provider: -1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. +1. Select the **Selected Projects** option and use the text field that appears to search for and select projects to enable. All current and future workspaces for any selected projects can use repositories from this VCS Provider. 2. Click the **Update VCS Provider** button to save your selections. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx index 24d13c9886..7951e3e2d7 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/bitbucket-data-center.mdx @@ -106,7 +106,7 @@ Do not specify a passphrase because Terraform cannot use SSH keys that require a In the following steps, you must provide HCP Terraform with the private SSH key you created in [Create an SSH key for Terraform](#create-an-ssh-key-for-terraform). Although HCP Terraform does not display the text of the key to users after it is entered, it retains the key and uses it for authenticating to Bitbucket Data Center. 1. If you are logged into Bitbucket Data Center as an administrator, log out before proceeding. -2. Log in with the account that you want to enable HCP Terraform or Terraform Enterprise to log in with. Many organizations use a dedicated service user account for this purpose. The account you use for connecting HCP Terraform must have admin access to any shared repositories of Terraform configurations because since creating webhooks requires admin permissions. Refer to [Requirements](#requirements) for additional information. +2. Log in with the Bitbucket account that you want to use for HCP Terraform or Terraform Enterprise. Many organizations use a dedicated service user account for this purpose. Because creating webhooks requires admin permissions, the account must have admin access to any shared repositories of Terraform configurations. Refer to [Requirements](#requirements) for more information. 3. Open the **SSH keys** page and click the profile icon. 4. Choose **Manage account**. 5. Click **SSH keys** or enter `https:///plugins/servlet/ssh/account/keys` in the address bar to go to the **SSH keys** screen. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/index.mdx index bf7668e7c2..4b1c37c0c5 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/vcs/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/vcs/index.mdx @@ -39,7 +39,8 @@ HCP Terraform supports the following VCS providers: - [Bitbucket Cloud](/terraform/enterprise/vcs/bitbucket-cloud) - [Bitbucket Data Center](/terraform/enterprise/vcs/bitbucket-data-center) - [Azure DevOps Server](/terraform/enterprise/vcs/azure-devops-server) -- [Azure DevOps Services](/terraform/enterprise/vcs/azure-devops-services) +- [Azure DevOps Services (OAuth)](/terraform/enterprise/vcs/azure-devops-services) +- [Azure DevOps Services (PAT)](/terraform/enterprise/vcs/azure-devops-services-pat) Use the links above to see details on configuring VCS access for each supported provider. If you use another VCS that is not supported, you can build an integration via [the API-driven run workflow](/terraform/enterprise/run/api). @@ -123,14 +124,10 @@ You can use self-hosted HCP Terraform Agents to connect HCP Terraform to your pr -## Configure a VCS host for Terraform Enterprise - -You can configure Terraform Enterprise to be accessible over a primary and a secondary hostname so that you can federate workloads associated with your VCS. Refer to [Specify integration setttings](/terraform/enterprise/deploy/configuration/network#specify-integration-settings) for additional information. - -You must set up new VCS connections any time you update the VCS host configuration. When the VCS integration uses the secondary hostname, you should continue using it while setting up the new VCS connection. When setup is complete, you can use the primary hostname for all other activities. Refer to [`TFE_VCS_HOSTNAME_CHOICE` ](/terraform/enterprise/deploy/reference/configuration#tfe_vcs_hostname_choice) in the configuration reference for additional information. - ## Viewing events +-> **Note**: The VCS Events page is still in beta as support is being added for additional VCS providers. Currently only GitLab.com connections established after December 2020 are supported. + VCS events describe changes within your organization for VCS-related actions. The VCS events page only displays events from previously processed commits in the past 30 days. The VCS page indicates previously processed commits with the message, `"Processing skipped for duplicate commit SHA"`. Viewing VCS events requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/best-practices.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/best-practices.mdx index 648d24569e..a2d44d71e7 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/best-practices.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/best-practices.mdx @@ -54,7 +54,11 @@ HCP Terraform and Terraform Enterprise execute workloads using agents. Every tim ## Determine workspace concurrency vs Terraform parallelism -Concurrency refers to the number of plan and apply operations HCP Terraform or Terraform Enterprise can run simultaneously. In HCP Terraform, your subscription limits the maximum concurrency. Terraform Enterprise lets you configure the concurrency, but defaults to 10 concurrent runs. As you increase concurrency, the amount of memory your Terraform Enterprise installation requires increases as well. Refer to the [Capacity and performance](/terraform/enterprise/replicated/architecture/system-overview/capacity) documentation for more information. +Concurrency refers to the number of plan and apply operations that HCP Terraform or Terraform Enterprise can run simultaneously. + +In HCP Terraform, your edition limits the maximum concurrency for your organization. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing?product_intent=terraform) for details. + +Terraform Enterprise lets you configure the concurrency, but defaults to 10 concurrent runs. As you increase concurrency, the amount of memory your Terraform Enterprise installation requires increases as well. Refer to the [Capacity and performance](/terraform/enterprise/replicated/architecture/system-overview/capacity) documentation for more information. Parallelism refers to the number of tasks the Terraform CLI performs simultaneously in a single workload. By default, Terraform performs a maximum of 10 operations in parallel. When running a `terraform apply` command, Terraform refreshes each resource in the state file and compares to the remote object. Every resource refresh, creation, update, or destruction is an individual operation. If your workload creates 11 resources, Terraform starts by creating the first 10 resources in its dependency graph, and will begin creating the 11th once it finishes creating one of the first 10 resources. diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/index.mdx index 61267c1f5b..2c2f763bec 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/index.mdx @@ -70,11 +70,11 @@ In Terraform Enterprise, administrators can use [Admin Settings](/terraform/ente ## Organize Workspaces with Projects -Projects let you organize your workspaces into groups. +Projects let you organize your workspaces into groups. --> **Note:** On HCP Terraform **Standard** Edition, you can assign project permissions to scope access to collections of workspaces based on business units and responsibilities. Refer to [HCP Terraform pricing](https://www.hashicorp.com/products/terraform/pricing) for details. +@include 'tfc-package-callouts/project-workspaces.mdx' diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/access.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/access.mdx index 8fd6acdce7..abad3a8b0e 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/access.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/access.mdx @@ -10,7 +10,7 @@ source: terraform-docs-common --> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). +@include 'tfc-package-callouts/team-management.mdx' @@ -49,6 +49,6 @@ HCP Terraform displays the teams you can grant workspace access to. Select a tea There are four [fixed permissions sets](/terraform/enterprise/users-teams-organizations/permissions#fixed-permission-sets) available for basic usage: Read, Plan, Write, and Admin. -To enable finer-grained selection of non-admin permissions, select "Customize permissions for this team". On this screen, you can select specific permissions to grant the team for the workspace. +To enable finer-grained selection of non-admin permissions, select "Customize permissions for this team". On this screen, you can select specific permissions to grant the team for the workspace. For more information on permissions, see [the documentation on Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/index.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/index.mdx index e57f67d8f4..0dc4c0ab9c 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/index.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/index.mdx @@ -84,10 +84,11 @@ To minimize the number of runs that error when changing your workspace's executi Whether or not HCP Terraform should automatically apply a successful Terraform plan. If you choose manual apply, an operator must confirm a successful plan and choose to apply it. -The main auto-apply setting affects runs created by the HCP Terraform user interface, API, CLI, and version control webhooks. HCP Terraform also has a separate setting for runs created by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) from another workspace. +The main auto-apply setting affects runs created by the HCP Terraform user interface, API, and version control webhooks. HCP Terraform also has a separate setting for runs created by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) from another workspace. -Auto-apply has the following exception: +Auto-apply has the following exceptions: +- Runs created by the terraform CLI must use the `-auto-approve` argument flag to control auto-apply of a particular run. - Plans queued by users without permission to apply runs for the workspace must be approved by a user who does have permission. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) [permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx index 5831610aa2..baab7caf6e 100644 --- a/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx +++ b/content/ptfe-releases/v202504-1/docs/enterprise/workspaces/settings/run-tasks.mdx @@ -32,9 +32,9 @@ You can manage run tasks through the HCP Terraform UI or the [Run Tasks API](/te ## Creating a Run Task -Explore the full list of [run tasks in the Terraform Registry](https://registry.terraform.io/browse/run-tasks). +Explore the full list of [run tasks in the Terraform Registry](https://registry.terraform.io/browse/run-tasks). -Run tasks send an API payload to an external service. The API payload contains run-related information, including a callback URL, which the service uses to return a pass or fail status to HCP Terraform. +Run tasks send an API payload to an external service. The API payload contains run-related information, including a callback URL, which the service uses to return a pass or fail status to HCP Terraform. For example, the [HCP Packer integration](/terraform/enterprise/integrations/run-tasks#hcp-packer-run-task) checks image artifacts within a Terraform configuration for validity. If the configuration references images marked as unusable (revoked), then the run task fails and provides an error message. @@ -54,7 +54,12 @@ To create a new run task: - **Description** (optional): A human-readable description for the run task. This information can contain letters, numbers, spaces, and special characters. - **HMAC key** (optional): A secret key that may be required by the external service to verify request authenticity. -5. Click **Create run task**. The run task is now available within the organization, and you can associate it with one or more workspaces. +5. Select a **Source**: + + - **Managed** HCP Terraform's infrastructure initiates run task requests. This is the default option. + - **Agent** HCP Terraform can initiate run task requests within your self-managed HCP Terraform agents to let run tasks communicate with isolated, private, or on-premises infrastructure. To use this option, an HCP Terraform agent in the agent pool must have [request forwarding](/terraform/cloud-docs/agents/request-forwarding) enabled, and you must be on the [HCP Terraform **Premium** edition](https://www.hashicorp.com/products/terraform/pricing). + +6. Click **Create run task**. The run task is now available within the organization, and you can associate it with one or more workspaces. ### Global Run Tasks