diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/_template.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/_template.mdx new file mode 100644 index 0000000000..94c74253f0 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/_template.mdx @@ -0,0 +1,222 @@ +--- +page_title: /example-endpoint API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/endpoint-name` to {A meaningful + description of this endpoint}. Aim for 130-160 characters total. +source: terraform-docs-common +--- + +Follow this template to format each API method. There are usually multiple sections like this on a given API endpoint page. + + + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: http://jsonapi.org/format/#error-objects + +# Example name API reference + +A explanatory sentence about what this thing in HCP Terraform does. + +## Create a Something + +Add at least one sentence of description about what this endpoint does. + + + +`POST /organizations/:organization_name/somethings` + + + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create the something in. The organization must already exist in the system, and the user must have permissions to create new somethings. | + + + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + + + +| Status | Response | Reason | +| ------- | -------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "somethings"`) | Successfully created a team | +| [400][] | [JSON API error object][] | Invalid `include` parameter | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during team creation | + + + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + + + +| Parameter | Description | +| ----------------------- | ------------------------------------------------------------- | +| `filter[workspace][id]` | **Required.** The workspace ID where this action will happen. | + + + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + + + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"somethings"`. | +| `data[].type` | string | | ... | +| `data.attributes.category` | string | | Whether this is a blue or red something. Valid values are `"blue"` or `"red"`. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the something is written once and not visible thereafter. | +| `filter.workspace.name` | string | | The name of the workspace that owns the something. | +| `filter.organization.name` | string | | The name of the organization that owns the workspace. | + + + +### Available Related Resources + + + +This GET endpoint can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------------ | --------------------------------------------- | +| `organization` | The full organization record. | +| `current_run` | Additional information about the current run. | +| `current_run.plan` | The plan used in the current run. | + +### Sample Payload + +```json +{ + "data": { + "type":"somethings", + "attributes": { + "category":"red", + "sensitive":true + } + }, + "filter": { + "organization": { + "name":"my-organization" + }, + "workspace": { + "name":"my-workspace" + } + } +} +``` + +### 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/somethings +``` + + + +### Sample Response + +```json +{ + "data": { + "id":"som-EavQ1LztoRTQHSNT", + "type":"somethings", + "attributes": { + "sensitive":true, + "category":"red", + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/somethings/som-EavQ1LztoRTQHSNT" + } + } +} +``` + + diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/account.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/account.mdx new file mode 100644 index 0000000000..570770ef0d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/account.mdx @@ -0,0 +1,278 @@ +--- +page_title: /account API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/account` endpoint to manage the current + user. Learn how to read and update your account's details and change your + password. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Account API reference + +Account represents the current user interacting with Terraform. It returns the same type of object as the [Users](/terraform/enterprise/api-docs/users) API, but also includes an email address, which is hidden when viewing info about other users. + +For internal reasons, HCP Terraform associates team and organization tokens with a synthetic user account called _service user_. HCP Terraform returns the associated service user for account requests authenticated by a team or organization token. Use the `authenticated-resource` relationship to access the underlying team or organization associated with a token. For user tokens, you can use the user, itself. + +## Get your account details + +`GET /account/details` + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | The request was successful | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/account/details +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "tfc", + "avatar-url": "https://www.gravatar.com/avatar/9babb00091b97b9ce9538c45807fd35f?s=100&d=mm", + "v2-only": false, + "is-site-admin": true, + "is-sso-login": false, + "email": "admin@hashicorp.com", + "unconfirmed-email": null, + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN/authentication-tokens" + } + }, + "authenticated-resource": { + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } + }, + "links": { + "self": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } +} +``` + +## Update your account info + +Your username and email address can be updated with this endpoint. + +`PATCH /account/update` + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Your info was successfully updated | +| [401][] | [JSON API error object][] | Unauthorized | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | --------------------------------------------------------------- | +| `data.type` | string | | Must be `"users"` | +| `data.attributes.username` | string | | New username | +| `data.attributes.email` | string | | New email address (must be confirmed afterwards to take effect) | + +### Sample Payload + +```json +{ + "data": { + "type": "users", + "attributes": { + "email": "admin@example.com", + "username": "admin" + } + } +} +``` + +### 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/account/update +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "hcp_username_password", + "avatar-url": "https://www.gravatar.com/avatar/9babb00091b97b9ce9538c45807fd35f?s=100&d=mm", + "v2-only": false, + "is-site-admin": true, + "is-sso-login": false, + "email": "admin@hashicorp.com", + "unconfirmed-email": null, + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } +} +``` + +## Change your password + +`PATCH /account/password` + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "users"`) | Your password was successfully changed | +| [401][] | [JSON API error object][] | Unauthorized | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------------------------------------- | ------ | ------- | ------------------------------------------------------- | +| `data.type` | string | | Must be `"users"` | +| `data.attributes.current_password` | string | | Current password | +| `data.attributes.password` | string | | New password (must be at least 10 characters in length) | +| `data.attributes.password_confirmation` | string | | New password (confirmation) | + +### Sample Payload + +```json +{ + "data": { + "type": "users", + "attributes": { + "current_password": "current password e.g. 2:C)e'G4{D\n06:[d1~y", + "password": "new password e.g. 34rk492+jgLL0@xhfyisj", + "password_confirmation": "new password e.g. 34rk492+jLL0@xhfyisj" + } + } +} +``` + +### 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/account/password +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-V3R563qtJNcExAkN", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "hcp_github", + "avatar-url": "https://www.gravatar.com/avatar/9babb00091b97b9ce9538c45807fd35f?s=100&d=mm", + "v2-only": false, + "is-site-admin": true, + "is-sso-login": false, + "email": "admin@hashicorp.com", + "unconfirmed-email": null, + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-V3R563qtJNcExAkN/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-V3R563qtJNcExAkN" + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/agent-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/agent-tokens.mdx new file mode 100644 index 0000000000..e1d27c1395 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/agent-tokens.mdx @@ -0,0 +1,272 @@ +--- +page_title: /authentication-tokens API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/authentication-tokens` endpoint to manage + agent tokens. Learn how to read, create, and destroy agent tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Agent token API reference + + + +@include 'tfc-package-callouts/agents.mdx' + + + +## List Agent Tokens + +`GET /agent-pools/:agent_pool_id/authentication-tokens` + +| Parameter | Description | +| ---------------- | ------------------------- | +| `:agent_pool_id` | The ID of the Agent Pool. | + +The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 tokens per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "at-bonpPzYqv2bGD7vr", + "type": "authentication-tokens", + "attributes": { + "created-at": "2020-08-07T19:38:20.868Z", + "last-used-at": "2020-08-07T19:40:55.139Z", + "description": "asdfsdf", + "token": null + }, + "relationships": { + "created-by": { + "data": { + "id": "user-Nxv6svuhVrTW7eb1", + "type": "users" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd/authentication-tokens?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show an Agent Token + +`GET /authentication-tokens/:id` + +| Parameter | Description | +| --------- | --------------------------------- | +| `:id` | The ID of the Agent Token to show | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | Success | +| [404][] | [JSON API error object][] | Agent Token not found, or user unauthorized to perform action | + +### 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-bonpPzYqv2bGD7vr +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-bonpPzYqv2bGD7vr", + "type": "authentication-tokens", + "attributes": { + "created-at": "2020-08-07T19:38:20.868Z", + "last-used-at": "2020-08-07T19:40:55.139Z", + "description": "test token", + "token": null + }, + "relationships": { + "created-by": { + "data": { + "id": "user-Nxv6svuhVrTW7eb1", + "type": "users" + } + } + } + } +} +``` + +## Create an Agent Token + +`POST /agent-pools/:agent_pool_id/authentication-tokens` + +| Parameter | Description | +| ---------------- | ------------------------ | +| `:agent_pool_id` | The ID of the Agent Pool | + +This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | Agent Pool not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during Agent Token creation | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ------------------------------------ | +| `data.type` | string | | Must be `"authentication-tokens"`. | +| `data.attributes.description` | string | | The description for the Agent Token. | + +### Sample Payload + +```json +{ + "data": { + "type": "authentication-tokens", + "attributes": { + "description":"api" + } + } +} +``` + +### 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/agent-pools/apool-xkuMi7x4LsEnBUdY/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-2rG2oYU9JEvfaqji", + "type": "authentication-tokens", + "attributes": { + "created-at": "2020-08-10T22:29:21.907Z", + "last-used-at": null, + "description": "api", + "token": "eHub7TsW7fz7LQ.atlasv1.cHGFcvf2VxVfUH4PZ7UNdaGB6SjyKWs5phdZ371zkI2KniZs2qKgrAcazhlsiy02awk" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-Nxv6svuhVrTW7eb1", + "type": "users" + } + } + } + } +} +``` + +## Destroy an Agent Token + +`DELETE /api/v2/authentication-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------------------- | +| `:id` | The ID of the Agent Token to destroy. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | Empty response | The Agent Token was successfully destroyed | +| [404][] | [JSON API error object][] | Agent Token not found, or user unauthorized to perform action | + +### 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 +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/agents.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/agents.mdx new file mode 100644 index 0000000000..58acfa2aad --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/agents.mdx @@ -0,0 +1,637 @@ +--- +page_title: /agents and /agent-pools API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/agents` endpoint to read and delete + agents. Use the `/agent-pools` endpoint to read, create, update, and delete + agent pools. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Agents and agent pools API reference + +An Agent Pool represents a group of Agents, often related to one another by sharing a common network segment or purpose. +A workspace may be configured to use one of the organization's agent pools to run remote operations with isolated, +private, or on-premises infrastructure. + + + +@include 'tfc-package-callouts/agents.mdx' + + + +## List Agent Pools + +`GET /organizations/:organization_name/agent-pools` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:organization_name` | The name of the organization. | + +This endpoint allows you to list agent pools, their agents, and their tokens for an organization. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ---------------------- | +| [200][] | [JSON API document][] (`type: "agent-pools"`) | Success | +| [404][] | [JSON API error object][] | Organization not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | +| `q` | **Optional.** A search query string. Agent pools are searchable by name. | | +| `sort` | **Optional.** Allows sorting the returned agents pools. Valid values are `"name"` and `"created-at"`. Prepending a hyphen to the sort parameter will reverse the order (e.g. `"-name"`). | | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agent pools per page. | | +| `filter[allowed_workspaces][name]` | **Optional.** Filters agent pools to those associated with the given workspace. The workspace must have permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). | | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/agent-pools +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "created-at": "2020-08-05T18:10:26.964Z", + "organization-scoped": false, + "agent-count": 3 + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-9EEkcEQSA3XgWyGe", + "type": "workspaces" + } + ] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/agent-pools?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + }, + "status-counts": { + "total": 1, + "matching": 1 + } + } +} +``` + +## List Agents + +`GET /agent-pools/:agent_pool_id/agents` + +| Parameter | Description | +| ---------------- | --------------------------------- | +| `:agent_pool_id` | The ID of the Agent Pool to list. | + +| Status | Response | Reason | +| ------- | ---------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "agents"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------------------------- | +| `filter[last-ping-since]` | **Optional.** Accepts a date in ISO8601 format (ex. `2020-08-11T10:41:23Z`). | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 agents per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agent-pools/apool-xkuMi7x4LsEnBUdY/agents +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "agent-A726QeosTCpCumAs", + "type": "agents", + "attributes": { + "name": "my-cool-agent", + "status": "idle", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-10-09T18:52:25.246Z" + }, + "links": { + "self": "/api/v2/agents/agent-A726QeosTCpCumAs" + } + }, + { + "id": "agent-4cQzjbr1cnM6Pcxr", + "type": "agents", + "attributes": { + "name": "my-other-cool-agent", + "status": "exited", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-08-12T15:25:09.726Z" + }, + "links": { + "self": "/api/v2/agents/agent-4cQzjbr1cnM6Pcxr" + } + }, + { + "id": "agent-yEJjXQCucpNxtxd2", + "type": "agents", + "attributes": { + "name": null, + "status": "errored", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-08-11T06:22:20.300Z" + }, + "links": { + "self": "/api/v2/agents/agent-yEJjXQCucpNxtxd2" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 3 + } + } +} +``` + +## Show an Agent Pool + +`GET /agent-pools/:id` + +| Parameter | Description | +| --------- | -------------------------------- | +| `:id` | The ID of the Agent Pool to show | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "agent-pools"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd +``` + +### Sample Response + +```json +{ + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "created-at": "2020-08-05T18:10:26.964Z", + "organization-scoped": false + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-9EEkcEQSA3XgWyGe", + "type": "workspaces" + } + ] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i" + } + } +} +``` + +## Show an Agent + +`GET /agents/:id` + +| Parameter | Description | +| --------- | --------------------------- | +| `:id` | The ID of the agent to show | + +| Status | Response | Reason | +| ------- | ---------------------------------------- | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "agents"`) | Success | +| [404][] | [JSON API error object][] | Agent not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ +``` + +### Sample Response + +```json +{ + "data": { + "id": "agent-Zz9PTEcUgBtYzht8", + "type": "agents", + "attributes": { + "name": "my-agent", + "status": "busy", + "ip-address": "123.123.123.123", + "last-ping-at": "2020-09-08T18:47:35.361Z" + }, + "links": { + "self": "/api/v2/agents/agent-Zz9PTEcUgBtYzht8" + } + } +} +``` + +This endpoint lists details about an agent along with that agent's status. [Learn more about agents statuses](/terraform/cloud-docs/agents/agent-pools#view-agent-statuses). + +## Delete an Agent + +`DELETE /agents/:id` + +| Parameter | Description | +| --------- | ----------------------------- | +| `:id` | The ID of the agent to delete | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ | +| [204][] | No Content | Success | +| [412][] | [JSON API error object][] | Agent is not deletable. Agents must have a status of `unknown`, `errored`, or `exited` before being deleted. | +| [404][] | [JSON API error object][] | Agent not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --request DELETE \ + https://app.terraform.io/api/v2/agents/agent-73PJNzbZB5idR7AQ +``` + +## Create an Agent Pool + +`POST /organizations/:organization_name/agent-pools` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:organization_name` | The name of the organization. | + +This endpoint allows you to create an Agent Pool for an organization. Only one Agent Pool may exist for an organization. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "agent-pools"`) | Agent Pool successfully created | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"agent-pools"`. | +| `data.attributes.name` | string | | The name of the agent pool, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. | +| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). | + +### Sample Payload + +```json +{ + "data": { + "type": "agent-pools", + "attributes": { + "name": "my-pool", + "organization-scoped": false + }, + "relationships": { + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + } + } +} +``` + +### 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/organizations/my-organization/agent-pools +``` + +### Sample Response + +```json +{ + "data": { + "id": "apool-55jZekR57npjHHYQ", + "type": "agent-pools", + "attributes": { + "name": "my-pool", + "created-at": "2020-10-13T16:32:45.165Z", + "organization-scoped": false, + + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ/authentication-tokens" + } + }, + "workspaces": { + "data": [] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-55jZekR57npjHHYQ" + } + } +} +``` + +## Update an Agent Pool + +`PATCH /agent-pools/:id` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `:id` | The ID of the Agent Pool to update | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "agent-pools"`) | Success | +| [404][] | [JSON API error object][] | Agent Pool not found, or user unauthorized to perform action | +| [422][] | JSON error document | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"agent-pools"`. | +| `data.attributes.name` | string | (previous value) | The name of the agent pool, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.organization-scoped` | bool | true | The scope of the agent pool. If true, all workspaces in the organization can use the agent pool. | +| `data.relationships.allowed-workspaces.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.allowed-workspaces.data.id` | string | | The ID of the workspace that has permission to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). | + +### Sample Payload + +```json +{ + "data": { + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "organization-scoped": false + }, + "relationships": { + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + } + } +} +``` + +### 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/agent-pools/apool-MCf6kkxu5FyHbqhd +``` + +### Sample Response + +```json +{ + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools", + "attributes": { + "name": "example-pool", + "created-at": "2020-08-05T18:10:26.964Z" + }, + "relationships": { + "agents": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/agents" + } + }, + "authentication-tokens": { + "links": { + "related": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i/authentication-tokens" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-9EEkcEQSA3XgWyGe", + "type": "workspaces" + } + ] + }, + "allowed-workspaces": { + "data": [ + { + "id": "ws-x9taqV23mxrGcDrn", + "type": "workspaces" + } + ] + } + }, + "links": { + "self": "/api/v2/agent-pools/apool-yoGUFz5zcRMMz53i" + } + } +} +``` + +## Delete an Agent Pool + +`DELETE /agent-pools/:agent_pool_id` + +| Parameter | Description | +| ---------------- | ------------------------------------- | +| `:agent_pool_id` | The ID of the agent pool ID to delete | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/agent-pools/apool-MCf6kkxu5FyHbqhd +``` + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | ------------------------------------------- | +| `workspaces` | The workspaces attached to this agent pool. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/applies.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/applies.mdx new file mode 100644 index 0000000000..a124bf588c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/applies.mdx @@ -0,0 +1,201 @@ +--- +page_title: /applies API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/applies` endpoint to read the results of + a Terraform apply and to recover any failed state uploads after applying. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[307]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Applies API reference + +An apply represents the results of applying a Terraform Run's execution plan. + +## Attributes + +### Apply States + +You'll find the apply state in `data.attributes.status`, as one of the following values. + +| State | Description | +| ------------------------- | ------------------------------------------------------------------------------ | +| `pending` | The initial status of a apply once it has been created. | +| `managed_queued`/`queued` | The apply has been queued, awaiting backend service capacity to run terraform. | +| `running` | The apply is running. | +| `errored` | The apply has errored. This is a final state. | +| `canceled` | The apply has been canceled. This is a final state. | +| `finished` | The apply has completed successfully. This is a final state. | +| `unreachable` | The apply will not run. This is a final state. | + +## Show an apply + +`GET /applies/:id` + +| Parameter | Description | +| --------- | ---------------------------- | +| `id` | The ID of the apply to show. | + +There is no endpoint to list applies. You can find the ID for an apply in the +`relationships.apply` property of a run object. + +| Status | Response | Reason | +| ------- | ----------------------------------------- | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "applies"`) | The request was successful | +| [404][] | [JSON API error object][] | Apply not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v +``` + +### Sample Response + +```json +{ + "data": { + "id": "apply-47MBvjwzBG8YKc2v", + "type": "applies", + "attributes": { + "execution-details": { + "mode": "remote", + }, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-10-17T18:58:27+00:00", + "started-at": "2018-10-17T18:58:29+00:00", + "finished-at": "2018-10-17T18:58:37+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg", + "resource-additions": 1, + "resource-changes": 0, + "resource-destructions": 0, + "resource-imports": 0 + }, + "relationships": { + "state-versions": { + "data": [ + { + "id": "sv-TpnsuD3iewwsfeRD", + "type": "state-versions" + }, + { + "id": "sv-Fu1n6a3TgJ1Typq9", + "type": "state-versions" + } + ] + } + }, + "links": { + "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v" + } + } +} +``` + +_Using HCP Terraform agents_ + +[HCP Terraform agents](/terraform/enterprise/api-docs/agents) allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the apply response will include additional details about the agent pool and agent used. + +```json +{ + "data": { + "id": "apply-47MBvjwzBG8YKc2v", + "type": "applies", + "attributes": { + "execution-details": { + "agent-id": "agent-S1Y7tcKxXPJDQAvq", + "agent-name": "agent_01", + "agent-pool-id": "apool-Zigq2VGreKq7nwph", + "agent-pool-name": "first-pool", + "mode": "agent", + }, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-10-17T18:58:27+00:00", + "started-at": "2018-10-17T18:58:29+00:00", + "finished-at": "2018-10-17T18:58:37+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg", + "resource-additions": 1, + "resource-changes": 0, + "resource-destructions": 0, + "resource-imports": 0 + }, + "relationships": { + "state-versions": { + "data": [ + { + "id": "sv-TpnsuD3iewwsfeRD", + "type": "state-versions" + }, + { + "id": "sv-Fu1n6a3TgJ1Typq9", + "type": "state-versions" + } + ] + } + }, + "links": { + "self": "/api/v2/applies/apply-47MBvjwzBG8YKc2v" + } + } +} +``` + +## Recover a failed state upload after applying + +`GET /applies/:id/errored-state` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `id` | The ID of the apply to recover state for. | + +It is possible that during the course of a Run, Terraform may fail to upload a +state file. This can happen for a variety of reasons, but should be an +exceptionally rare occurrence. HCP Terraform agent versions greater than 1.12.0 +include a fallback mechanism which attempts to upload the state directly to +HCP Terraform's backend storage system in these cases. This endpoint then +makes the raw data from these failed uploads available to users who are +authorized to read the state contents. + +| Status | Response | Reason | +| ------- | -------------------------------------------- | ----------------------------------------------------------------------------------- | +| [307][] | HTTP temporary redirect to state storage URL | Errored state available and user is authorized to read it | +| [404][] | [JSON API error object][] | Apply not found, errored state not uploaded, or user unauthorized to perform action | + +When a 307 redirect is returned, the storage URL to the raw state file will be +present in the `Location` header of the response. The URL in the `Location` +header will expire after one minute. It is recommended for the API client to +follow the redirect immediately. Each successful request to the errored-state +endpoint will generate a new, unique storage URL with the same one minute +expiration window. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/applies/apply-47MBvjwzBG8YKc2v/errored-state +``` + +### Sample Response + + HTTP/1.1 307 Temporary Redirect + Content-Length: 22 + Content-Type: text/plain + Location: https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg + + 307 Temporary Redirect diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/assessment-results.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/assessment-results.mdx new file mode 100644 index 0000000000..6ce07a2eda --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/assessment-results.mdx @@ -0,0 +1,129 @@ +--- +page_title: /assessment-results API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/assessment-results` endpoint to read a + health assessment's results, including details on continuous validation and + drift detection. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +# Health assessment results API reference + +An Assessment Result is the summary record of an instance of health assessment. HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Refer to [Health](/terraform/enterprise/workspaces/health) for more details. + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +## Show Assessment Result + +Any user with read access to a workspace can retrieve assessment results for the workspace. + +`GET api/v2/assessment-results/:assessment_result_id` + +| Parameter | Description | +| ----------------------- | ------------------------ | +| `:assessment_result_id` | The assessment result ID | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm +``` + +### Sample Response + +```json +{ + "id": "asmtres-UG5rE9L1373hMYMA", + "type": "assessment-results", + "data": { + "attributes": { + "drifted": true, + "succeeded": true, + "error-msg": null, + "created-at": "2022-07-02T22:29:58+00:00", + }, + "links": { + "self": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/" + "json-output": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/json-output" + "json-schema": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/json-schema" + "log-output": "/api/v2/assessment-results/asmtres-UG5rE9L1373hMYMA/log-output" + } + } +} +``` + +## Retrieve the JSON output from the assessment execution + +The following endpoints retrieve files documenting the plan, schema, and logged runtime associated with the specified assessment result. They provide complete context for an assessment result. The responses do not adhere to JSON API spec. + +You cannot access these endpoints with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access them with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) that has admin level access to the workspace. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### JSON Plan + +The following endpoint returns the JSON plan output associated with the assessment result. + +`GET api/v2/assessment-results/:assessment_result_id/json-output` + +#### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/json-output +``` + +### JSON Schema file + +The following endpoint returns the JSON [provider schema](/terraform/cli/commands/providers/schema) associated with the assessment result. + +`GET api/v2/assessment-results/:assessment_result_id/json-schema` + +#### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/json-schema +``` + +### JSON Log Output + +The following endpoint returns Terraform JSON log output. + +`GET api/v2/assessment-results/assessment_result_id/log-output` + +#### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/assessment-results/asmtres-cHh5777xm/log-output +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/changelog.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/changelog.mdx new file mode 100644 index 0000000000..7cda177f5a --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/changelog.mdx @@ -0,0 +1,578 @@ +--- +page_title: API Changelog for Terraform Enterprise +page_id: api-changelog +description: >- + Use this log of Terraform Enterprise API changes to track new features and + evolving functionality over time. +source: terraform-docs-common +--- + +# API Changelog + +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. + +## 2024-11-19 + +- Clarify `tag-bindings` and `effective-tag-bindings` on [workspaces](/terraform/enterprise/api-docs/workspaces) and [projects](/terraform/enterprise/api-docs/projects) +- Adds new documentation for `PATCH`ing tag bindings on [projects](/terraform/enterprise/api-docs/projects) and [workspaces](/terraform/enterprise/api-docs/workspaces) + +## 2024-10-15 + +- Add new documentation for the ability to deprecate, and revert the deprecation of, module versions. Learn more about [Managing module versions](/terraform/enterprise/api-docs/private-registry/manage-module-versions). + +## 2024-10-14 + +- Update the [Organizations API](/terraform/enterprise/api-docs/organizations) to support the `speculative-plan-management-enabled` attribute, which controls [automatic cancellation of plan-only runs triggered by outdated commits](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management). + +## 2024-10-11 + +- Add documentation for new timeframe filter on List endpoints for [Runs](/terraform/enterprise/api-docs/run) API + +## 2024-09-02 + +- Add warning about the deprecation and future removal of the [Policy Checks](/terraform/enterprise/api-docs/policy-checks) API. + +## 2024-08-16 + +- Fixes Workspace API responses to be consistent and contain all attributes and relationships. + +## 2024-08-14 + +- Add documentation for a new API endpoint that lists an [organization's team tokens](/terraform/enterprise/api-docs/team-tokens). + +## 2024-08-01 + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. + + +- Update the [admin settings API](/terraform/enterprise/api-docs/admin/settings##update-general-settings) and [admin organizations API](/terraform/enterprise/api-docs/admin/organizations#update-an-organization) to indicate that the `terraform-build-worker-plan-timeout` and `terraform-build-worker-apply-timeout` attributes are deprecated and will be replaced by `plan-timeout` and `apply-timeout`, respectively. + + + +## 2024-07-24 + +- Remove beta tags from documentation for audit trail tokens. + + +## 2024-07-15 + +- Update the [Team API](/terraform/enterprise/api-docs/teams) to include `allow-member-token-management`. + + + +## 2024-07-12 + +- Add beta tags to documentation for audit trail tokens. + + +## 2024-06-25 + +- Add API documentation for new [team token management setting](/terraform/enterprise/users-teams-organizations/api-tokens). +- Update API documentation for the [manage teams permission](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions). + +## 2024-05-29 + +- Add API documentation for the new [audit trails token](/terraform/enterprise/api-docs/audit-trails-tokens). + +## 2024-05-23 + +- Update the [registry modules API](/terraform/enterprise/api-docs/private-registry/modules#create-a-module-version) for publishing new versions of branch based modules. + +## 2024-05-10 + +- Add API documentation for new [manage agent pools permission](/terraform/enterprise/users-teams-organizations/permissions#manage-agent-pools). + +## 2024-04-25 + +- Project names can now be up to 40 characters. + +## 2024-04-08 + +- Add API documentation for new [team management permissions](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions). + +## 2024-04-04 + +- Add a `sort` parameter to the [Projects list API](/terraform/enterprise/api-docs/projects#query-parameters) to allow sorting projects by name. +- Add a `description` attribute to the [Projects API](/terraform/enterprise/api-docs/projects). +- Add `project-count` and `workspace-count` attributes to sample [Projects API](/terraform/enterprise/api-docs/projects) responses. + +## 2024-3-27 + +- Add `private-vcs` to [Feature Entitlements](/terraform/enterprise/api-docs#feature-entitlements). + +## 2024-3-26 + +- Add API documentation for searching [variable sets](/terraform/enterprise/api-docs/variable-sets#list-variable-sets) by name. + +## 2024-3-14 + +- Add documentation for creating runs with debugging mode enabled. + +## 2024-3-12 + +- Update OAuth Client API endpoints to create, update, and return projects associated with an oauth client. +- Add API endpoints to [Attach an OAuth Client](/terraform/enterprise/api-docs/oauth-clients#attach-an-oauth-client-to-projects) and [Detach an OAuth Client](/terraform/enterprise/api-docs/oauth-clients#detach-an-oauth-client-from-projects) from a project. +- Add `organization-scoped` attribute to the [OAuth Clients API](/terraform/enterprise/api-docs/oauth-clients). + +## 2024-2-29 + +- Update [run task stages](/terraform/enterprise/api-docs/run-tasks/run-task-stages-and-results) with new multi-stage payload format. +- Update [run tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) with global run tasks request/response payloads. + +## 2024-2-27 + +- Add `private-policy-agents` to [Feature Entitlements](/terraform/enterprise/api-docs#feature-entitlements). + +## 2024-2-20 + +- Add documentation for configuring organization and workspace data retention policies through the API and on the different [types of data retention policies](/terraform/enterprise/api-docs/data-retention-policies). + + +## 2024-2-8 + +- Add [Explorer API documentation](/terraform/enterprise/api-docs/explorer) + + +## 2024-1-30 + +- Update the [Audit trails](/terraform/enterprise/api-docs/audit-trails) documentation to expand on the payloads for each event. + +## 2024-1-24 + +- Introduce configurable data retention policies at the site-wide level and extend data retention policies at the organization and workspace levels. +- Added and/or updated data retention policy documentation to the following topics: + - [Admin Settings Documentation](/terraform/enterprise/application-administration/general#data-retention-policies) + - [Admin API Documentation](/terraform/enterprise/api-docs/admin/settings#data-retention-policies) + - [Organization Documentation](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) + - [Workspace Documentation](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) + +## 2024-1-4 + +- Update the [Organizations API](/terraform/enterprise/api-docs/organizations) to support the `aggregated-commit-status-enabled` attribute, which controls whether [Aggregated Status Checks](/terraform/enterprise/users-teams-organizations/organizations/vcs-status-checks) are enabled. + +## 2023-11-17 + +- Added the [`opa-versions` endpoint](/terraform/enterprise/api-docs/admin/opa-versions) to allow administrators to manage available Open Policy Agent (OPA) versions. +- Added the [`sentinel-versions` endpoint](/terraform/enterprise/api-docs/admin/sentinel-versions) to allow administrators to manage available Sentinel versions. +- Add `authenticated-resource` relationship to the [`account` API](/terraform/enterprise/api-docs/account). + +## 2023-11-15 + +- Introduce configurable data retention policies at the [organization](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) and [workspace](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) levels. +- Added data retention policy documentation to the following topics: + - [`state-versions` API documentation](/terraform/enterprise/api-docs/state-versions) + - [`configuration-versions` API documentation](/terraform/enterprise/api-docs/configuration-versions) + - [Organizations documentation](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) + - [Workspaces documentation](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) + +## 2023-11-07 + +- Add `auto_destroy_activity_duration` to the [Workspaces API](/terraform/enterprise/api-docs/workspaces), which allows Terraform Cloud to schedule auto-destroy runs [based on workspace inactivity](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). + +## 2023-10-31 + +- Update the [Workspaces API](/terraform/enterprise/api-docs/workspaces) to support the `auto-apply-run-trigger` attribute, which controls if run trigger runs are auto-applied. + +## 2023-10-30 + +- Add `priority` attribute to the [Variable Sets API](/terraform/enterprise/api-docs/variable-sets). + +## 2023-10-04 + +- Updates to [run task integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) + - Fix invalid JSON in the example payload. + - Clarify the expected JSON:API payload fields. +- Add `policy-tool-version` attribute to [Policy Set Outcomes](/terraform/enterprise/api-docs/policy-evaluations#list-policy-outcomes). + +## 2023-10-03 + +- Update [Policy Sets API](/terraform/enterprise/api-docs/policy-sets) to include `agent-enabled` and `policy-tool-version`. +- Update [Policy Evaluations API](/terraform/enterprise/api-docs/policy-evaluations) to include `policy-tool-version`. + +## 2023-09-29 + +- Add support for [streamlined run task reviews](/terraform/enterprise/integrations/run-tasks), enabling run task integrations to return high fidelity results. + - Update the [Terraform cloud run task API](/terraform/enterprise/api-docs/run-tasks/run-tasks) to enable streamlined run task reviews. + - The [run task integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) now guides integrations through sending rich results. + - Updated the run task payload [JSON Schema](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json). + +## 2023-09-25 + +- Add `intermediate` boolean attribute to the [State Versions API](/terraform/enterprise/api-docs/state-versions). + +## 2023-09-19 + +- Add [failed state upload recovery](/terraform/enterprise/api-docs/applies#recover-a-failed-state-upload-after-applying) endpoint. + +## 2023-09-15 + +- Add `auto-destroy-at` attribute to the [Workspaces API](/terraform/enterprise/api-docs/workspaces). +- Update the [Notification Configurations API](/terraform/enterprise/api-docs/notification-configurations) to include [automatic destroy run](/terraform/enterprise/api-docs/notification-configurations#automatic-destroy-runs) details. + +## 2023-09-08 + +- Update the [Organizations API](/terraform/enterprise/api-docs/organizations) to include `default-execution-mode` and `default-agent-pool`. +- Update the [Workspaces API](/terraform/enterprise/api-docs/workspaces) to add a `setting-overwrites` object to allow you to overwrite `default-execution-mode` and `default-agent-pool`. + +## 2023-09-06 + +- Update Policy Sets API endpoints to create, update, and return excluded workspaces associated with a policy set. +- Add API endpoints to [Attach a Policy Set](/terraform/enterprise/api-docs/policy-sets#attach-a-policy-set-to-exclusions) and [Detach a Policy Set](/terraform/enterprise/api-docs/policy-sets#detach-a-policy-set-to-exclusions) from excluded workspaces. + +## 2023-08-21 + +- Add `save-plan` attribute, `planned_and_saved` status, and `save_plan` operation type to [Runs endpoints](/terraform/enterprise/api-docs/run). + +## 2023-08-10 + +- Add `provisional` to `configuration-versions` endpoint. + +## 2023-07-26 + +- Add support for a `custom` option to the `team_project` access level along with various customizable permissions. The `project-access` permissions apply to the project itself, and `workspace-access` permissions apply to all workspaces within the project. For more information, see [Project Team Access](/terraform/enterprise/api-docs/project-team-access). + +## 2023-06-09 + +- Introduce support for [`import` blocks](/terraform/language/import/generating-configuration). + - [Runs](/terraform/enterprise/api-docs/run#create-a-run) have a new `allow-config-generation` option. + - [Plans](/terraform/enterprise/api-docs/plans#show-a-plan) have new `resource-imports` and `generated-configuration` properties. + - [Applies](/terraform/enterprise/api-docs/applies#show-an-apply) have a new `resource-imports` property. +- The workspaces associated with a policy set can now be updated using the [Policy Sets PATCH endpoint](/terraform/enterprise/api-docs/policy-sets#update-a-policy-set) +- Update the [Workspaces](/terraform/enterprise/api-docs/workspaces) API endpoints to include the associated [project](/terraform/enterprise/api-docs/projects). + +## 2023-05-25 + +- Terraform Cloud sets the `configuration_version_download_url`, `configuration_version_id`, and `workspace_working_directory` properties for all stages of the [Run Task Request](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration#request-body). +- Add the new `enforcement-level` property in the request and response of [Policies endpoints](/terraform/enterprise/api-docs/policies). +- Deprecate the old `enforce` property in the request and response of [Policies endpoints](/terraform/enterprise/api-docs/policies). +- Add new properties to limit run tasks and policies for the Terraform Cloud free tier. We updated the [entitlement set](/terraform/enterprise/api-docs/organizations#show-the-entitlement-set), [feature set](/terraform/enterprise/api-docs/feature-sets#sample-response), and [subscription](/terraform/enterprise/api-docs/subscriptions#sample-response) endpoints with the following properties: + - `run-task-limit` + - `run-task-workspace-limit` + - `run-task-mandatory-enforcement-limit` + - `policy-set-limit` + - `policy-limit` + - `policy-mandatory-enforcement-limit` + - `versioned-policy-set-limit` + +## 2023-04-25 + +- Add the `version-id` property to the response for the Create, List, and Update [Workspace Variables endpoints](/terraform/enterprise/api-docs/workspaces-variables). + +## 2023-03-30 + +- Add the `sort` query parameter to the Workspaces API's [list workspaces endpoint](/terraform/enterprise/api-docs/workspaces#list-workspaces). + +## 2023-03-24 + +- Update the [Variable Sets](/terraform/enterprise/api-docs/variable-sets) API endpoints to include assigning variable sets to projects. + +## 2023-03-20 + +- Add a names filter to the [Projects list API](/terraform/enterprise/api-docs/projects#query-parameters) to allow fetching a list of projects by name. + +## 2023-03-13 + +- Update [Project Team Access API](/terraform/enterprise/api-docs/project-team-access) to include additional Project roles. +- Update [Permissions](/terraform/enterprise/users-teams-organizations/permissions) to reflect the decoupling of projects and workspaces in the Organization Permissions UI. + +## 2023-03-08 + +- Introduced the [GitHub App Installation APIs](/terraform/enterprise/api-docs/github-app-installations). +- Updated [Workspaces API](/terraform/enterprise/api-docs/workspaces) to accept `vcs-repo.github-app-installation-id` to connect a workspace to a GitHub App Installation. +- Updated [Registry Module API](/terraform/enterprise/api-docs/private-registry/modules) to accept `vcs-repo.github-app-installation-id` to connect to a GitHub App Installation. +- Updated [Policy Sets API](/terraform/enterprise/api-docs/policy-sets) to accept `vcs-repo.github-app-installation-id` to connect to a GitHub App Installation. + +## 2023-02-16 + +- Add `manage-membership` to the organization access settings of the [Team API](/terraform/enterprise/api-docs/teams). + +## 2023-02-03 + +- Updated the [List Runs API](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace) to note that the filter query parameters accept comma-separated lists. + +## 2023-01-18 + +- Updated the [Team API](/terraform/enterprise/api-docs/teams) to include the `read-workspaces` and `read-projects` permissions which grants teams view access to workspaces and projects. + +## 2023-01-17 + +- Add [Projects API](/terraform/enterprise/api-docs/projects) for creating, updating and deleting projects. +- Add [Project Team Access API](/terraform/enterprise/api-docs/project-team-access) for managing access for teams to individual projects. +- Update [Workspaces API](/terraform/enterprise/api-docs/workspaces) to include examples of creating a workspace in a project and moving a workspace between projects. +- Update [List Teams API](/terraform/enterprise/api-docs/teams#query-parameters) to accept a search parameter `q`, so that teams can be searched by name. + +## 2023-01-12 + +- Added new rollback to previous state endpoint to [State Versions API](/terraform/enterprise/api-docs/state-versions) + +## 2022-12-22 + +- Updated [Safe Delete a workspace](/terraform/enterprise/api-docs/workspaces#safe-delete-a-workspace) to fix HTTP verb as `POST`. + +## 2022-11-18 + +- Update [Policies API](/terraform/enterprise/api-docs/policies) to fix policy enforcement level defaults. Enforcement level is a required field, so no defaults are available. + +## 2022-11-03 + +- Update [Policy Checks](/terraform/enterprise/api-docs/policy-checks) to fix policy set outcome return data type. + +### 2022-10-17 + +- Updated the [Organizations API](/terraform/enterprise/api-docs/organizations) with the `allow-force-delete-workspaces`, which controls whether workspace administrators can delete workspaces with resources under management. +- Updated the [Workspaces API](/terraform/enterprise/api-docs/workspaces) with a safe delete endpoint that guards against deleting workspaces that are managing resources. + +### 2022-10-12 + +- Update [Policy Checks](/terraform/enterprise/api-docs/policy-checks) with result counts and support for filtering policy set outcomes. +- Update [Team Membership API](/terraform/enterprise/api-docs/team-members) to include adding and removing users from teams using organization membership ID. + + + +### 2022-10-06 + +- Updated the [Policies API](/terraform/enterprise/api-docs/policies) with support for Open Policy Agent (OPA) policies. +- Update [Policy Sets](/terraform/enterprise/api-docs/policy-sets) with support for OPA policy sets. +- Updated [Policy Checks](/terraform/enterprise/api-docs/policy-checks) to add support for listing policy evaluations and policy set outcomes. +- Update [Run Tasks Stage](/terraform/enterprise/api-docs/run-tasks/run-task-stages-and-results) to include the new `policy_evaluations` attribute in the output. + + +### 2022-09-21 + +- Update [State Versions](/terraform/enterprise/api-docs/state-versions#create) with optional `json-state-outputs` and `json-state` attributes, which are base-64 encoded external JSON representations of the terraform state. The read-only `hosted-json-state-download-url` attribute links to this version of the state file when available. +- Update [State Version Outputs](/terraform/enterprise/api-docs/state-version-outputs) with a `detailed-type` attribute, which refines the output with the precise Terraform type. + +### 2022-07-26 + +- Updated the [Run status list](/terraform/enterprise/api-docs/run#run-states) with `fetching`, `queuing`, `pre_plan_running` and `pre_plan_completed` +- Update [Run Tasks](/terraform/enterprise/api-docs/run-tasks.mdx) to include the new `stages` attribute when attaching or updating workspace tasks. +- Updated [Run Tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) to specify the different request payloads for different stages. + +### 2022-06-23 + + + +- Added the [Assessments](/terraform/enterprise/api-docs/assessments). + +- Updated [Workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) and + [Notification Configurations](/terraform/enterprise/api-docs/notification-configurations#notification-triggers) to account for assessments. + + +- Added new query parameter(s) to [List Runs endpoint](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace). + +### 2022-06-21 + +- Updated [Admin Organizations](/terraform/enterprise/api-docs/admin/organizations) endpoints with new `workspace-limit` setting. This is available in Terraform Enterprise v202207-1 and later. +- Updated [List Agent Pools](/terraform/enterprise/api-docs/agents#list-agent-pools) to accept a filter parameter `filter[allowed_workspaces][name]` so that agent pools can be filtered by name of an associated workspace. The given workspace must be allowed to use the agent pool. Refer to [Scoping Agent Pools to Specific Workspaces](/terraform/cloud-docs/agents#scope-an-agent-pool-to-specific-workspaces). +- Added new `organization-scoped` attribute and `allowed-workspaces` relationship to the request/response body of the below endpoints. This is available in Terraform Enterprise v202207-1 and later. + - [Show an Agent Pool](/terraform/enterprise/api-docs/agents#show-an-agent-pool) + - [Create an Agent Pool](/terraform/enterprise/api-docs/agents#create-an-agent-pool) + - [Update an Agent Pool](/terraform/enterprise/api-docs/agents#update-an-agent-pool) + +### 2022-06-17 + +- Updated [Creating a Run Task](/terraform/enterprise/workspaces/settings/run-tasks#creating-a-run-task) section to include the new description information for the run task to be configured. +- Update [Run Tasks](/terraform/enterprise/api-docs/run-tasks.mdx) to include the new description attribute. + +### 2022-06-09 + +- Updated [List Agent Pools](/terraform/enterprise/api-docs/agents#list-agent-pools) to accept a search parameter `q`, so that agent pools can be searched by `name`. This is available in Terraform Enterprise v202207-1 and later. +- Fixed [List Workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces) to add missing `search[tags]` query parameter. +- Updated [List Workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces) to add new `search[exclude_tags]` query parameter. This is available in Terraform Enterprise v202207-1 and later. + +### 2022-05-11 + +- Updated Run Tasks permission to the following endpoints: + - [Organizations](/terraform/enterprise/api-docs/organizations#list-organizations). + - [Team Access](/terraform/enterprise/api-docs/team-access#list-team-access-to-a-workspace). + - [Teams](/terraform/enterprise/api-docs/teams#list-teams). + +### 2022-05-04 + +- Updated [Feature Sets](/terraform/enterprise/api-docs/feature-sets#list-feature-sets) to add new `run-tasks` attribute. + +### 2022-05-03 + +- Added Run Tasks permission to the following endpoints: + - [Organizations](/terraform/enterprise/api-docs/organizations#list-organizations) + - [Workspaces](/terraform/enterprise/api-docs/workspaces#show-workspace) + +### 2022-04-29 + +- Updated [Run Tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) to specify the allowed `status` attribute values. +- Updated [Organization Memberships](/terraform/enterprise/api-docs/organization-memberships#query-parameters) to add new `filter[email]` query parameter. +- Updated [Teams](/terraform/enterprise/api-docs/teams#query-parameters) to add new `filter[names]` query parameter. + +### 2022-04-04 + +- Added the [Run Tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) endpoint. + +### 2022-03-14 + +- Added the [Download Configuration Files](/terraform/enterprise/api-docs/configuration-versions#download-configuration-files) endpoints. + +### 2022-03-11 + +- Introduced [Archiving Configuration Versions](/terraform/enterprise/workspaces/configurations#archiving-configuration-versions). + - Updated [Configuration Versions](/terraform/enterprise/api-docs/configuration-versions#attributes) to add new `fetching` and `archived` states. + - Updated [Runs](/terraform/enterprise/api-docs/run#attributes) to add new `fetching` state. + - Added the [Archive a Configuration Version](/terraform/enterprise/api-docs/configuration-versions#archive-a-configuration-version) endpoint. + +### 2022-02-25 + +- Updated [Workspace Run Tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks#show-a-run-task) to add new `enabled`attribute. + +### 2022-02-28 + +- Introduced the [Registry Providers](/terraform/enterprise/api-docs/private-registry/providers) endpoints to manage private providers for a private registry. + +### 2021-12-09 + +- Added `variables` field for POST /runs and the run resource, enabling run-specific variable values. + +### 2021-12-03 + +- OAuth API updated to handle `secret` and `rsa_public_key` fields for POST/PUT. + +### 2021-11-17 + +- Added pagination support to the following endpoints: + - [Feature Sets](/terraform/enterprise/api-docs/feature-sets#list-feature-sets) - `GET /feature-sets` + - [Notification Configurations](/terraform/enterprise/api-docs/notification-configurations#list-notification-configurations) - `GET /workspaces/:workspace_id/notification-configurations` + - [Oauth Clients](/terraform/enterprise/api-docs/oauth-clients#list-oauth-clients) - `GET /organizations/:organization_name/oauth-clients` + - [Oauth Tokens](/terraform/enterprise/api-docs/oauth-tokens#list-oauth-tokens) - `GET /oauth-clients/:oauth_client_id/oauth-tokens` + - [Organization Feature Sets](/terraform/enterprise/api-docs/feature-sets#list-feature-sets-for-organization) - `GET /organizations/:organization_name/feature-sets` + - [Organizations](/terraform/enterprise/api-docs/organizations#list-organizations) - `GET /organizations` + - [Policy Checks](/terraform/enterprise/api-docs/policy-checks#list-policy-checks) - `GET /runs/:run_id/policy-checks` + - [Policy Set Parameters](/terraform/enterprise/api-docs/policy-set-params#list-parameters) - `GET /policy-sets/:policy_set_id/parameters` + - [SSH Keys](/terraform/enterprise/api-docs/ssh-keys#list-ssh-keys) - `GET /organizations/:organization_name/ssh-keys` + - [User Tokens](/terraform/enterprise/api-docs/user-tokens#list-user-tokens) - `GET /users/:user_id/authentication-tokens` + +### 2021-11-11 + +- Introduced the [Variable Sets](/terraform/enterprise/api-docs/variable-sets) endpoints for viewing and administering Variable Sets + +### 2021-11-18 + +- Introduced the [Registry Providers](/terraform/enterprise/api-docs/private-registry/providers) endpoint to manage public providers for a + private registry. These endpoints will be available in the following Terraform Enterprise Release: `v202112-1` + +### 2021-09-12 + +- Added [Run Tasks Stages and Results](/terraform/enterprise/api-docs/run-tasks/run-task-stages-and-results) endpoint. + +### 2021-08-18 + +- Introduced the [State Version Outputs](/terraform/enterprise/api-docs/state-versions) endpoint to retrieve the Outputs for a + given State Version + +### 2021-08-11 + +- **BREAKING CHANGE:** Security fix to [Configuration versions](/terraform/enterprise/api-docs/configuration-versions): upload-url attribute for [uploading configuration files](/terraform/enterprise/api-docs/configuration-versions#upload-configuration-files) is now only available on the create response. + +### 2021-07-30 + +- Introduced Workspace Tagging + - Updated [Workspaces](/terraform/enterprise/api-docs/workspaces): + - added `tag-names` attribute. + - added `POST /workspaces/:workspace_id/relationships/tags` + - added `DELETE /workspaces/:workspace_id/relationships/tags` + - Added [Organization Tags](/terraform/enterprise/api-docs/organization-tags). + - Added `tags` attribute to [`tfrun`](/terraform/enterprise/policy-enforcement/sentinel/import/tfrun) + +### 2021-07-19 + +- [Notification configurations](/terraform/enterprise/api-docs/notification-configurations): Gave organization tokens permission to create and manage notification configurations. + +### 2021-07-09 + +- [State versions](/terraform/enterprise/api-docs/state-versions): Fixed the ID format for the workspace relationship of a state version. Previously, the reported ID was unusable due to a bug. +- [Workspaces](/terraform/enterprise/api-docs/workspaces): Added `locked_by` as an includable related resource. +- Added [Run Tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) API endpoint. + +### 2021-06-8 + +- Updated [Registry Module APIs](/terraform/enterprise/api-docs/private-registry/modules). + - added `registry_name` scoped APIs. + - added `organization_name` scoped APIs. + - added [Module List API](/terraform/enterprise/api-docs/private-registry/modules#list-registry-modules-for-an-organization). + - updated [Module Delete APIs](/terraform/enterprise/api-docs/private-registry/modules#delete-a-module) (see deprecation note below). + - **CLOUD**: added public registry module related APIs. +- **DEPRECATION**: The following [Registry Module APIs](/terraform/enterprise/api-docs/private-registry/modules) have been replaced with newer apis and will be removed in the future. + - The following endpoints to delete modules are replaced with [Module Delete APIs](/terraform/enterprise/api-docs/private-registry/modules#delete-a-module) + - `POST /registry-modules/actions/delete/:organization_name/:name/:provider/:version` replaced with `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/:version` + - `POST /registry-modules/actions/delete/:organization_name/:name/:provider` replaced with `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` + - `POST /registry-modules/actions/delete/:organization_name/:name` replaced with `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name` + - `POST /registry-modules` replaced with [`POST /organizations/:organization_name/registry-modules/vcs`](/terraform/enterprise/api-docs/private-registry/modules#publish-a-private-module-from-a-vcs) + - `POST /registry-modules/:organization_name/:name/:provider/versions` replaced with [`POST /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/versions`](/terraform/enterprise/api-docs/private-registry/modules#create-a-module-version) + - `GET /registry-modules/show/:organization_name/:name/:provider` replaced with [`GET /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider`](/terraform/enterprise/api-docs/private-registry/modules#get-a-module) + +### 2021-05-27 + +- **CLOUD**: [Agents](/terraform/enterprise/api-docs/agents): added [delete endpoint](/terraform/enterprise/api-docs/agents#delete-an-agent). + +### 2021-05-19 + +- [Runs](/terraform/enterprise/api-docs/run): added `refresh`, `refresh-only`, and `replace-addrs` attributes. + +### 2021-04-16 + +- Introduced [Controlled Remote State Access](https://www.hashicorp.com/blog/announcing-controlled-remote-state-access-for-terraform-cloud-and-enterprise). + - [Admin Settings](/terraform/enterprise/api-docs/admin/settings): added `default-remote-state-access` attribute. + - [Workspaces](/terraform/enterprise/api-docs/workspaces): + - added `global-remote-state` attribute. + - added [Remote State Consumers](/terraform/enterprise/api-docs/workspaces#get-remote-state-consumers) relationship. + +### 2021-04-13 + +- [Teams](/terraform/enterprise/api-docs/teams): added `manage-policy-overrides` property to the `organization-access` attribute. + +### 2021-03-23 + +- **ENTERPRISE**: `v202103-1` Introduced [Share Modules Across Organizations with Terraform Enterprise](https://www.hashicorp.com/blog/share-modules-across-organizations-terraform-enterprise). + - [Admin Organizations](/terraform/enterprise/api-docs/admin/organizations): + - added new query parameters to [List all Organizations endpoint](/terraform/enterprise/api-docs/admin/organizations#query-parameters) + - added module-consumers link in `relationships` response + - added [update module consumers endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + - added [list module consumers endpoint](/terraform/enterprise/api-docs/admin/organizations#list-module-consumers-for-an-organization) + - [Organizations](/terraform/enterprise/api-docs/organizations): added [Module Producers](/terraform/enterprise/api-docs/organizations#show-module-producers) + - **DEPRECATION**: [Admin Module Sharing](/terraform/enterprise/api-docs/admin/module-sharing): is replaced with a new JSON::Api compliant [endpoint](/terraform/enterprise/api-docs/admin/organizations#update-an-organization-39-s-module-consumers) + +### 2021-03-18 + +- **CLOUD**: Introduced [New Workspace Overview for Terraform Cloud](https://www.hashicorp.com/blog/new-workspace-overview-for-terraform-cloud). + - [Workspaces](/terraform/enterprise/api-docs/workspaces): + - added `resource-count` and `updated-at` attributes. + - added [performance attributes](/terraform/enterprise/api-docs/workspaces#workspace-performance-attributes) (`apply-duration-average`, `plan-duration-average`, `policy-check-failures`, `run-failures`, `workspaces-kpis-run-count`). + - added `readme` and `outputs` [related resources](/terraform/enterprise/api-docs/workspaces#available-related-resources). + - [Team Access](/terraform/enterprise/api-docs/team-access): updated to support pagination. + +### 2021-03-11 + +- Added [VCS Events](/terraform/enterprise/api-docs/vcs-events), limited to GitLab.com connections. + +### 2021-03-08 + +- [Workspaces](/terraform/enterprise/api-docs/workspaces): added `current_configuration_version` and `current_configuration_version.ingress_attributes` as includable related resources. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/comments.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/comments.mdx new file mode 100644 index 0000000000..2e96414328 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/comments.mdx @@ -0,0 +1,227 @@ +--- +page_title: /comments API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/comments` endpoint to create and read + comments on Terraform runs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[307]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Comments API reference + +Comments allow users to leave feedback or record decisions about a run. + +## List Comments for a Run + +`GET /runs/:id/comments` + +| Parameter | Description | +| --------- | ------------------ | +| `id` | The ID of the run. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/runs/run-KTuq99JSzgmDSvYj/comments +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsc-JdFX3u8o114F4CWf", + "type": "comments", + "attributes": { + "body": "A comment body" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-fo1YXZ8W5bp5GBKM", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-fo1YXZ8W5bp5GBKM" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-JdFX3u8o114F4CWf" + } + }, + { + "id": "wsc-QdhSPFTNoCTpfafp", + "type": "comments", + "attributes": { + "body": "Another comment body" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-fo1YXZ8W5bp5GBKM", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-fo1YXZ8W5bp5GBKM" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-QdhSPFTNoCTpfafp" + } + } + ] +} +``` + +## Show a Comment + +`GET /comments/:id` + +| Parameter | Description | +| --------- | ---------------------- | +| `id` | The ID of the comment. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/comments/wsc-gTFq83JSzjmAvYj +``` + +### Sample Response + +```json +{ + "data": { + "id": "wsc-gTFq83JSzjmAvYj", + "type": "comments", + "attributes": { + "body": "Another comment" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-8RB5ZaFrDanG2hGY", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-8RB5ZaFrDanG2hGY" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-gTFq83JSzjmAvYj" + } + } +} +``` + +## Create Comment + +`POST /runs/:id/comments` + +| Parameter | Description | +| --------- | ------------------ | +| `id` | The ID of the run. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as the request payload. + +| Key Path | Type | Default | Description | +| ---------------------- | ------ | ------- | ------------------------ | +| `data.type` | string | | Must be `"comments"`. | +| `data.attributes.body` | string | | The body of the comment. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "body": "A comment about the run", + }, + "type": "comments" + } +} +``` + +### 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/runs/run-KTuq99JSzgmDSvYj/comments +``` + +### Sample Response + +```json +{ + "data": { + "id": "wsc-oRiShushpgLU4JD2", + "type": "comments", + "attributes": { + "body": "A comment about the run" + }, + "relationships": { + "run-event": { + "data": { + "id": "re-E3xsBX11F1fbm2zV", + "type": "run-events" + }, + "links": { + "related": "/api/v2/run-events/re-E3xsBX11F1fbm2zV" + } + } + }, + "links": { + "self": "/api/v2/comments/wsc-oRiShushpgLU4JD2" + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/configuration-versions.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/configuration-versions.mdx new file mode 100644 index 0000000000..8b5f077525 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/configuration-versions.mdx @@ -0,0 +1,561 @@ +--- +page_title: /configuration-versions API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/configuration-versions` endpoint to list, + show, and create a configuration version and its files within a workspace. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[302]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Configuration versions API reference + +-> **Note:** Before working with the runs or configuration versions APIs, read the [API-driven run workflow](/terraform/enterprise/run/api) page, which includes both a full overview of this workflow and a walkthrough of a simple implementation of it. + +A configuration version (`configuration-version`) is a resource used to reference the uploaded configuration files. It is associated with the run to use the uploaded configuration files for performing the plan and apply. + +You need read runs permission to list and view configuration versions for a workspace, and you need queue plans permission to create new configuration versions. Refer to the [permissions](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) documentation for more details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Attributes + +### Configuration Version States + +The configuration version state is found in `data.attributes.status`, and you can reference the following list of possible states. + +A configuration version created through the API or CLI can only be used in runs if it is in an `uploaded` state. A configuration version created through a linked VCS repository may also be used in runs if it is in an `archived` state. + +| State | Description | | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | +| `pending` | The initial status of a configuration version after it has been created. Pending configuration versions cannot be used to create new runs. | | +| `fetching` | For configuration versions created from a commit to a connected VCS repository, HCP Terraform is currently fetching the associated files from VCS. | | +| `uploaded` | The configuration version is fully processed and can be used in runs. | | +| `archived` | All immediate runs are complete and HCP Terraform has discarded the files associated with this configuration version. If the configuration version was created through a connected VCS repository, it can still be used in new runs. In those cases, HCP Terraform will re-fetch the files from VCS. | | +| `errored` | HCP Terraform could not process this configuration version, and it cannot be used to create new runs. You can try again by pushing a new commit to your linked VCS repository or creating a new configuration version with the API or CLI. | | +| `backing_data_soft_deleted` | Indicates that the configuration version's backing data is marked for garbage collection. If no action is taken, the backing data associated with this configuration version is permanently deleted after a set number of days. You can restore the backing data associated with the configuration version before it is permanently deleted. | | +| `backing_data_permanently_deleted` | The configuration version's backing data has been permanently deleted and can no longer be restored. | | + +## List Configuration Versions + +`GET /workspaces/:workspace_id/configuration-versions` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list configurations from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 configuration versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/workspaces/ws-2Qhk7LHgbMrm3grF/configuration-versions +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "cv-ntv3HbhJqvFzamy7", + "type": "configuration-versions", + "attributes": { + "error": null, + "error-message": null, + "source": "gitlab", + "speculative":false, + "status": "uploaded", + "status-timestamps": {}, + "provisional": false + }, + "relationships": { + "ingress-attributes": { + "data": { + "id": "ia-i4MrTxmQXYxH2nYD", + "type": "ingress-attributes" + }, + "links": { + "related": + "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes" + } + } + }, + "links": { + "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7", + "download": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download" + } + } + ] +} +``` + +## Show a Configuration Version + +`GET /configuration-versions/:configuration-id` + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:configuration-id` | The id of the configuration to show. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7 +``` + +### Sample Response + +```json +{ + "data": { + "id": "cv-ntv3HbhJqvFzamy7", + "type": "configuration-versions", + "attributes": { + "error": null, + "error-message": null, + "source": "gitlab", + "speculative":false, + "status": "uploaded", + "status-timestamps": {}, + "provisional": false + }, + "relationships": { + "ingress-attributes": { + "data": { + "id": "ia-i4MrTxmQXYxH2nYD", + "type": "ingress-attributes" + }, + "links": { + "related": + "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/ingress-attributes" + } + } + }, + "links": { + "self": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7", + "download": "/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download" + } + } +} +``` + +## Show a Configuration Version's Commit Information + +An ingress attributes resource (`ingress-attributes`) is used to reference commit information for configuration versions created in a workspace with a VCS repository. + +`GET /configuration-versions/:configuration-id/ingress-attributes` + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:configuration-id` | The id of the configuration to show. | + +Ingress attributes can also be fetched as part of a query to a particular configuration version via `include`: + +`GET /configuration-versions/:configuration-id?include=ingress-attributes` + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:configuration-id` | The id of the configuration to show. | + + + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/configuration-versions/cv-TrHjxIzad9Ae9i8x/ingress-attributes +``` + +### Sample Response + +```json +{ + "data": { + "id": "ia-zqHjxJzaB9Ae6i9t", + "type": "ingress-attributes", + "attributes": { + "branch": "add-cool-stuff", + "clone-url": "https://github.com/hashicorp/foobar.git", + "commit-message": "Adding really cool infrastructure", + "commit-sha": "1e1c1018d1bbc0b8517d072718e0d87c1a0eda95", + "commit-url": "https://github.com/hashicorp/foobar/commit/1e1c1018d1bbc0b8517d072718e0d87c1a0eda95", + "compare-url": "https://github.com/hashicorp/foobar/pull/163", + "identifier": "hashicorp/foobar", + "is-pull-request": true, + "on-default-branch": false, + "pull-request-number": 163, + "pull-request-url": "https://github.com/hashicorp/foobar/pull/163", + "pull-request-title": "Adding really cool infrastructure", + "pull-request-body": "These are changes to add really cool stuff. We should absolutely merge this.", + "tag": null, + "sender-username": "chrisarcand", + "sender-avatar-url": "https://avatars.githubusercontent.com/u/2430490?v=4", + "sender-html-url": "https://github.com/chrisarcand" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-PQk2Z3dfXAax18P6s", + "type": "users" + }, + "links": { + "related": "/api/v2/ingress-attributes/ia-zqHjxJzaB9Ae6i9t/created-by" + } + } + }, + "links": { + "self": "/api/v2/ingress-attributes/ia-zqHjxJzaB9Ae6i9t" + } + } +} +``` + +## Create a Configuration Version + +`POST /workspaces/:workspace_id/configuration-versions` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to create the new configuration version in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.auto-queue-runs` | boolean | true | When true, runs are queued automatically when the configuration version is uploaded. | +| `data.attributes.speculative` | boolean | false | When true, this configuration version may only be used to create runs which are speculative, that is, can neither be confirmed nor applied. | +| `data.attributes.provisional` | boolean | false | When true, this configuration version does not immediately become the workspace current configuration version. If the associated run is applied, it then becomes the current configuration version unless a newer one exists. | + +### Sample Payload + +```json +{ + "data": { + "type": "configuration-versions", + "attributes": { + "auto-queue-runs": true + } + } +} +``` + +### 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/workspaces/ws-2Qhk7LHgbMrm3grF/configuration-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "cv-UYwHEakurukz85nW", + "type": "configuration-versions", + "attributes": { + "auto-queue-runs": true, + "error": null, + "error-message": null, + "source": "tfe-api", + "speculative":false, + "status": "pending", + "status-timestamps": {}, + "upload-url": + "https://archivist.terraform.io/v1/object/9224c6b3-2e14-4cd7-adff-ed484d7294c2", + "provisional": false + }, + "relationships": { + "ingress-attributes": { + "data": null, + "links": { + "related": + "/api/v2/configuration-versions/cv-UYwHEakurukz85nW/ingress-attributes" + } + } + }, + "links": { "self": "/api/v2/configuration-versions/cv-UYwHEakurukz85nW" } + } +} +``` + +### Configuration Files Upload URL + +Once a configuration version is created, use the `upload-url` attribute to [upload configuration files](#upload-configuration-files) associated with that version. The `upload-url` attribute is only provided in the response when creating configuration versions. + +## Upload Configuration Files + +-> **Note**: If `auto-queue-runs` was either not provided or set to `true` during creation of the configuration version, a run using this configuration version will be automatically queued on the workspace. If `auto-queue-runs` was set to `false` explicitly, then it is necessary to [create a run on the workspace](/terraform/enterprise/api-docs/run#create-a-run) manually after the configuration version is uploaded. + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided in the `upload-url` attribute when creating a `configuration-versions` resource. After creation, the URL is hidden on the resource and no longer available.** + +### Sample Request + +**@filename is the name of configuration file you wish to upload.** + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @filename \ + https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da +``` + +## Archive a Configuration Version + +`POST /configuration-versions/:configuration_version_id/actions/archive` + +| Parameter | Description | +| -------------------------- | ----------------------------------------------- | +| `configuration_version_id` | The ID of the configuration version to archive. | + +This endpoint notifies HCP Terraform to discard the uploaded `.tar.gz` file associated with this configuration version. This endpoint can only archive configuration versions that were created with the API or CLI, are in an `uploaded` [state](#configuration-version-states), have no runs in progress, and are not the current configuration version for any workspace. Otherwise, calling this endpoint will result in an error. + +HCP Terraform automatically archives configuration versions created through VCS when associated runs are complete and then re-fetches the files for subsequent runs. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [202][] | none | Successfully initiated the archive process. | +| [409][] | [JSON API error object][] | Configuration version was in a non-archivable state or the configuration version was created with VCS and cannot be archived through the API. | +| [404][] | [JSON API error object][] | Configuration version was not found or user not authorized. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/archive +``` + +## Download Configuration Files + +`GET /configuration-versions/:configuration_version_id/download` + +| Parameter | Description | +| -------------------------- | ------------------------------------------------ | +| `configuration_version_id` | The ID of the configuration version to download. | + +`GET /runs/:run_id/configuration-version/download` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------- | +| `run_id` | The ID of the run whose configuration version should be downloaded. | + +These endpoints generate a temporary URL to the location of the configuration version in a `.tar.gz` archive, and then redirect to that link. If using a client that can follow redirects, you can use these endpoints to save the `.tar.gz` archive locally without needing to save the temporary URL. These endpoints will return an error if attempting to download a configuration version that is not in an `uploaded` [state](#configuration-version-states). + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| [302][] | HTTP Redirect | Configuration version found and temporary download URL generated | +| [404][] | [JSON API error object][] | Configuration version not found, or specified configuration version is not uploaded, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --location \ + https://app.terraform.io/api/v2/configuration-versions/cv-C6Py6WQ1cUXQX2x2/download \ + > export.tar.gz +``` + +## Mark a Configuration Version for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/configuration-versions/:configuration-id/actions/soft_delete_backing_data` + +| Parameter | Description | +| ------------------- | --------------------------------------------------- | +| `:configuration-id` | The ID of the configuration version to soft delete. | + +This endpoint directs Terraform Enterprise to _soft delete_ the backing files associated with the configuration version. Soft deletion refers to marking the configuration version for garbage collection. Terraform permanently deletes configuration versions marked for soft deletion after a set number of days unless the configuration version is restored. Once a configuration version is soft deleted, any attempts to read the configuration version will fail. Refer to [Configuration Version States](#configuration-version-states) for information about all data states. + +This endpoint can only soft delete configuration versions that meet the following criteria: + +- Were created using the API or CLI, +- are in an [`uploaded` state](#configuration-version-states), +- and are not the current configuration version. + +Otherwise, the endpoint returns an error. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [200][] | none | Terraform successfully marked the data for garbage collection. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_soft_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the configuration version or the user is not authorized to modify the configuration version state. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/soft_delete_backing_data + --data {"data": {"attributes": {"delete-older-than-n-days": 23}}} +``` + +## Restore Configuration Versions Marked for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/configuration-versions/:configuration-id/actions/restore_backing_data` + +| Parameter | Description | +| ------------------- | ---------------------------------------------------------------------------------------- | +| `:configuration-id` | The ID of the configuration version to restore back to its uploaded state if applicable. | + +This endpoint directs Terraform Enterprise to restore backing files associated with this configuration version. This endpoint can only restore delete configuration versions that meet the following criteria: + +- are not in a [`backing_data_permanently_deleted` state](#configuration-version-states). + +Otherwise, the endpoint returns an error. Terraform restores applicable configuration versions back to their `uploaded` state. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [200][] | none | Terraform successfully initiated the restore process. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `uploaded`. | +| [404][] | [JSON API error object][] | Terraform did not find the configuration version or the user is not authorized to modify the configuration version state. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/restore_backing_data +``` + +## Permanently Delete a Configuration Version + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/configuration-versions/:configuration-id/actions/permanently_delete_backing_data` + +| Parameter | Description | +| ------------------- | ---------------------------------------------------------- | +| `:configuration-id` | The ID of the configuration version to permanently delete. | + +This endpoint directs Terraform Enterprise to permanently delete backing files associated with this configuration version. This endpoint can only permanently delete configuration versions that meet the following criteria: + +- Were created using the API or CLI, +- are in a [`backing_data_soft_deleted` state](#configuration-version-states), +- and are not the current configuration version. + +Otherwise, the endpoint returns an error. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| [200][] | none | Terraform successfully deleted the data permanently. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_permanently_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the configuration version or the user is not authorized to modify the configuration version state. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/actions/permanently_delete_backing_data +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| -------------------- | ------------------------------------------------- | +| `ingress_attributes` | The commit information used in the configuration. | +| `run` | The run created by the configuration. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/cost-estimates.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/cost-estimates.mdx new file mode 100644 index 0000000000..a58a2b8481 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/cost-estimates.mdx @@ -0,0 +1,98 @@ +--- +page_title: /cost-estimates API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/cost-estimates` endpoint to read a cost + estimate using its ID. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Cost estimates API reference + +## Show a cost estimate + +-> **Note**: The hash in the `resources` attribute structure represents low-level Cost Estimation details. The keys or structure may change over time. Use the data in this hash at your own risk. + +`GET /cost-estimates/:id` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `id` | The ID of the cost estimate to show. | + +There is no endpoint to list cost estimates. You can find the ID for a cost estimate in the +`relationships.cost-estimate` property of a run object. + +| Status | Response | Reason | +| ------- | ------------------------------------------------ | --------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "cost-estimates"`) | The request was successful | +| [404][] | [JSON API error object][] | Cost estimate not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/cost-estimates/ce-BPvFFrYCqRV6qVBK +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ce-BPvFFrYCqRV6qVBK", + "type": "cost-estimates", + "attributes": { + "error-message": null, + "status": "finished", + "status-timestamps": { + "queued-at": "2017-11-29T20:02:17+00:00", + "finished-at": "2017-11-29T20:02:20+00:00" + }, + "resources": {...}, + "resources-count": 4, + "matched-resources-count": 3, + "unmatched-resources-count": 1, + "prior-monthly-cost": "0.0", + "proposed-monthly-cost": "25.488", + "delta-monthly-cost": "25.488", + }, + "links": { + "self": "/api/v2/cost-estimate/ce-9VYRc9bpfJEsnwum" + } + } + ] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/github-app-installations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/github-app-installations.mdx new file mode 100644 index 0000000000..8573467c08 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/github-app-installations.mdx @@ -0,0 +1,127 @@ +--- +page_title: /github-app/installations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/github-app/installations` endpoint to + view details about where you have installed the Terraform Enterprise GitHub + App. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# GitHub App installations API reference + +You can create a GitHub App installation using the HCP Terraform UI. Learn how to [create a GitHub App installation](/terraform/enterprise/vcs/github-app). + +~> **Note:** To use this resource in Terraform Enterprise installations, you must configure the GitHub App in the site admin area. + +~> **Note:** You can only use this API if you have already authorized the Terraform Cloud GitHub App. Manage your [GitHub App token](/terraform/enterprise/users-teams-organizations/users#github-app-oauth-token) from **Account Settings** > **Tokens**. + +## List Installations + +This endpoint lists GitHub App installations available to the current user. + +`GET /github-app/installations` + +### Query Parameters + +Queries only return GitHub App Installations that the current user has access to within GitHub. + +| Parameter | Description | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[name]` | **Optional.** If present, returns a list of available GitHub App installations that match the GitHub organization or login. | +| `filter[installation_id]` | **Optional.** If present, returns a list of available GitHub App installations that match the installation ID within GitHub. (**Not HCP Terraform**) | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/github-app/installations +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ghain-BYrbNeGQ8nAzKouu", + "type": "github-app-installations", + "attributes": { + "name": "octouser", + "installation-id": 54810170, + "icon-url": "https://avatars.githubusercontent.com/u/29916665?v=4", + "installation-type": "User", + "installation-url": "https://github.com/settings/installations/54810170" + } + } + ] +} +``` + +## Show Installation + +`GET /github-app/installation/:gh_app_installation_id` + +| Parameter | Description | +| ------------------------- | ------------------------------ | +| `:gh_app_installation_id` | The Github App Installation ID | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/github-app/installation/ghain-R4xmKTaxnhLFioUq +``` + +### Sample Response + +```json +{ + "data": { + "id": "ghain-R4xmKTaxnhLFioUq", + "type": "github-app-installations", + "attributes": { + "name": "octouser", + "installation-id": 54810170, + "icon-url": "https://avatars.githubusercontent.com/u/29916665?v=4", + "installation-type": "User", + "installation-url": "https://github.com/settings/installations/54810170" + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/index.mdx new file mode 100644 index 0000000000..94b8db2657 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/index.mdx @@ -0,0 +1,396 @@ +--- +page_title: API documentation for Terraform Enterprise +description: >- + Learn about API authentication, response codes, versioning, formatting, rate + limiting, and clients. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# HCP Terraform API documentation + +HCP Terraform provides an API for a subset of its features. If you need assistance or want to submit a feature request, visit the [HashiCorp support center](https://support.hashicorp.com/hc/en-us) and open a ticket. + +-> **Note:** Before planning an API integration, consider whether [the `tfe` Terraform provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) meets your needs. It can't create or approve runs in response to arbitrary events, but it's a useful tool for managing your organizations, teams, and workspaces as code. + +HashiCorp provides a [stability policy](/terraform/enterprise/api-docs/stability-policy) for the HCP Terraform API, ensuring backwards compatibility for stable endpoints. The [changelog](/terraform/enterprise/api-docs/changelog) tracks changes to the API for HCP Terraform and Terraform Enterprise. + +## Authentication + +All requests must be authenticated with a bearer token. Use the HTTP header `Authorization` with the value `Bearer `. If the token is absent or invalid, HCP Terraform responds with [HTTP status 401][401] and a [JSON API error object][]. The 401 status code is reserved for problems with the authentication token; forbidden requests with a valid token result in a 404. + +You can use the following types of tokens to authenticate: + +- [User tokens](/terraform/enterprise/users-teams-organizations/users#api-tokens) — each HCP Terraform user can have any number of API tokens, which can make requests on their behalf. +- [Team tokens](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) — each team can have one API token at a time. This is intended for performing plans and applies via a CI/CD pipeline. +- [Organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) — each organization can have one API token at a time. This is intended for automating the management of teams, team membership, and workspaces. The organization token cannot perform plans and applies. + +- [Audit trails token](/terraform/enterprise/users-teams-organizations/api-tokens#audit-trails-tokens) - each organization can have a single token that can read that organization's audit trails. Use this token type to authenticate integrations pulling audit trail data, for example, using the [HCP Terraform for Splunk](/terraform/enterprise/integrations/splunk) app. + + +### 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). + +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. + +For example, the [state versions api](/terraform/enterprise/api-docs/state-versions) returns a field named `hosted-state-download`, which is a URL of this form: +`https://archivist.terraform.io/v1/object/` + +This is a broadly accepted pattern for secure access. It is important to treat these URLs themselves as secrets. They should not be logged, nor shared with untrusted parties. + +## Feature Entitlements + +HCP Terraform is available at multiple pricing tiers (including free), which offer different feature sets. + +Each organization has a set of _entitlements_ that corresponds to its pricing tier. These entitlements determine which HCP Terraform features the organization can use. + +If an organization doesn't have the necessary entitlement to use a given feature, HCP Terraform returns a 404 error for API requests to any endpoints devoted to that feature. + +The [show entitlement set](/terraform/enterprise/api-docs/organizations#show-the-entitlement-set) endpoint can return information about an organization's current entitlements, which is useful if your client needs to change its interface when a given feature isn't available. + +The following entitlements are available: + +- `agents` — Allows isolated, private or on-premises infrastructure to communicate with an organization in HCP Terraform. Affects the [agent pools][], [agents][], and [agent tokens][] endpoints. + +- `audit-logging` — Allows an organization to access [audit trails][]. + +- `configuration-designer` — Allows an organization to use the [Configuration Designer][]. +- `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. +- `state-storage` — Allows an organization to store state versions in its workspaces, which enables local Terraform runs with HCP Terraform. Affects the [state versions][] endpoints. +- `sso` — Allows an organization to manage and authenticate users with single sign on. +- `teams` — Allows an organization to manage access to its workspaces with [teams](/terraform/enterprise/users-teams-organizations/teams). Without this entitlement, an organization only has an owners team. Affects the [teams][], [team members][], [team access][], and [team tokens][] endpoints. +- `user-limit` — An integer value representing the maximum number of users allowed for the organization. If blank, there is no limit. +- `vcs-integrations` — Allows an organization to [connect with a VCS provider][vcs integrations] and link VCS repositories to workspaces. Affects the [OAuth Clients][o-clients], and [OAuth Tokens][o-tokens] endpoints, and determines whether the `data.attributes.vcs-repo` property can be set for [workspaces][]. + +[agents]: /terraform/enterprise/api-docs/agents + +[agent pools]: /terraform/enterprise/api-docs/agents + +[agent tokens]: /terraform/enterprise/api-docs/agent-tokens + +[applies]: /terraform/enterprise/api-docs/applies + + + +[audit trails]: /terraform/enterprise/api-docs/audit-trails + + + +[Configuration Designer]: /terraform/enterprise/registry/design + +[cost estimation]: /terraform/enterprise/cost-estimation + +[o-clients]: /terraform/enterprise/api-docs/oauth-clients + +[o-tokens]: /terraform/enterprise/api-docs/oauth-tokens + +[plans]: /terraform/enterprise/api-docs/plans + +[policies]: /terraform/enterprise/api-docs/policies + +[policy checks]: /terraform/enterprise/api-docs/policy-checks + +[policy sets]: /terraform/enterprise/api-docs/policy-sets + +[private module registry]: /terraform/enterprise/registry + +[registry modules]: /terraform/enterprise/api-docs/private-registry/modules + +[registry providers]: /terraform/enterprise/api-docs/private-registry/providers + +[runs]: /terraform/enterprise/api-docs/run + +[run tasks]: /terraform/enterprise/api-docs/run-tasks/run-tasks + +[Sentinel]: /terraform/enterprise/policy-enforcement/sentinel + +[single sign on]: /terraform/enterprise/users-teams-organizations/single-sign-on + +[state versions]: /terraform/enterprise/api-docs/state-versions + +[teams]: /terraform/enterprise/api-docs/teams + +[team access]: /terraform/enterprise/api-docs/team-access + +[team members]: /terraform/enterprise/api-docs/team-members + +[team tokens]: /terraform/enterprise/api-docs/team-tokens + +[vcs integrations]: /terraform/enterprise/vcs + +[workspaces]: /terraform/enterprise/api-docs/workspaces + +## Response Codes + +This API returns standard HTTP response codes. + +We return 404 Not Found codes for resources that a user doesn't have access to, as well as for resources that don't exist. This is to avoid telling a potential attacker that a given resource exists. + +## Versioning + +The API documented in these pages is the second version of HCP Terraform's API, and resides under the `/v2` prefix. + +Future APIs will increment this version, leaving the `/v1` API intact, though in the future we might deprecate certain features. In that case, we'll provide ample notice to migrate to the new API. + +## Paths + +All V2 API endpoints use `/api/v2` as a prefix unless otherwise specified. + +For example, if the API endpoint documentation defines the path `/runs` then the full path is `/api/v2/runs`. + +## JSON API Formatting + +The HCP Terraform endpoints use the [JSON API specification](https://jsonapi.org/), which specifies key aspects of the API. Most notably: + +- [HTTP error codes](https://jsonapi.org/examples/#error-objects-error-codes) +- [Error objects](https://jsonapi.org/examples/#error-objects-basics) +- [Document structure][document] +- [HTTP request/response headers](https://jsonapi.org/format/#content-negotiation) + +[document]: https://jsonapi.org/format/#document-structure + +### JSON API Documents + +Since our API endpoints use the JSON API spec, most of them return [JSON API documents][document]. + +Endpoints that use the POST method also require a JSON API document as the request payload. A request object usually looks something like this: + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "category":"terraform", + "hcl":false, + "sensitive":false + }, + "relationships": { + "workspace": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + } + } + } + } +} +``` + +These objects always include a top-level `data` property, which: + +- Must have a `type` property to indicate what type of API object you're interacting with. +- Often has an `attributes` property to specify attributes of the object you're creating or modifying. +- Sometimes has a `relationships` property to specify other objects that are linked to what you're working with. + +In the documentation for each API method, we use dot notation to explain the structure of nested objects in the request. For example, the properties of the request object above are listed as follows: + +| Key path | Type | Default | Description | +| ---------------------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | | The value of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. | +| `data.relationships.workspace.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.workspace.data.id` | string | | The ID of the workspace that owns the variable. | + +We also always include a sample payload object, to show the document structure more visually. + +### Query Parameters + +Although most of our API endpoints use the POST method and receive their parameters as a JSON object in the request payload, some of them use the GET method. These GET endpoints sometimes require URL query parameters, in the standard `...path?key1=value1&key2=value2` format. + +Since these parameters were originally designed as part of a JSON object, they sometimes have characters that must be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) in a query parameter. For example, `[` becomes `%5B` and `]` becomes `%5D`. + +For more about URI structure and query strings, see [the specification (RFC 3986)](https://tools.ietf.org/html/rfc3986) or [the Wikipedia page on URIs](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). + +### Pagination + +Most of the endpoints that return lists of objects support pagination. A client may pass the following query parameters to control pagination on supported endpoints: + +| Parameter | Description | +| -------------- | --------------------------------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 items per page. The maximum page size is 100. | + +Additional data is returned in the `links` and `meta` top level attributes of the response. + +```json +{ + "data": [...], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20", + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/workspaces?page%5Bnumber%5D=2&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": 2, + "total-pages": 2, + "total-count": 21 + } + } +} +``` + +### Inclusion of Related Resources + +Some of the API's GET endpoints can return additional information about nested resources by adding an `include` query parameter, whose value is a comma-separated list of resource types. + +The related resource options are listed in each endpoint's documentation where available. + +The related resources will appear in an `included` section of the response. + +Example: + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-n8UQ6wfhyym25sMe?include=users +``` + +```json +{ + "data": { + "id": "team-n8UQ6wfhyym25sMe", + "type": "teams", + "attributes": { + "name": "owners", + "users-count": 1 + ... + }, + "relationships": { + "users": { + "data": [ + { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + ] + } ... + } + ... + }, + "included": [ + { + "id": "user-62goNpx1ThQf689e", + "type": "users", + "attributes": { + "username": "hashibot" + ... + } ... + } + ] +} +``` + +## Rate Limiting + +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. + +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. + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------- | +| [429][] | [JSON API error object][] | Rate limit has been reached. | + +```json +{ + "errors": [ + { + "detail": "You have exceeded the API's rate limit.", + "status": 429, + "title": "Too many requests" + } + ] +} +``` + +### 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. + +Additionally, the community of HCP Terraform users and vendors have built client libraries in other languages. These client libraries and tools are not tested nor officially maintained by HashiCorp, but are listed below in order to help users find them easily. + +If you have built a client library and would like to add it to this community list, please [contribute](https://github.com/hashicorp/terraform-website#contributions-welcome) to [this page](https://github.com/hashicorp/terraform-docs-common/blob/main/website/docs/cloud-docs/api-docs/index.mdx#client-libraries-and-tools). + +- [tfh](https://github.com/hashicorp-community/tf-helper): UNIX shell console app +- [tf_api_gateway](https://github.com/PlethoraOfHate/tf_api_gateway): Python API library and console app +- [terrasnek](https://github.com/dahlke/terrasnek): Python API library +- [terraform-enterprise-client](https://github.com/skierkowski/terraform-enterprise-client): Ruby API library and console app +- [pyterprise](https://github.com/JFryy/terraform-enterprise-api-python-client): A simple Python API client library. +- [Tfe.NetClient](https://github.com/everis-technology/Tfe.NetClient): .NET Client Library diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/no-code-provisioning.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/no-code-provisioning.mdx new file mode 100644 index 0000000000..c8c0bfd9f9 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/no-code-provisioning.mdx @@ -0,0 +1,924 @@ +--- +page_title: /no-code-modules API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/no-code-modules` endpoint to designate + and configure no-code modules. You can also use this endpoint to deploy and + upgrade no-code workspaces. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: http://jsonapi.org/format/#error-objects + +# No-code provisioning API reference + +The no-code provisioning API allows you to create, configure, and deploy Terraform modules in the no-code provisioning workflows within HCP Terraform. For more information on no-code modules, refer to [Designing No-Code Ready Modules](/terraform/enterprise/no-code-provisioning/module-design). + +## Enable no-code provisioning for a module + +`POST /organizations/:organization_name/no-code-modules` + +| Parameter | Description | +| -------------------- | --------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | + +To deploy a module using the no-code provisioning workflow, the module must meet the following requirement: + +1. The module must exist in your organization's private registry. +2. The module must meet the [design requirements](/terraform/enterprise/no-code-provisioning/module-design#requirements) for a no-code module. +3. You must enable no-code provisioning for the module. + +You can send a `POST` request to the `/no-code-modules` endpoint to enable no-code provisioning for a specific module. You can also call this endpoint to set options for the allowed values of a variable for a no-code module in your organization. + +-> **Note**: This endpoint can not be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "no-code-modules"`) | Successfully enabled a module for no-code provisioning. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------------------------------- | ------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"no-code-modules"`. | +| `data.attributes.version-pin` | string | Latest version of the module | The module version to use in no-code provisioning workflows. | +| `data.attributes.enabled` | boolean | `false` | Set to `true` to enable no-code provisioning workflows. | +| `data.relationships.registry-module.data.id` | string | | The ID of a module in the organization's private registry. | +| `data.relationships.registry-module.data.type` | string | | Must be `"registry-module"`. | +| `data.relationships.variable-options.data[].type` | string | | Must be `"variable-options"`. | +| `data.relationships.variable-options.data[].attributes.variable-name` | string | | The name of a variable within the module. | +| `data.relationships.variable-options.data[].attributes.variable-type` | string | | The data type for the variable. Can be [any type supported by Terraform](/terraform/language/expressions/types#types). | +| `data.relationships.variable-options.data[].attributes.options` | Any\[] | | A list of allowed values for the variable. | + +### Sample Payload + +```json +{ + "data": { + "type": "no-code-modules", + "attributes": { + "version-pin": "1.0.1", + "enabled": true + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-module" + } + }, + "variable-options": { + "data": [ + { + "type": "variable-options", + "attributes": { + "variable-name": "amis", + "variable-type": "string", + "options": [ + "ami-1", + "ami-2", + "ami-3" + ] + } + }, + { + "type": "variable-options", + "attributes": { + "variable-name": "region", + "variable-type": "string", + "options": [ + "eu-north-1", + "us-east-2", + "us-west-1" + ] + } + } + ] + } + } + } +} + +``` + +### 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/organizations/my-organization/no-code-modules +``` + +### Sample Response + +```json +{ + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-modules", + "attributes": { + "enabled": true, + "version-pin": "1.0.1" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-modules" + }, + "links": { + "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options" + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options" + } + ] + } + }, + "links": { + "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2" + } + } +} +``` + +## Update no-code provisioning settings + +`PATCH /no-code-modules/:id` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `:id` | The unique identifier of the no-code module. | + +Send a `PATCH` request to the `/no-code-modules/:id` endpoint to update the settings for the no-code provisioning of a module. You can update the following settings: + +- Enable or disable no-code provisioning. +- Adjust the set of options for allowed variable values. +- Change the module version being provisioned. +- Change the module being provisioned. + +The [API call that enables no-code provisioning for a module](#allow-no-code-provisioning-of-a-module-within-an-organization) returns that module's unique identifier. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "no-code-modules"`) | Successfully updated a no-code module. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------------------------------- | ------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"no-code-modules"`. | +| `data.attributes.version-pin` | string | Existing value | The module version to use in no-code provisioning workflows. | +| `data.attributes.enabled` | boolean | Existing value | Set to `true` to enable no-code provisioning workflows, or `false` to disable them. | +| `data.relationships.registry-module.data.id` | string | Existing value | The ID of a module in the organization's Private Registry. | +| `data.relationships.registry-module.data.type` | string | Existing value | Must be `"registry-module"`. | +| `data.relationships.variable-options.data[].id` | string | | The ID of an existing variable-options set. If provided, a new variable-options set replaces the set with this ID. If not provided, this creates a new variable-option set. | +| `data.relationships.variable-options.data[].type` | string | | Must be `"variable-options"`. | +| `data.relationships.variable-options.data[].attributes.variable-name` | string | | The name of a variable within the module. | +| `data.relationships.variable-options.data[].attributes.variable-type` | string | | The data type for the variable. Can be [any type supported by Terraform](/terraform/language/expressions/types#types). | +| `data.relationships.variable-options.data[].attributes.options` | Any\[] | | A list of allowed values for the variable. | + +### Sample Payload + +```json +{ + "data": { + "type": "no-code-modules", + "attributes": { + "enabled": false + }, + "relationships": { + "registry-module": { + "data": { + "id": "mod-zyai9dwH4VPPaVuC", + "type": "registry-module" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options", + "attributes": { + "variable-name": "Linux AMIs", + "variable-type": "array", + "options": [ + "Xenial Xerus", + "Trusty Tahr" + ] + } + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options", + "attributes": { + "variable-name": "region", + "variable-type": "array", + "options": [ + "eu-north-1", + "us-east-2", + "us-west-1" + ] + } + } + ] + } + } + } +} +``` + +### 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/no-code-modules/nocode-9HE91XDNY3faePn2 +``` + +### Sample Response + +```json +{ + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-modules", + "attributes": { + "enabled": true, + "version-pin": "1.0.1" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-modules" + }, + "links": { + "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options" + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options" + } + ] + } + }, + "links": { + "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2" + } + } +} +``` + +## Read a no-code module's properties + +`GET /no-code-modules/:id` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `:id` | The unique identifier of the no-code module. | + +Use this API to read the details of an existing no-code module. + +The [API call that enables no-code provisioning for a module](#allow-no-code-provisioning-of-a-module-within-an-organization) returns that module's unique identifier. + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "no-code-modules"`) | Successfully read the no-code module. | +| [400][] | [JSON API error object][] | Invalid `include` parameter. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Query Parameters + +This endpoint uses our [standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Use HTML URL encoding syntax, such as `%5B` to represent `[` and `%5D` to represent `]`, if your tooling does not automatically encode URLs. + +Terraform returns related resources when you add the [`include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources) to the request. + +| Parameter | Description | +| --------- | ------------------------------------------------- | +| `include` | List related resource to include in the response. | + +The following resource types are available: + +| Resource Name | Description | +| ------------------ | --------------------------------------------------------- | +| `variable_options` | Module variables with a configured set of allowed values. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2?include=variable_options +``` + +### Sample Response + +```json +{ + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-modules", + "attributes": { + "enabled": true, + "version-pin": "1.0.1" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "registry-module": { + "data": { + "id": "mod-2aaFrmRPZs2N9epr", + "type": "registry-modules" + }, + "links": { + "related": "/api/v2/registry-modules/mod-2aaFrmRPZs2N9epr" + } + }, + "variable-options": { + "data": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options" + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options" + } + ] + } + }, + "links": { + "self": "/api/v2/no-code-modules/nocode-9HE91XDNY3faePn2" + } + }, + "included": [ + { + "id": "ncvaropt-fcHDfnZ1EGdRzFNC", + "type": "variable-options", + "attributes": { + "variable-name": "Linux AMIs", + "variable-type": "array", + "options": [ + "Xenial Xerus", + "Trusty Tahr" + ] + }, + "relationships": { + "no-code-allowed-module": { + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-allowed-modules" + } + } + } + }, + { + "id": "ncvaropt-dZMfdh9KBcwFjyv2", + "type": "variable-options", + "attributes": { + "variable-name": "region", + "variable-type": "array", + "options": [ + "eu-north-1", + "us-east-2", + "us-west-1" + ] + }, + "relationships": { + "no-code-allowed-module": { + "data": { + "id": "nocode-9HE91XDNY3faePn2", + "type": "no-code-allowed-modules" + } + } + } + } + ] +} +``` + +## Create a no-code module workspace + +This endpoint creates a workspace from a no-code module. + +`POST /no-code-modules/:id/workspaces` + +| Parameter | Description | +| --------- | ------------------------------------------ | +| `:id` | The ID of the no-code module to provision. | + +Each HCP Terraform organization has a list of which modules you can use to create workspaces using no-code provisioning. You can use this API to create a workspace by selecting a no-code module to enable a no-code provisioning workflow. + +-> **Note**: This endpoint can not be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | -------------------------------------------- | -------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully created a workspace from a no-code module for no-code provisioning. | +| [404][] | [JSON API error object][] | Not found, or the user is unauthorized to perform this action. | +| [422][] | [JSON API error object][] | Malformed request body (e.g., missing attributes, wrong types, etc.). | +| [500][] | [JSON API error object][] | Internal system failure. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | | +| ------------------------------------------------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | +| `data.type` | string | none | Must be `"workspaces"`. | | +| `data.attributes.agent-pool-id` | string | none | Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote`. | | +| `data.attributes.auto_apply` | boolean | `false` | If `true`, Terraform automatically applies changes when a Terraform `plan` is successful. | | +| `data.attributes.description` | string | `""` | A description for the workspace. | | +| `data.attributes.execution-mode` | string | none | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use. Valid values are `remote`, and `agent`. When not provided, defaults to `remote`. | | +| `data.attributes.name` | string | none | The name of the workspace. You can only include letters, numbers, `-`, and `_`. Terraform uses this value to identify the workspace and must be unique in the organization. | | +| `data.attributes.source-name` | string | none | A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via ``". | | +| `data.attributes.source-url` | string | (nothing) | A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client. | | +| `data.attributes.terraform-version` | string | latest release | Specifies the version of Terraform to use for this workspace. You can specify an exact version or a [version constraint](/terraform/language/expressions/version-constraints) such as `~> 1.0.0`. If you specify a constraint, the workspace always uses the newest release that meets that constraint. If omitted when creating a workspace, this defaults to the latest released version. | | +| `data.relationships.project.data.id` | string | | The ID of the project to create the workspace in. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project. | | +| `data.relationships.project.data.type` | string | | Must be `"project"`. | | +| `data.relationships.vars.data[].type` | string | | Must be `"vars"`. | | +| `data.relationships.vars.data[].attributes.key` | string | | The name of the variable. | | +| `data.relationships.vars.data[].attributes.value` | string | `""` | The value of the variable. | | +| `data.relationships.vars.data[].attributes.description` | string | | The description of the variable. | | +| `data.relationships.vars.data[].attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | | +| `data.relationships.vars.data[].attributes.hcl` | boolean | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | | +| `data.relationships.vars.data[].attributes.sensitive` | boolean | `false` | Whether the value is sensitive. If `true` then the variable is written once and not visible thereafter. | | + +### Sample Payload + +```json +{ + "data": { + "type": "workspaces", + "attributes": { + "name": "no-code-workspace", + "description": "A workspace to enable the no-code provisioning workflow." + }, + "relationships": { + "project": { + "data": { + "id": "prj-yuEN6sJVra5t6XVy", + "type": "project" + } + }, + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "region", + "value": "eu-central-1", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + }, + { + "type": "vars", + "attributes": { + "key": "ami", + "value": "ami‑077062", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + } + ] + } + } + } +} + +``` + +### 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/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces +``` + +### Sample Response + +```json +{ + "data": { + "id": "ws-qACTToFUM5BvDKhC", + "type": "workspaces", + "attributes": { + "allow-destroy-plan": true, + "auto-apply": false, + "auto-destroy-at": null, + "auto-destroy-status": null, + "created-at": "2023-09-08T10:36:04.391Z", + "environment": "default", + "locked": false, + "name": "no-code-workspace", + "queue-all-runs": false, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "terraform-version": "1.5.6", + "working-directory": null, + "global-remote-state": true, + "updated-at": "2023-09-08T10:36:04.427Z", + "resource-count": 0, + "apply-duration-average": null, + "plan-duration-average": null, + "policy-check-failures": null, + "run-failures": null, + "workspace-kpis-runs-count": null, + "latest-change-at": "2023-09-08T10:36:04.391Z", + "operations": true, + "execution-mode": "remote", + "vcs-repo": null, + "vcs-repo-identifier": null, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": true, + "can-force-delete": true, + "can-manage-assessments": true, + "can-manage-ephemeral-workspaces": true, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "actions": { + "is-destroyable": true + }, + "description": null, + "file-triggers-enabled": true, + "trigger-prefixes": [], + "trigger-patterns": [], + "assessments-enabled": false, + "last-assessment-result-at": null, + "source": "tfe-module", + "source-name": null, + "source-url": null, + "source-module-id": "private/my-organization/lambda/aws/1.0.9", + "no-code-upgrade-available": false, + "tag-names": [], + "setting-overwrites": { + "execution-mode": false, + "agent-pool": false + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "current-run": { + "data": null + }, + "latest-run": { + "data": null + }, + "outputs": { + "data": [] + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-qACTToFUM5BvDKhC/relationships/remote-state-consumers" + } + }, + "current-state-version": { + "data": null + }, + "current-configuration-version": { + "data": { + "id": "cv-vizi2p3mnrt3utgA", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-vizi2p3mnrt3utgA" + } + }, + "agent-pool": { + "data": null + }, + "readme": { + "data": null + }, + "project": { + "data": { + "id": "prj-yuEN6sJVra5t6XVy", + "type": "projects" + } + }, + "current-assessment-result": { + "data": null + }, + "no-code-module-version": { + "data": { + "id": "nocodever-vFcQjZLs3ZHTe4TU", + "type": "no-code-module-versions" + } + }, + "vars": { + "data": [] + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/no-code-workspace", + "self-html": "/app/my-organization/workspaces/no-code-workspace" + } + } +} +``` + +## Initiate a no-code workspace update + +Upgrading a workspace's no-code provisioning settings is a multi-step process. + +1. Use this API to initiate the update. HCP Terraform starts a new plan, which describes the resources to add, update, or remove from the workspace. +2. Poll the [read workspace upgrade plan status API](#read-workspace-upgrade-plan-status) to wait for HCP Terraform to complete the plan. +3. Use the [confirm and apply a workspace upgrade plan API](#confirm-and-apply-a-workspace-upgrade-plan) to complete the workspace upgrade. + +`POST /no-code-modules/:no_code_module_id/workspaces/:id/upgrade` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:no_code_module_id` | The ID of the no-code module. | +| `:id` | The ID of the workspace. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.vars.data[].type` | string | | Must be `"vars"`. | +| `data.relationships.vars.data[].attributes.key` | string | | The name of the variable. | +| `data.relationships.vars.data[].attributes.value` | string | `""` | The value of the variable. | +| `data.relationships.vars.data[].attributes.description` | string | | The description of the variable. | +| `data.relationships.vars.data[].attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.relationships.vars.data[].attributes.hcl` | boolean | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.relationships.vars.data[].attributes.sensitive` | boolean | `false` | Whether the value is sensitive. If `true` then the variable is written once and not visible thereafter. | + +### Sample Payload + +```json +{ + "data": { + "type": "workspaces", + "relationships": { + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "region", + "value": "eu-central-1", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + }, + { + "type": "vars", + "attributes": { + "key": "ami", + "value": "ami‑077062", + "category": "terraform", + "hcl": true, + "sensitive": false, + } + } + ] + } + } + } +} + +``` + +### 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/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-Cyij8ctBHM1g5xdX", + "type": "workspace-upgrade", + "attributes": { + "status": "planned", + "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-VvKtcfueHNkR6GqP", + "type": "workspaces" + } + } + } + } +} +``` + +## Read workspace upgrade plan status + +This endpoint returns the plan details and status for updating a workspace to new no-code provisioning settings. + +`GET /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:no_code_module_id` | The ID of the no-code module. | +| `:workspace_id` | The ID of workspace. | +| `:id` | The ID of update. | + +Returns the details of a no-code workspace update run, including the run's current state, such as `pending`, `fetching`, `planning`, `planned`, or `cost_estimated`. Refer to [Run States and Stages](/terraform/enterprise/run/states) for more information on the states a run can return. + +| Status | Response | Reason | +| ------- | --------------------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspace-upgrade"`) | Success | +| [404][] | [JSON API error object][] | Workspace upgrade not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-Cyij8ctBHM1g5xdX", + "type": "workspace-upgrade", + "attributes": { + "status": "planned_and_finished", + "plan-url": "https://app.terraform.io/app/my-organization/no-code-workspace/runs/run-Cyij8ctBHM1g5xdX" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-VvKtcfueHNkR6GqP", + "type": "workspaces" + } + } + } + } +} +``` + +## Confirm and apply a workspace upgrade plan + +Use this endpoint to confirm an update and finalize the update for a workspace to use new no-code provisioning settings. + +`POST /no-code-modules/:no_code_module_id/workspaces/:workspace_id/upgrade/:id` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:no_code_module_id` | The ID of the no-code module. | +| `:workspace_id` | The ID of workspace. | +| `:id` | The ID of update. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/no-code-modules/nocode-WGckovT2RQxupyt1/workspaces/ws-qACTToFUM5BvDKhC/upgrade/run-Cyij8ctBHM1g5xdX +``` + +### Sample Response + +```json +{ "Workspace update completed" } +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/notification-configurations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/notification-configurations.mdx new file mode 100644 index 0000000000..2fa78f811f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/notification-configurations.mdx @@ -0,0 +1,1437 @@ +--- +page_title: /notification-configurations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/notification-configurations` endpoint to + read, create, update, verify, and delete workspace configurations and create + team configurations. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Notification configurations API reference + +HCP Terraform can send notifications for run state transitions and workspace events. You can specify a destination URL, request type, and what events will trigger the notification. Each workspace can have up to 20 notification configurations, and they apply to all runs for that workspace. + +Interacting with notification configurations requires admin access to the relevant workspace. ([More about permissions](/terraform/enterprise/users-teams-organizations/permissions).) + +-> **Note:** [Speculative plans](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) and workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) do not support notifications. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Notification triggers + +Notifications are sent in response to triggers related to workspace events, and can be defined at workspace and team levels. You can specify workspace events in the `triggers` array attribute. + +### Workspace notification triggers + +The following triggers are available for workspace notifications. + +| Display Name | Value | Description | +| ------------------------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Created | `"run:created"` | A run is created and enters the [Pending stage](/terraform/enterprise/run/states#the-pending-stage) | +| Planning | `"run:planning"` | A run acquires the lock and starts to execute. | +| Needs Attention | `"run:needs_attention"` | A plan has changes and Terraform requires user input to continue. This input may include approving the plan or a [policy override](/terraform/enterprise/run/states#the-policy-check-stage). | +| Applying | `"run:applying"` | A run enters the [Apply stage](/terraform/enterprise/run/states#the-apply-stage), where Terraform makes the infrastructure changes described in the plan. | +| Completed | `"run:completed"` | A run completes successfully. | +| Errored | `"run:errored"` | A run terminates early due to error or cancellation. | +| Drifted | `"assessment:drifted"` | HCP Terraform detected configuration drift. This option is only available if you enabled drift detection for the workspace. | +| Checks Failed | `"assessment:check_failure"` | One or more continuous validation checks did not pass. This option is only available if you enabled drift detection for the workspace. | +| Health Assessment Failed | `"assessment:failed"` | A health assessment failed. This option is only available if you enable health assessments for the workspace. | +| Auto Destroy Reminder | `"workspace:auto_destro_reminder"` | An automated workspace destroy run is imminent. | +| Auto Destroy Results | `"workspace:auto_destroy_run_results"` | HCP Terraform attempted an automated workspace destroy run. | + +### Team notification triggers + +The following triggers are available for [team notifications](#team-notification-configuration). + +| Display Name | Value | Description | +| -------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | +| Change Request | `"team:change_request"` | HCP Terraform sent a change request to a workspace that the specified team has explicit access to. | + +## Notification payload + +The notification is an HTTP POST request with a detailed payload. The content depends on the type of notification. + +For Slack and Microsoft Teams notifications, the payload conforms to the respective webhook API and results in a notification message with informational attachments. Refer to [Slack Notification Payloads](/terraform/enterprise/workspaces/settings/notifications#slack) and [Microsoft Teams Notification Payloads](/terraform/enterprise/workspaces/settings/notifications#microsoft-teams) for examples. For generic notifications, the payload varies based on whether the notification contains information about run events or workspace events. + +### Run notification payload + +Run events include detailed information about a specific run, including the time it began and the associated workspace and organization. Generic notifications for run events contain the following information: + +| Name | Type | Description | +| -------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `payload_version` | number | Always "1". | +| `notification_configuration_id` | string | The ID of the configuration associated with this notification. | +| `run_url` | string | URL used to access the run UI page. | +| `run_id` | string | ID of the run which triggered this notification. | +| `run_message` | string | The reason the run was queued. | +| `run_created_at` | string | Timestamp of the run's creation. | +| `run_created_by` | string | Username of the user who created the run. | +| `workspace_id` | string | ID of the run's workspace. | +| `workspace_name` | string | Human-readable name of the run's workspace. | +| `organization_name` | string | Human-readable name of the run's organization. | +| `notifications` | array | List of events which caused this notification to be sent, with each event represented by an object. At present, this is always one event, but in the future HCP Terraform may roll up several notifications for a run into a single request. | +| `notifications[].message` | string | Human-readable reason for the notification. | +| `notifications[].trigger` | string | Value of the trigger which caused the notification to be sent. | +| `notifications[].run_status` | string | Status of the run at the time of notification. | +| `notifications[].run_updated_at` | string | Timestamp of the run's update. | +| `notifications[].run_updated_by` | string | Username of the user who caused the run to update. | + +#### Sample payload + +```json +{ + "payload_version": 1, + "notification_configuration_id": "nc-AeUQ2zfKZzW9TiGZ", + "run_url": "https://app.terraform.io/app/acme-org/my-workspace/runs/run-FwnENkvDnrpyFC7M", + "run_id": "run-FwnENkvDnrpyFC7M", + "run_message": "Add five new queue workers", + "run_created_at": "2019-01-25T18:34:00.000Z", + "run_created_by": "sample-user", + "workspace_id": "ws-XdeUVMWShTesDMME", + "workspace_name": "my-workspace", + "organization_name": "acme-org", + "notifications": [ + { + "message": "Run Canceled", + "trigger": "run:errored", + "run_status": "canceled", + "run_updated_at": "2019-01-25T18:37:04.000Z", + "run_updated_by": "sample-user" + } + ] +} +``` + +### Change request notification payload + +Change request events contain the following fields in their payloads. + +| Name | Type | Description | +| ------------------------------- | ------ | -------------------------------------------------------------- | +| `payload_version` | number | Always "1". | +| `notification_configuration_id` | string | The ID of the configuration associated with this notification. | +| `change_request_url` | string | URL used to access the change request UI page. | +| `change_request_subject` | string | title of the change request which triggered this notification. | +| `change_request_message` | string | The contents of the change request. | +| `change_request_created_at` | string | Timestamp of the change request's creation. | +| `change_request_created_by` | string | Username of the user who created the change_request. | +| `workspace_id` | string | ID of the run's workspace. | +| `workspace_name` | string | Human-readable name of the run's workspace. | +| `organization_name` | string | Human-readable name of the run's organization. | + +##### `Send a test` payload + +This is a sample payload you can send to test if notifications are working. The payload does not have a `run` or `workspace` context, resulting in null values. + +You can trigger a test notification from the workspace notification settings page. You can read more about verifying a [notification configuration](/terraform/enterprise/workspaces/settings/notifications#enabling-and-verifying-a-configuration). + +```json +{ + "payload_version": 1, + "notification_configuration_id": "nc-jWvVsmp5VxsaCeXm", + "run_url": null, + "run_id": null, + "run_message": null, + "run_created_at": null, + "run_created_by": null, + "workspace_id": null, + "workspace_name": null, + "organization_name": null, + "notifications": [ + { + "message": "Verification of test", + "trigger": "verification", + "run_status": null, + "run_updated_at": null, + "run_updated_by": null, + } + ] +} +``` + +### Workspace notification payload + +Workspace events include detailed information about workspace-level validation events like [health assessments](/terraform/enterprise/workspaces/health) if you enable them for the workspace. Much of the information provides details about the associated [assessment result](/terraform/enterprise/api-docs/assessment-results), which HCP Terraform uses to track instances of continuous validation. + +HCP Terraform returns different types of attributes returned in the payload details, depending on the type of `trigger_scope`. There are two main values for `trigger_scope`: `assessment` and `workspace`, examples of which you can see below. + +#### Health assessments + +Health assessment notifications for workspace events contain the following information: + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +| Name | Type | Description | +| ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------- | +| `payload_version` | number | Always "2". | +| `notification_configuration_id` | string | The ID of the configuration associated with this notification. | +| `notification_configuration_url` | string | URL to get the notification configuration from the HCP Terraform API. | +| `trigger_scope` | string | Always "assessment" for workspace assessment notifications. | +| `trigger` | string | Value of the trigger that caused the notification to be sent. | +| `message` | string | Human-readable reason for the notification. | +| `details` | object | Object containing details specific to the notification. | +| `details.new_assessment_result` | object | The most recent assessment result. This result triggered the notification. | +| `details.new_assessment_result.id` | string | ID of the assessment result. | +| `details.new_assessment_result.url` | string | URL to get the assessment result from the HCP Terraform API. | +| `details.new_assessment_result.succeeded` | bool | Whether assessment succeeded. | +| `details.new_assessment_result.all_checks_succeeded` | bool | Whether all conditions passed. | +| `details.new_assessment_result.checks_passed` | number | The number of resources, data sources, and outputs passing their conditions. | +| `details.new_assessment_result.checks_failed` | number | The number of resources, data sources, and outputs with one or more failing conditions. | +| `details.new_assessment_result.checks_errored` | number | The number of resources, data sources, and outputs that had a condition error. | +| `details.new_assessment_result.checks_unknown` | number | The number of resources, data sources, and outputs that had conditions left unevaluated. | +| `details.new_assessment_result.drifted` | bool | Whether assessment detected drift. | +| `details.new_assessment_result.resources_drifted` | number | The number of resources whose configuration does not match from the workspace's state file. | +| `details.new_assessment_result.resources_undrifted` | number | The number of real resources whose configuration matches the workspace's state file. | +| `details.new_assessment_result.created_at` | string | Timestamp for when HCP Terraform created the assessment result. | +| `details.prior_assessment_result` | object | The assessment result immediately prior to the one that triggered the notification. | +| `details.prior_assessment_result.id` | string | ID of the assessment result. | +| `details.prior_assessment_result.url` | string | URL to get the assessment result from the HCP Terraform API. | +| `details.prior_assessment_result.succeeded` | bool | Whether assessment succeeded. | +| `details.prior_assessment_result.all_checks_succeeded` | bool | Whether all conditions passed. | +| `details.prior_assessment_result.checks_passed` | number | The number of resources, data sources, and outputs passing their conditions. | +| `details.prior_assessment_result.checks_failed` | number | The number of resources, data sources, and outputs with one or more failing conditions. | +| `details.prior_assessment_result.checks_errored` | number | The number of resources, data sources, and outputs that had a condition error. | +| `details.prior_assessment_result.checks_unknown` | number | The number of resources, data sources, and outputs that had conditions left unevaluated. | +| `details.prior_assessment_result.drifted` | bool | Whether assessment detected drift. | +| `details.prior_assessment_result.resources_drifted` | number | The number of resources whose configuration does not match the workspace's state file. | +| `details.prior_assessment_result.resources_undrifted` | number | The number of resources whose configuration matches the workspace's state file. | +| `details.prior_assessment_result.created_at` | string | Timestamp of the assessment result. | +| `details.workspace_id` | string | ID of the workspace that generated the notification. | +| `details.workspace_name` | string | Human-readable name of the workspace. | +| `details.organization_name` | string | Human-readable name of the organization. | + +##### Sample payload + +Health assessment payloads have information about resource drift and continuous validation checks. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "assessment", + "trigger": "assessment:drifted", + "message": "Drift Detected", + "details": { + "new_assessment_result": { + "id": "asmtres-vRVQxpqq64EA9V5a", + "url": "https://app.terraform.io/api/v2/assessment-results/asmtres-vRVQxpqq64EA9V5a", + "succeeded": true, + "drifted": true, + "all_checks_succeeded": true, + "resources_drifted": 4, + "resources_undrifted": 55, + "checks_passed": 33, + "checks_failed": 0, + "checks_errored": 0, + "checks_unknown": 0, + "created_at": "2022-06-09T05:23:10Z" + }, + "prior_assessment_result": { + "id": "asmtres-A6zEbpGArqP74fdL", + "url": "https://app.terraform.io/api/v2/assessment-results/asmtres-A6zEbpGArqP74fdL", + "succeeded": true, + "drifted": true, + "all_checks_succeeded": true, + "resources_drifted": 4, + "resources_undrifted": 55, + "checks_passed": 33, + "checks_failed": 0, + "checks_errored": 0, + "checks_unknown": 0, + "created_at": "2022-06-09T05:22:51Z" + }, + "workspace_id": "ws-XdeUVMWShTesDMME", + "workspace_name": "my-workspace", + "organization_name": "acme-org" + } +} +``` + +#### Automatic destroy runs + + + +@include 'tfc-package-callouts/ephemeral-workspaces.mdx' + + + +Automatic destroy run notifications for workspace events contain the following information: + +| Name | Type | Description | +| ---------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- | +| `payload_version` | string | Always 2. | +| `notification_configuration_id` | string | The ID of the notification's configuration. | +| `notification_configuration_url` | string | The URL to get the notification's configuration from the HCP Terraform API. | +| `trigger_scope` | string | Always "workspace" for ephemeral workspace notifications | +| `trigger` | string | Value of the trigger that caused HCP Terraform to send the notification. | +| `message` | string | Human-readable reason for the notification. | +| `details` | object | Object containing details specific to the notification. | +| `details.auto_destroy_at` | string | Timestamp when HCP Terraform will schedule the next destroy run. Only applies to reminder notifications. | +| `details.run_created_at` | string | Timestamp of when HCP Terraform successfully created a destroy run. Only applies to results notifications. | +| `details.run_status` | string | Status of the scheduled destroy run. Only applies to results notifications. | +| `details.run_external_id` | string | The ID of the scheduled destroy run. Only applies to results notifications. | +| `details.run_create_error_message` | string | Message detailing why the run was unable to be queued. Only applies to results notifications. | +| `details.trigger_type` | string | The type of notification, and the value is either "reminder" or "results". | +| `details.workspace_name` | string | Human-readable name of the workspace. | +| `details.organization_name` | string | Human-readable name of the organization. | + +##### Sample payload + +The shape of data in auto destroy notification payloads may differ depending on the success of the run HCP Terraform created. Refer to the specific examples below. + +###### Reminder + +Reminders that HCP Terraform will trigger a destroy run at some point in the future. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "workspace", + "trigger": "workspace:auto_destroy_reminder", + "message": "Auto Destroy Reminder", + "details": { + "auto_destroy_at": "2025-01-01T00:00:00Z", + "run_created_at": null, + "run_status": null, + "run_external_id": null, + "run_create_error_message": null, + "trigger_type": "reminder", + "workspace_name": "learned-english-dog", + "organization_name": "acme-org" + } +} +``` + +###### Results + +The final result of the scheduled auto destroy run includes additional metadata about the run. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "workspace", + "trigger": "workspace:auto_destroy_results", + "message": "Auto Destroy Results", + "details": { + "auto_destroy_at": null, + "run_created_at": "2022-06-09T05:22:51Z", + "run_status": "applied", + "run_external_id": "run-vRVQxpqq64EA9V5a", + "run_create_error_message": null, + "trigger_type": "results", + "workspace_name": "learned-english-dog", + "organization_name": "acme-org" + } +} +``` + +###### Failed run creation + +Run-specific values are empty when HCP Terraform was unable to create an auto destroy run. + +```json +{ + "payload_version": "2", + "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", + "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", + "trigger_scope": "workspace", + "trigger": "workspace:auto_destroy_results", + "message": "Auto Destroy Results", + "details": { + "auto_destroy_at": null, + "run_created_at": null, + "run_status": null, + "run_external_id": null, + "run_create_error_message": "Configuration version is missing", + "trigger_type": "results", + "workspace_name": "learned-english-dog", + "organization_name": "acme-org" + } +} +``` + +## Notification authenticity + +If a `token` is configured, HCP Terraform provides an HMAC signature on all `"generic"` notification requests, using the `token` as the key. This is sent in the `X-TFE-Notification-Signature` header. The digest algorithm used is SHA-512. Notification target servers should verify the source of the HTTP request by computing the HMAC of the request body using the same shared secret, and dropping any requests with invalid signatures. + +Sample Ruby code for verifying the HMAC: + +```ruby +token = SecureRandom.hex +hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha512"), token, @request.body) +fail "Invalid HMAC" if hmac != @request.headers["X-TFE-Notification-Signature"] +``` + +## Notification verification and delivery responses + +When saving a configuration with `enabled` set to `true`, or when using the [verify API][], HCP Terraform sends a verification request to the configured URL. The response to this request is stored and available in the `delivery-responses` array of the `notification-configuration` resource. + +Configurations cannot be enabled if the verification request fails. Success is defined as an HTTP response with status code of `2xx`. +Configurations with `destination_type` `email` can only be verified manually, they do not require an HTTP response. + +The most recent response is stored in the `delivery-responses` array. + +Each delivery response has several fields: + +| Name | Type | Description | +| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `body` | string | Response body (may be truncated). | +| `code` | string | HTTP status code, e.g. `400`. | +| `headers` | object | All HTTP headers received, represented as an object with keys for each header name (lowercased) and an array of string values (most arrays will be size one). | +| `sent-at` | date | The UTC timestamp when the notification was sent. | +| `successful` | bool | Whether HCP Terraform considers this response to be successful. | +| `url` | string | The URL to which the request was sent. | + +[verify API]: #verify-a-notification-configuration + +## Create a notification configuration + +`POST /workspaces/:workspace_id/notification-configurations` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The ID of the workspace to list configurations for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully created a notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +If `enabled` is set to `true`, a verification request will be sent before saving the configuration. If this request receives no response or the response is not successful (HTTP 2xx), the configuration will not save. + +| Key path | Type | Default | Description | +| ---------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"notification-configuration"`. | +| `data.attributes.destination-type` | string | | Type of notification payload to send. Valid values are `"generic"`, `"email"`, `"slack"` or `"microsoft-teams"`. | +| `data.attributes.enabled` | bool | `false` | Disabled configurations will not send any notifications. | +| `data.attributes.name` | string | | Human-readable name for the configuration. | +| `data.attributes.token` | string or null | `null` | Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See [Notification Authenticity][notification-authenticity] for more details. | +| `data.attributes.triggers` | array | `[]` | Array of triggers for which this configuration will send notifications. See [Notification Triggers][notification-triggers] for more details and a list of allowed values. | +| `data.attributes.url` | string | | HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"` | +| `data.relationships.users` | array | | Array of users part of the organization, only for configurations with `"destination_type:"` `"email"` | + +[notification-authenticity]: #notification-authenticity + +[notification-triggers]: #notification-triggers + +### Sample payload for generic notification configurations + +```json +{ + "data": { + "type": "notification-configuration", + "attributes": { + "destination-type": "generic", + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ] + } + } +} +``` + +### Sample payload for email notification configurations + +```json +{ + "data": { + "type": "notification-configurations", + "attributes": { + "destination-type": "email", + "enabled": true, + "name": "Notify organization users about run", + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ] + }, + "relationships": { + "users": { + "data": [ { "id": "organization-user-id", "type": "users" } ] + } + } + } +} +``` + +### 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/workspaces/ws-XdeUVMWShTesDMME/notification-configurations +``` + +### Sample response + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +## List notification configurations + +Use the following endpoint to list all notification configurations for a workspace. + +`GET /workspaces/:workspace_id/notification-configurations` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list configurations from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. | + +### Query parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 notification configurations per page. | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/notification-configurations +``` + +### Sample response + +```json +{ + "data": [ + { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000000/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "run:errored", + "run:needs_attention" + ], + "delivery-responses": [], + "created-at": "2019-01-08T21:34:28.367Z", + "updated-at": "2019-01-08T21:34:28.367Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" + } + }, + { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } + ] +} + +``` + +## Show a notification configuration + +`GET /notification-configurations/:notification-configuration-id` + +| Parameter | Description | +| -------------------------------- | ------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to show. | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ +``` + +### Sample response + +The `type` and `id` attributes in `relationships.subscribable` may also reference a `"teams"` and team ID, respectively. + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +## Update a notification configuration + +`PATCH /notification-configurations/:notification-configuration-id` + +| Parameter | Description | +| -------------------------------- | --------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to update. | + +If the `enabled` attribute is true, updating the configuration will cause HCP Terraform to send a verification request. If a response is received, it will be stored and returned in the `delivery-responses` attribute. More details in the [Notification Verification and Delivery Responses][] section above. + +[Notification Verification and Delivery Responses]: #notification-verification-and-delivery-responses + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully updated the notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | +| [404][] | [JSON API error object][] | Notification configuration not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +If `enabled` is set to `true`, a verification request will be sent before saving the configuration. If this request fails to send, or the response is not successful (HTTP 2xx), the configuration will not save. + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | (previous value) | Must be `"notification-configuration"`. | +| `data.attributes.enabled` | bool | (previous value) | Disabled configurations will not send any notifications. | +| `data.attributes.name` | string | (previous value) | User-readable name for the configuration. | +| `data.attributes.token` | string | (previous value) | Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See [Notification Authenticity][notification-authenticity] for more details. | +| `data.attributes.triggers` | array | (previous value) | Array of triggers for sending notifications. See [Notification Triggers][notification-triggers] for more details. | +| `data.attributes.url` | string | (previous value) | HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"` | +| `data.relationships.users` | array | | Array of users part of the organization, only for configurations with `"destination_type:"` `"email"` | + +[notification-authenticity]: #notification-authenticity + +[notification-triggers]: #notification-triggers + +### Sample payload + +```json +{ + "data": { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000001/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "run:created", + "run:errored", + "run:needs_attention" + ], + } + } +} +``` + +### 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/notification-configurations/nc-W6VGEi8A7Cfoaf4K +``` + +### Sample response + +```json +{ + "data": { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000001/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "run:created", + "run:errored", + "run:needs_attention" + ], + "delivery-responses": [], + "created-at": "2019-01-08T21:34:28.367Z", + "updated-at": "2019-01-08T21:49:02.103Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" + } + }, +} +``` + +## Verify a notification configuration + +`POST /notification-configurations/:notification-configuration-id/actions/verify` + +| Parameter | Description | +| -------------------------------- | --------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to verify. | + +This will cause HCP Terraform to send a verification request for the specified configuration. If a response is received, it will be stored and returned in the `delivery-responses` attribute. More details in the [Notification Verification and Delivery Responses][] section above. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | ---------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully verified the notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | + +### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ/actions/verify +``` + +### Sample response + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "run:applying", + "run:completed", + "run:created", + "run:errored", + "run:needs_attention", + "run:planning" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +## Delete a notification configuration + +This endpoint deletes a notification configuration. + +`DELETE /notification-configurations/:notification-configuration-id` + +| Parameter | Description | +| -------------------------------- | --------------------------------------------------- | +| `:notification-configuration-id` | The id of the notification configuration to delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------------- | +| [204][] | None | Successfully deleted the notification configuration | +| [404][] | [JSON API error object][] | Notification configuration not found, or user unauthorized to perform action | + +### Sample request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ +``` + +## Team notification configuration + +Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs. + + + +@include 'tfc-package-callouts/notifications.mdx' + + + +### Create a team notification configuration + +By default, every team has a default email notification configuration with no users assigned. If a notification configuration has no users assigned, HCP Terraform sends email notifications to all team members. + +Use this endpoint to create a notification configuration to notify a team. + +`POST /teams/:team_id/notification-configurations` + +| Parameter | Description | +| ---------- | ------------------------------------------------- | +| `:team_id` | The ID of the team to create a configuration for. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "notification-configurations"`) | Successfully created a notification configuration | +| [400][] | [JSON API error object][] | Unable to complete verification request to destination URL | +| [404][] | [JSON API error object][] | Team not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +#### Request body + +This `POST` endpoint requires a JSON object with the following properties as a request payload. Properties without a default value are required. + +If `enabled` is set to `true`, HCP Terraform sends a verification request before saving the configuration. If this request does not receive a response or the response is not successful (HTTP 2xx), the configuration will not be saved. + +| Key path | Type | Default | Description | +| ----------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"notification-configuration"`. | +| `data.attributes.destination-type` | string | | Type of notification payload to send. Valid values are `"generic"`, `"email"`, `"slack"` or `"microsoft-teams"`. | +| `data.attributes.enabled` | bool | `false` | Disabled configurations will not send any notifications. | +| `data.attributes.name` | string | | Human-readable name for the configuration. | +| `data.attributes.token` | string or null | `null` | Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See [Notification Authenticity][notification-authenticity] for more details. | +| `data.attributes.triggers` | array | `[]` | Array of triggers for which this configuration will send notifications. See [Notification Triggers][notification-triggers] for more details and a list of allowed values. | +| `data.attributes.url` | string | | HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"` | +| `data.attributes.email_all_members` | bool | | Email all team members, only for configurations with `"destination_type:" "email"`. | +| `data.relationships.users` | array | | Array of users part of the organization, only for configurations with `"destination_type:"` `"email"` | + +[notification-authenticity]: #notification-authenticity + +[notification-triggers]: #notification-triggers + +#### Sample payload for generic notification configurations + +```json +{ + "data": { + "type": "notification-configuration", + "attributes": { + "destination-type": "generic", + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "triggers": [ + "change_request:created" + ] + } + } +} +``` + +#### Sample payload for email notification configurations + +```json +{ + "data": { + "type": "notification-configurations", + "attributes": { + "destination-type": "email", + "enabled": true, + "name": "Email teams about change requests", + "triggers": [ + "change_request:created" + ] + }, + "relationships": { + "users": { + "data": [ { "id": "organization-user-id", "type": "users" } ] + } + } + } +} +``` + +#### 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-6p5jTwJQXwqZBncC/notification-configurations +``` + +#### Sample response + +```json +{ + "data": { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "change_request:created" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2024 21:34:37 GMT" + ] + }, + "sent-at": "2024-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2024-01-08T21:32:14.125Z", + "updated-at": "2024-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "team-6p5jTwJQXwqZBncC", + "type": "teams" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } +} +``` + +### List team notification configurations + +Use this endpoint to list notification configurations for a team. + +`GET /teams/:team_id/notification-configurations` + +| Parameter | Description | +| ---------- | ------------------------------------------------ | +| `:team_id` | The ID of the teams to list configurations from. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 notification configurations per page. | + +#### Sample request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC/notification-configurations +``` + +#### Sample response + +```json +{ + "data": [ + { + "id": "nc-W6VGEi8A7Cfoaf4K", + "type": "notification-configurations", + "attributes": { + "enabled": false, + "name": "Slack: #devops", + "url": "https://hooks.slack.com/services/T00000000/BC012345/0PWCpQmYyD4bTTRYZ53q4w", + "destination-type": "slack", + "token": null, + "triggers": [ + "change_request:created" + ], + "delivery-responses": [], + "created-at": "2019-01-08T21:34:28.367Z", + "updated-at": "2019-01-08T21:34:28.367Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "team-TdeUVMWShTesDMME", + "type": "teams" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" + } + }, + { + "id": "nc-AeUQ2zfKZzW9TiGZ", + "type": "notification-configurations", + "attributes": { + "enabled": true, + "name": "Webhook server test", + "url": "https://httpstat.us/200", + "destination-type": "generic", + "token": null, + "triggers": [ + "change_request:created" + ], + "delivery-responses": [ + { + "url": "https://httpstat.us/200", + "body": "\"200 OK\"", + "code": "200", + "headers": { + "cache-control": [ + "private" + ], + "content-length": [ + "129" + ], + "content-type": [ + "application/json; charset=utf-8" + ], + "content-encoding": [ + "gzip" + ], + "vary": [ + "Accept-Encoding" + ], + "server": [ + "Microsoft-IIS/10.0" + ], + "x-aspnetmvc-version": [ + "5.1" + ], + "access-control-allow-origin": [ + "*" + ], + "x-aspnet-version": [ + "4.0.30319" + ], + "x-powered-by": [ + "ASP.NET" + ], + "set-cookie": [ + "ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us" + ], + "date": [ + "Tue, 08 Jan 2019 21:34:37 GMT" + ] + }, + "sent-at": "2019-01-08 21:34:37 UTC", + "successful": "true" + } + ], + "created-at": "2019-01-08T21:32:14.125Z", + "updated-at": "2019-01-08T21:34:37.274Z" + }, + "relationships": { + "subscribable": { + "data": { + "id": "team-XdeUVMWShTesDMME", + "type": "teams" + } + } + }, + "links": { + "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" + } + } + ] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/oauth-clients.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/oauth-clients.mdx new file mode 100644 index 0000000000..c16d5161c7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/oauth-clients.mdx @@ -0,0 +1,603 @@ +--- +page_title: /oauth-clients API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/oauth-clients` endpoint to manage + connections between VCS providers and organizations and projects. Learn how to + read, create, update, and destroy clients. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# OAuth client API reference + +An OAuth client represents the connection between an organization and a VCS provider. By default, you can globally access an OAuth client throughout the organization, or you can have scope access to one or more [projects](/terraform/enterprise/projects/manage). + +## List OAuth Clients + +`GET /organizations/:organization_name/oauth-clients` + +| Parameter | Description | +| -------------------- | ----------------------------- | +| `:organization_name` | The name of the organization. | + +This endpoint allows you to list VCS connections between an organization and a VCS provider (GitHub, Bitbucket, or GitLab) for use when creating or setting up workspaces. + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ---------------------- | +| [200][] | [JSON API document][] (`type: "oauth-clients"`) | Success | +| [404][] | [JSON API error object][] | Organization not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 oauth clients per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/oauth-clients +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckpK", + "type": "agent-pools" + }, + "links": { + "related": "/api/v2/agent-pools/apool-VsmjEMcYkShrckpK" + } + } + } + } + ] +} +``` + +## Show an OAuth Client + +`GET /oauth-clients/:id` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `:id` | The ID of the OAuth Client to show | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-clients"`) | Success | +| [404][] | [JSON API error object][] | OAuth Client not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K +``` + +### Sample Response + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckpK", + "type": "agent-pools" + }, + "links": { + "related": "/api/v2/agent-pools/apool-VsmjEMcYkShrckpK" + } + } + } + } +} +``` + +## Create an OAuth Client + +`POST /organizations/:organization_name/oauth-clients` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization that will be connected to the VCS provider. The organization must already exist in the system, and the user must have permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint allows you to create a VCS connection between an organization and a VCS provider (GitHub or GitLab) for use when creating or setting up workspaces. By using this API endpoint, you can provide a pre-generated OAuth token string instead of going through the process of creating a GitHub or GitLab OAuth Application. + +To learn how to generate one of these token strings for your VCS provider, you can read the following documentation: + +- [GitHub and GitHub Enterprise](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) +- [GitLab, GitLab Community Edition, and GitLab Enterprise Edition](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token) +- [Azure DevOps Server](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops-2019&tabs=preview-page) + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "oauth-clients"`) | OAuth Client successfully created | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"oauth-clients"`. | +| `data.attributes.service-provider` | string | | The VCS provider being connected with. Valid options are `"github"`, `"github_enterprise"`, `"gitlab_hosted"`, `"gitlab_community_edition"`, `"gitlab_enterprise_edition"`, or `"ado_server"`. | +| `data.attributes.name` | string | `null` | An optional display name for the OAuth Client. If left `null`, the UI will default to the display name of the VCS provider. | +| `data.attributes.key` | string | | The OAuth Client key. It can refer to a Consumer Key, Application Key, or another type of client key for the VCS provider. | +| `data.attributes.http-url` | string | | The homepage of your VCS provider (e.g. `"https://github.com"` or `"https://ghe.example.com"` or `"https://gitlab.com"`). | +| `data.attributes.api-url` | string | | The base URL as per your VCS provider's API documentation (e.g. `"https://api.github.com"`, `"https://ghe.example.com/api/v3"` or `"https://gitlab.com/api/v4"`). | +| `data.attributes.oauth-token-string` | string | | The token string you were given by your VCS provider | +| `data.attributes.private-key` | string | | **Required for Azure DevOps Server. Not used for any other providers.** The text of the SSH private key associated with your Azure DevOps Server account. | +| `data.attributes.secret` | string | | The OAuth client secret. For Bitbucket Data Center, the secret is the text of the SSH private key associated with your Bitbucket Data Center application link. | +| `data.attributes.rsa-public-key` | string | | **Required for Bitbucket Data Center in conjunction with the `secret`. Not used for any other providers.** The text of the SSH public key associated with your Bitbucket Data Center application link. | +| `data.attributes.organization-scoped` | boolean | | Whether or not the OAuth client is scoped to all projects and workspaces in the organization. Defaults to `true`. | +| `data.relationships.projects.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects are associated with the OAuth client. If `data.attributes.organization-scoped` is set to `false`, the OAuth client is only available to this list of projects. Each object in this list must contain a project `id` and use the `"projects"` type. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. | +| `data.relationships.agent-pool.data` | object | `{}` | The Agent Pool associated to the VCS connection. This pool will be responsible for forwarding VCS Provider API calls and cloning VCS repositories. | + +### Sample Payload + +```json +{ + "data": { + "type": "oauth-clients", + "attributes": { + "service-provider": "github", + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "oauth-token-string": "4306823352f0009d0ed81f1b654ac17a", + "organization-scoped": false + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +### 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/organizations/my-organization/oauth-clients +``` + +### Sample Response + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +## Update an OAuth Client + +`PATCH /oauth-clients/:id` + +| Parameter | Description | +| --------- | ------------------------------------- | +| `:id` | The ID of the OAuth Client to update. | + +Use caution when changing attributes with this endpoint; editing an OAuth client that workspaces are currently using can have unexpected effects. + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-clients"`) | The request was successful | +| [404][] | [JSON API error object][] | OAuth Client not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------------------------------- | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"oauth-clients"`. | +| `data.attributes.name` | string | (previous value) | An optional display name for the OAuth Client. If set to `null`, the UI will default to the display name of the VCS provider. | +| `data.attributes.key` | string | (previous value) | The OAuth Client key. It can refer to a Consumer Key, Application Key, or another type of client key for the VCS provider. | +| `data.attributes.secret` | string | (previous value) | The OAuth client secret. For Bitbucket Data Center, this secret is the text of the SSH private key associated with your Bitbucket Data Center application link. | +| `data.attributes.rsa-public-key` | string | (previous value) | **Required for Bitbucket Data Center in conjunction with the `secret`. Not used for any other providers.** The text of the SSH public key associated with your Bitbucket Data Center application link. | +| `data.attributes.organization-scoped` | boolean | (previous value) | Whether or not the OAuth client is available to all projects and workspaces in the organization. | +| `data.relationships.projects` | array\[object] | (previous value) | A list of resource identifier objects that defines which projects are associated with the OAuth client. If `data.attributes.organization-scoped` is set to `false`, the OAuth client is only available to this list of projects. Each object in this list must contain a project `id` and use the `"projects"` type. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. Sending an empty array clears all project assignments. | +| `data.relationships.agent-pool.data` | object | `{}` | The Agent Pool associated to the VCS connection. This pool will be responsible for forwarding VCS Provider API calls and cloning VCS repositories. | + +### Sample Payload + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "key": "key", + "secret": "secret", + "organization-scoped": false + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +### 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/oauth-clients/oc-XKFwG6ggfA9n7t1K +``` + +### Sample Response + +```json +{ + "data": { + "id": "oc-XKFwG6ggfA9n7t1K", + "type": "oauth-clients", + "attributes": { + "created-at": "2018-04-16T20:42:53.771Z", + "callback-url": "https://app.terraform.io/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a/callback", + "connect-path": "/auth/35936d44-842c-4ddd-b4d4-7c741383dc3a?organization_id=1", + "service-provider": "github", + "service-provider-display-name": "GitHub", + "name": null, + "http-url": "https://github.com", + "api-url": "https://api.github.com", + "key": null, + "rsa-public-key": null, + "organization-scoped": false + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "oauth-tokens": { + "data": [], + "links": { + "related": "/api/v2/oauth-tokens/ot-KaeqH4cy72VPXFQT" + } + }, + "agent-pool": { + "data": { + "id": "apool-VsmjEMcYkShrckzzz", + "type": "agent-pools" + } + } + } + } +} +``` + +## Destroy an OAuth Client + +`DELETE /oauth-clients/:id` + +| Parameter | Description | +| --------- | ------------------------------------- | +| `:id` | The ID of the OAuth Client to destroy | + +This endpoint allows you to remove an existing connection between an organization and a VCS provider (GitHub, Bitbucket, or GitLab). + +**Note:** Removing the OAuth Client will unlink workspaces that use this connection from their repositories, and these workspaces will need to be manually linked to another repository. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------ | +| [204][] | Empty response | The OAuth Client was successfully destroyed | +| [404][] | [JSON API error object][] | Organization or OAuth Client not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K +``` + +## Attach to a project + +`POST /oauth-clients/:id/relationships/projects` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the OAuth client to attach to a project. Use the [List OAuth Clients](#list-oauth-clients) endpoint to reference your OAuth client IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | OAuth Client not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects to attach the OAuth client to. These objects must contain `id` and `type` properties, and the `type` property must be `projects` (e.g. `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K/relationships/projects +``` + +## Detach an OAuth Client from projects + +`DELETE /oauth-clients/:id/relationships/projects` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the oauth client you want to detach from the specified projects. Use the "List OAuth Clients" endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | OAuth Client not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects are associated with the OAuth client. If `data.attributes.organization-scoped` is set to `false`, the OAuth client is only available to this list of projects. Each object in this list must contain a project `id` and use the `"projects"` type. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/oauth-clients/oc-XKFwG6ggfA9n7t1K/relationships/projects +``` + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| -------------- | --------------------------------------- | +| `oauth_tokens` | The OAuth tokens managed by this client | +| `projects` | The projects scoped to this client | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/oauth-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/oauth-tokens.mdx new file mode 100644 index 0000000000..83cdaaae1b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/oauth-tokens.mdx @@ -0,0 +1,264 @@ +--- +page_title: /oauth-tokens API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/oauth-tokens` endpoint to manage the + OAuth tokens that connect workspaces to VCS providers. Learn how to read, + update, and destroy tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# OAuth token API reference + +The `oauth-token` object represents a VCS configuration which includes the OAuth connection and the associated OAuth token. This object is used when creating a workspace to identify which VCS connection to use. + +## List OAuth Tokens + +List all the OAuth Tokens for a given OAuth Client + +`GET /oauth-clients/:oauth_client_id/oauth-tokens` + +| Parameter | Description | +| ------------------ | -------------------------- | +| `:oauth_client_id` | The ID of the OAuth Client | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-tokens"`) | Success | +| [404][] | [JSON API error object][] | OAuth Client not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ---------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 oauth tokens per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/oauth-clients/oc-GhHqb5rkeK19mLB8/oauth-tokens +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ot-hmAyP66qk2AMVdbJ", + "type": "oauth-tokens", + "attributes": { + "created-at":"2017-11-02T06:37:49.284Z", + "service-provider-user":"skierkowski", + "has-ssh-key": false + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-GhHqb5rkeK19mLB8", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-GhHqb5rkeK19mLB8" + } + } + }, + "links": { + "self": "/api/v2/oauth-tokens/ot-hmAyP66qk2AMVdbJ" + } + } + ] +} +``` + +## Show an OAuth Token + +`GET /oauth-tokens/:id` + +| Parameter | Description | +| --------- | --------------------------------- | +| `:id` | The ID of the OAuth token to show | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-tokens"`) | Success | +| [404][] | [JSON API error object][] | OAuth Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL +``` + +### Sample Response + +```json +{ + "data": { + "id": "ot-29t7xkUKiNC2XasL", + "type": "oauth-tokens", + "attributes": { + "created-at": "2018-08-29T14:07:22.144Z", + "service-provider-user": "EM26Jj0ikRsIFFh3fE5C", + "has-ssh-key": false + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-WMipGbuW8q7xCRmJ", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-WMipGbuW8q7xCRmJ" + } + } + }, + "links": { + "self": "/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL" + } + } +} +``` + +## Update an OAuth Token + +`PATCH /oauth-tokens/:id` + +| Parameter | Description | +| --------- | ----------------------------------- | +| `:id` | The ID of the OAuth token to update | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "oauth-tokens"`) | OAuth Token successfully updated | +| [404][] | [JSON API error object][] | OAuth Token not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------- | ------ | ------- | ------------------------- | +| `data.type` | string | | Must be `"oauth-tokens"`. | +| `data.attributes.ssh-key` | string | | **Optional.** The SSH key | + +### Sample Payload + +```json +{ + "data": { + "id": "ot-29t7xkUKiNC2XasL", + "type": "oauth-tokens", + "attributes": { + "ssh-key": "..." + } + } +} +``` + +### 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/oauth-tokens/ot-29t7xkUKiNC2XasL +``` + +### Sample Response + +```json +{ + "data": { + "id": "ot-29t7xkUKiNC2XasL", + "type": "oauth-tokens", + "attributes": { + "created-at": "2018-08-29T14:07:22.144Z", + "service-provider-user": "EM26Jj0ikRsIFFh3fE5C", + "has-ssh-key": false + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-WMipGbuW8q7xCRmJ", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-WMipGbuW8q7xCRmJ" + } + } + }, + "links": { + "self": "/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL" + } + } +} +``` + +## Destroy an OAuth Token + +`DELETE /oauth-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `:id` | The ID of the OAuth Token to destroy | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | Empty response | The OAuth Token was successfully destroyed | +| [404][] | [JSON API error object][] | OAuth Token not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/oauth-tokens/ot-29t7xkUKiNC2XasL +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-memberships.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-memberships.mdx new file mode 100644 index 0000000000..dec59d2968 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-memberships.mdx @@ -0,0 +1,497 @@ +--- +page_title: /organization-memberships API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/organization-memberships` endpoint to + manage membership in an organization. Invite, list, and remove members from + organizations. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organization memberships API reference + +Users are added to organizations by inviting them to join. Once accepted, they become members of the organization. The Organization Membership resource represents this membership. + +You can invite users who already have an account, as well as new users. If the user has an existing account with the same email address used to invite them, they can reuse the same login. + +-> **Note:** Once a user is a member of the organization, you can manage their team memberships using [the Team Membership API](/terraform/enterprise/api-docs/team-members). + +## Invite a User to an Organization + +`POST /organizations/:organization_name/organization-memberships` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the user will be invited to join. The inviting user must have permission to manage organization memberships. | + +-> **Note:** Organization membership management is restricted to members of the owners team, the owners [team API token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens), the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens), and users or teams with one of the [Team Management](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions) permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] | Successfully invited the user | +| [400][] | [JSON API error object][] | Unable to invite user due to organization limits | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Unable to invite user due to validation errors | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organization-memberships"`. | +| `data.attributes.email` | string | | The email address of the user to be invited. | +| `data.relationships.teams.data[]` | array\[object] | | A list of resource identifier objects that defines which teams the invited user will be a member of. These objects must contain `id` and `type` properties, and the `type` property must be `teams` (e.g. `{ "id": "team-GeLZkdnK6xAVjA5H", "type": "teams" }`). Obtain team IDs from the [List Teams](/terraform/enterprise/api-docs/teams#list-teams) endpoint. All users must be added to at least one team. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "email": "test@example.com" + }, + "relationships": { + "teams": { + "data": [ + { + "type": "teams", + "id": "team-GeLZkdnK6xAVjA5H" + } + ] + } + }, + "type": "organization-memberships" + } +} +``` + +### 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/organizations/my-organization/organization-memberships +``` + +### Sample Response + +```json +{ + "data": { + "id": "ou-nX7inDHhmC3quYgy", + "type": "organization-memberships", + "attributes": { + "status": "invited" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-GeLZkdnK6xAVjA5H", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-J8oxGmRk5eC2WLfX", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + "included": [ + { + "id": "user-J8oxGmRk5eC2WLfX", + "type": "users", + "attributes": { + "username": null, + "is-service-account": false, + "auth-method": "hcp_sso", + "avatar-url": "https://www.gravatar.com/avatar/55502f40dc8b7c769880b10874abc9d0?s=100&d=mm", + "two-factor": { + "enabled": false, + "verified": false + }, + "email": "test@example.com", + "permissions": { + "can-create-organizations": true, + "can-change-email": true, + "can-change-username": true, + "can-manage-user-tokens": false + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-J8oxGmRk5eC2WLfX/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-J8oxGmRk5eC2WLfX" + } + } + ] +} +``` + +## List Memberships for an Organization + +`GET /organizations/:organization_name/organization-memberships` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------- | +| `:organization_name` | The name of the organization to list the memberships of. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organization memberships are searchable by user name and email. | +| `filter[status]` | **Optional.** If specified, restricts results to those with the matching status value. Valid values are `invited` and `active`. | +| `filter[email]` | **Optional.** If specified, restricts results to those with a matching user email address. If multiple comma separated values are specified, results matching any of the values are returned. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 users per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ou-tTJph1AQVK5ZmdND", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-vaQqszES9JnuK4eB", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "ou-D6HPYFt4GzeBt3gB", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-oqCgH7NgTn95jTGc", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "ou-x1E2eBwYwusLDC7h", + "type": "organization-memberships", + "attributes": { + "status": "invited" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-UntUdBTHsVRQMzC8", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/organization-memberships?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "status-counts": { + "total": 3, + "active": 2, + "invited": 1 + }, + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 3 + } + } +} +``` + +## List User's Own Memberships + +`GET /organization-memberships` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organization-memberships +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ou-VgJgfbDVN3APUm2F", + "type": "organization-memberships", + "attributes": { + "status": "invited" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-4QrJKzxB3J5N4cJc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-vaQqszES9JnuK4eB", + "type": "users" + } + }, + "organization": { + "data": { + "id": "acme-corp", + "type": "organizations" + } + } + } + }, + { + "id": "ou-tTJph1AQVK5ZmdND", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-yUrEehvfG4pdmSjc", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-vaQqszES9JnuK4eB", + "type": "users" + } + }, + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ] +} +``` + +## Show a Membership + +`GET /organization-memberships/:organization_membership_id` + +| Parameter | Description | +| ----------------------------- | --------------------------- | +| `:organization_membership_id` | The organization membership | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organization-memberships"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization membership not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organization-memberships/ou-kit6GaMo3zPGCzWb +``` + +### Sample Response + +```json +{ + "data": { + "id": "ou-kit6GaMo3zPGCzWb", + "type": "organization-memberships", + "attributes": { + "status": "active" + }, + "relationships": { + "teams": { + "data": [ + { + "id": "team-97LkM7QciNkwb2nh", + "type": "teams" + } + ] + }, + "user": { + "data": { + "id": "user-hn6v2WK1naDpGadd", + "type": "users" + } + }, + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## Remove User from Organization + +`DELETE /organization-memberships/:organization_membership_id` + +| Parameter | Description | +| ----------------------------- | --------------------------- | +| `:organization_membership_id` | The organization membership | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------------------- | +| [204][] | Empty body | Successfully removed the user from the organization | +| [403][] | [JSON API error object][] | Unable to remove the user: you cannot remove yourself from organizations which you own | +| [404][] | [JSON API error object][] | Organization membership not found, or user unauthorized to perform action | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organization-memberships/ou-tTJph1AQVK5ZmdND +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `user` - The user associated with the membership. +- `teams` - Teams the user is a member of. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-tags.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-tags.mdx new file mode 100644 index 0000000000..bcebf92fbc --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-tags.mdx @@ -0,0 +1,230 @@ +--- +page_title: /tags API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's organization `/tags` endpoint to assign, + list, and delete tags for an organization. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organization tags API reference + +This API returns the list of tags used in workspaces across the organization. Tags can be added to this pool via workspaces. Tags deleted here will be removed from all other workspaces. Tags can be added, applied, removed and deleted in bulk. + +Tags are subject to the following rules: + +- Workspace tags or tags must be one or more characters, have a 255 character limit, and can include letters, numbers, colons, hyphens, and underscores. +- You can create tags for a workspace using the user interface or the API. After you create a tag, you can assign it to other workspaces in the same organization. +- You cannot create tags for a workspace using the CLI. +- You cannot set tags at the project level, so there is no tag inheritance from projects to workspaces. + +## List Tags + +`GET /organizations/:organization_name/tags` + +| Parameter | Description | +| -------------------- | ---------------------------------------------- | +| `:organization_name` | The name of the organization to list tags from | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------------------- | ---------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organization tags are searchable by name likeness. | +| `filter[exclude][taggable][id]` | **Optional.** If specified, omits organization's related workspace's tags. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 organization tags per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/tags +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tag-1", + "type": "tags", + "attributes": { + "name": "tag1", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 1 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "tag-2", + "type": "tags", + "attributes": { + "name": "tag2", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ] +} +``` + +## Delete tags + +This endpoint deletes one or more tags from an organization. The organization and tags must already +exist. Tags deleted here will be removed from all other resources. + +`DELETE /organizations/:organization_name/tags` + +| Parameter | Description | +| -------------------- | ------------------------------------------------ | +| `:organization_name` | The name of the organization to delete tags from | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [204][] | No Content | Successfully removed tags from organization | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that `type` and `id` are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ---------------------------- | +| `data[].type` | string | | Must be `"tags"`. | +| `data[].id` | string | | The id of the tag to remove. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tags", + "id": "tag-Yfha4YpPievQ8wJw" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/hashicorp/tags +``` + +## Sample Response + +No response body. + +Status code `204`. + +## Add workspaces to a tag + +`POST /tags/:tag_id/relationships/workspaces` + +| Parameter | Description | +| --------- | ---------------------------------------------------- | +| `:tag_id` | The ID of the tag that workspaces should have added. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------- | +| [204][] | No Content | Successfully added workspaces to tag | +| [404][] | [JSON API error object][] | Tag not found, or user unauthorized to perform action | + +### 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 `"workspaces"`. | +| `data[].id` | string | | The id of the workspace to add. | + +### 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/tags/tag-2/relationships/workspaces +``` + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-pmKTbUwH2VPiiTC4" + } + ] +} +``` + +### Sample Response + +No response body. + +Status code `204`. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-tokens.mdx new file mode 100644 index 0000000000..75894a177c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organization-tokens.mdx @@ -0,0 +1,148 @@ +--- +page_title: /organizations/authentication-token API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/organizations/authentication-token` + endpoint to generate and delete organization-level API tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organization tokens API reference + +## Generate a new organization token + +`POST /organizations/:organization_name/authentication-token` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------- | +| `:organization_name` | The name of the organization to generate a token for. | + +Generates a new [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens), replacing any existing token. + +Only members of the owners team, the owners [team API token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens), and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) can access this endpoint. + +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. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------- | +| [201][] | [JSON API document][] (`type: "authentication-tokens"`) | Success | +| [404][] | [JSON API error object][] | User not authorized | + +### 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-token"`. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the Organization Token will expire, in ISO 8601 format. If omitted or set to `null` the token will never expire. | + +### Sample Payload + +```json +{ + "data": { + "type": "authentication-token", + "attributes": { + "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/organizations/my-organization/authentication-token +``` + +### Sample Response + +```json +{ + "data": { + "id": "4111756", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:11:28.075Z", + "last-used-at": null, + "description": null, + "token": "ZgqYdzuvlv8Iyg.atlasv1.6nV7t1OyFls341jo1xdZTP72fN0uu9VL55ozqzekfmToGFbhoFvvygIRy2mwVAXomOE", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-62goNpx1ThQf689e", + "type": "users" + } + } + } + } +} +``` + +## Delete the organization token + +`DELETE /organizations/:organization/authentication-token` + +| Parameter | Description | +| -------------------- | --------------------------------------------- | +| `:organization_name` | Which organization's token should be deleted. | + +Only members of the owners team, the owners [team API token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens), and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) can access this endpoint. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------- | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | User not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/authentication-token +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organizations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organizations.mdx new file mode 100644 index 0000000000..dc7e999e44 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/organizations.mdx @@ -0,0 +1,987 @@ +--- +page_title: /organizations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/organizations` endpoint to create, + update, and destroy organizations, and read their entitlement sets, module + producers, and data retention policies. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Organizations API reference + +The Organizations API is used to list, show, create, update, and destroy organizations. + +## List Organizations + +`GET /organizations` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +Currently, this endpoint returns a full, unpaginated list of organizations (without pagination metadata) if both of the pagination query parameters are omitted. To avoid inconsistent behavior, we recommend always supplying pagination parameters when building against this API. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Organizations are searchable by name and notification email. This query takes precedence over the attribute specific searches `q[email]` or `q[name]`. | +| `q[email]` | **Optional.** A search query string. This query searches organizations by notification email. If used with `q[name]`, it returns organizations that match both queries. | +| `q[name]` | **Optional.** A search query string. This query searches organizations by name. If used with `q[email]`, it returns organizations that match both queries. | +| `page[number]` | **Optional.** Defaults to the first page, if omitted when `page[size]` is provided. | +| `page[size]` | **Optional.** Defaults to 20 organizations per page, if omitted when `page[number]` is provided. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations\?page\[number\]\=1\&page\[size\]\=20 +``` + +### Sample Response + +**Note:** Only HCP Terraform organizations return the `two-factor-conformant` and `assessments-enforced` properties. + +```json +{ + "data": [ + { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-Hysjx5eUviuKVCJY", + "created-at": "2021-08-24T23:10:04.675Z", + "email": "hashicorp@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "plan-identifier": "developer", + "cost-estimation-enabled": true, + "send-passing-statuses-for-untriggered-speculative-plans": true, + "aggregated-commit-status-enabled": false, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": true, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": true, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": true, + "can-update-oauth": true, + "can-update-sentinel": true, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": true, + "can-manage-tags": true, + "can-manage-varsets": true, + "can-read-varsets": true, + "can-manage-public-providers": true, + "can-create-provider": true, + "can-manage-public-modules": true, + "can-manage-custom-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-Hysjx5eUviuKVCJY", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + }, + { + "id": "hashicorp-two", + "type": "organizations", + "attributes": { + "external-id": "org-iJ5tr4WgB4WpA1hD", + "created-at": "2022-01-04T18:57:16.036Z", + "email": "hashicorp@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "plan-identifier": "free", + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": false, + "name": "hashicorp-two", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-varsets": true, + "can-read-varsets": true, + "can-manage-public-providers": true, + "can-create-provider": true, + "can-manage-public-modules": true, + "can-manage-custom-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-project": false + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp-two/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp-two/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-iJ5tr4WgB4WpA1hD", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp-two/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp-two/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp-two" + } + } + ], + "links": { + "self": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe-zone-b0c8608c.ngrok.io/api/v2/organizations?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show an Organization + +`GET /organizations/:organization_name` + +| Parameter | Description | +| -------------------- | ------------------------------------ | +| `:organization_name` | The name of the organization to show | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/hashicorp +``` + +### Sample Response + +**Note:** Only HCP Terraform organizations return the `two-factor-conformant` and `assessments-enforced` properties. + +```json +{ + "data": { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-WV6DfwfxxXvLfvfs", + "created-at": "2020-03-26T22:13:38.456Z", + "email": "user@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": false, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-public-modules": true, + "can-manage-public-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-provider": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-WV6DfwfxxXvLfvfs", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + } +} +``` + +## Create an Organization + +`POST /organizations` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "organizations"`) | The organization was successfully created | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------- | ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organizations"` | +| `data.attributes.name` | string | | Name of the organization | +| `data.attributes.email` | string | | Admin email address | +| `data.attributes.session-timeout` | integer | 20160 | Session timeout after inactivity (minutes) | +| `data.attributes.session-remember` | integer | 20160 | Session expiration (minutes) | +| `data.attributes.collaborator-auth-policy` | string | password | Authentication policy (`password` or `two_factor_mandatory`) | +| `data.attributes.cost-estimation-enabled` | boolean | false | Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to false. In Terraform Enterprise, you must also enable cost estimation in [Site Administration](/terraform/enterprise/admin/application/integration#cost-estimation-integration). | +| `data.attributes.send-passing-statuses-for-untriggered-speculative-plans` | boolean | false | Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false. In Terraform Enterprise, this setting is always false and cannot be changed but is also available in Site Administration. | +| `data.attributes.aggregated-commit-status-enabled` | boolean | true | Whether or not to aggregate VCS status updates for triggered workspaces. This is useful for monorepo projects with configuration spanning many workspaces. Defaults to `true`. You cannot use this option if `send-passing-statuses-for-untriggered-speculative-plans` is set to `true`. | +| `data.attributes.speculative-plan-management-enabled` | boolean | true | Whether or not to enable [Automatically cancel plan-only runs](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management). Defaults to `true`. | +| `data.attributes.owners-team-saml-role-id` | string | (nothing) | **Optional.** **SAML only** The name of the ["owners" team](/terraform/enterprise/saml/team-membership#managing-membership-of-the-owners-team) | +| `data.attributes.assessments-enforced` | boolean | (false) | Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`. | +| `data.attributes.allow-force-delete-workspaces` | boolean | (false) | Whether workspace administrators can [delete workspaces with resources under management](/terraform/enterprise/users-teams-organizations/organizations#general). If false, only organization owners may delete these workspaces. | +| `data.attributes.default-execution-mode` | boolean | `remote` | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`. | +| `data.attributes.default-agent-pool-id` | string | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`. | + +### Sample Payload + +```json +{ + "data": { + "type": "organizations", + "attributes": { + "name": "hashicorp", + "email": "user@example.com" + } + } +} +``` + +### 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/organizations +``` + +### Sample Response + +**Note:** Only HCP Terraform organizations return the `two-factor-conformant` and `assessments-enforced` properties. + +```json +{ + "data": { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-Bzyc2JuegvVLAibn", + "created-at": "2021-08-30T18:09:57.561Z", + "email": "user@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "allow-force-delete-workspaces": false, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-public-modules": true, + "can-manage-public-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-provider": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + }, + "included": [ + { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets", + "attributes": { + "agents": false, + "audit-logging": false, + "configuration-designer": true, + "cost-estimation": false, + "global-run-tasks": false, + "module-tests-generation": false, + "operations": true, + "policy-enforcement": false, + "policy-limit": null, + "policy-mandatory-enforcement-limit": null, + "policy-set-limit": null, + "private-module-registry": true, + "run-task-limit": null, + "run-task-mandatory-enforcement-limit": null, + "run-task-workspace-limit": null, + "run-tasks": false, + "self-serve-billing": true, + "sentinel": false, + "sso": false, + "state-storage": true, + "teams": false, + "usage-reporting": false, + "user-limit": 5, + "vcs-integrations": true, + "versioned-policy-set-limit": null + }, + "links": { + "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn" + } + } + ] +} +``` + +## Update an Organization + +`PATCH /organizations/:organization_name` + +| Parameter | Description | +| -------------------- | -------------------------------------- | +| `:organization_name` | The name of the organization to update | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The organization was successfully updated | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------- | ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"organizations"` | +| `data.attributes.name` | string | | Name of the organization | +| `data.attributes.email` | string | | Admin email address | +| `data.attributes.session-timeout` | integer | 20160 | Session timeout after inactivity (minutes) | +| `data.attributes.session-remember` | integer | 20160 | Session expiration (minutes) | +| `data.attributes.collaborator-auth-policy` | string | password | Authentication policy (`password` or `two_factor_mandatory`) | +| `data.attributes.cost-estimation-enabled` | boolean | false | Whether or not the cost estimation feature is enabled for all workspaces in the organization. Defaults to false. In Terraform Enterprise, you must also enable cost estimation in [Site Administration](/terraform/enterprise/admin/application/integration#cost-estimation-integration). | +| `data.attributes.send-passing-statuses-for-untriggered-speculative-plans` | boolean | false | Whether or not to send VCS status updates for untriggered speculative plans. This can be useful if large numbers of untriggered workspaces are exhausting request limits for connected version control service providers like GitHub. Defaults to false. In Terraform Enterprise, this setting is always false and cannot be changed but is also available in Site Administration. | +| `data.attributes.aggregated-commit-status-enabled` | boolean | true | Whether or not to aggregate VCS status updates for triggered workspaces. This is useful for monorepo projects with configuration spanning many workspaces. Defaults to `true`. You cannot use this option if `send-passing-statuses-for-untriggered-speculative-plans` is set to `true`. | +| `data.attributes.speculative-plan-management-enabled` | boolean | true | Whether or not to enable [Automatically cancel plan-only runs](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management). Defaults to `true`. | +| `data.attributes.owners-team-saml-role-id` | string | (nothing) | **Optional.** **SAML only** The name of the ["owners" team](/terraform/enterprise/saml/team-membership#managing-membership-of-the-owners-team) | +| `data.attributes.assessments-enforced` | boolean | false | Whether or not to compel health assessments for all eligible workspaces. When true, health assessments occur on all compatible workspaces, regardless of the value of the workspace setting `assessments-enabled`. When false, health assessments only occur for workspaces that opt in by setting `assessments-enabled: true`. | +| `data.attributes.allow-force-delete-workspaces` | boolean | false | Whether workspace administrators can [delete workspaces with resources under management](/terraform/enterprise/users-teams-organizations/organizations#general). If false, only organization owners may delete these workspaces. | +| `data.attributes.default-execution-mode` | boolean | `remote` | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use by default. Valid values are `remote`, `local`, and `agent`. | +| `data.attributes.default-agent-pool-id` | string | (previous value) | Required when `default-execution-mode` is set to `agent`. The ID of the agent pool belonging to the organization. Do _not_ specify this value if you set `execution-mode` to `remote` or `local`. | + +### Sample Payload + +```json +{ + "data": { + "type": "organizations", + "attributes": { + "email": "admin@example.com" + } + } +} +``` + +### 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 +``` + +### Sample Response + +**Note:** The `two-factor-conformant` and `assessments-enforced` properties are only returned from HCP Terraform organizations. + +```json +{ + "data": { + "id": "hashicorp", + "type": "organizations", + "attributes": { + "external-id": "org-Bzyc2JuegvVLAibn", + "created-at": "2021-08-30T18:09:57.561Z", + "email": "admin@example.com", + "session-timeout": null, + "session-remember": null, + "collaborator-auth-policy": "password", + "plan-expired": false, + "plan-expires-at": null, + "plan-is-trial": false, + "plan-is-enterprise": false, + "cost-estimation-enabled": false, + "send-passing-statuses-for-untriggered-speculative-plans": false, + "aggregated-commit-status-enabled": true, + "speculative-plan-management-enabled": true, + "name": "hashicorp", + "permissions": { + "can-update": true, + "can-destroy": true, + "can-access-via-teams": true, + "can-create-module": true, + "can-create-team": false, + "can-create-workspace": true, + "can-manage-users": true, + "can-manage-subscription": true, + "can-manage-sso": false, + "can-update-oauth": true, + "can-update-sentinel": false, + "can-update-ssh-keys": true, + "can-update-api-token": true, + "can-traverse": true, + "can-start-trial": true, + "can-update-agent-pools": false, + "can-manage-tags": true, + "can-manage-public-modules": true, + "can-manage-public-providers": false, + "can-manage-run-tasks": false, + "can-read-run-tasks": false, + "can-create-provider": false, + "can-create-project": true + }, + "fair-run-queuing-enabled": true, + "saml-enabled": false, + "owners-team-saml-role-id": null, + "two-factor-conformant": false, + "assessments-enforced": false, + "default-execution-mode": "remote" + }, + "relationships": { + "default-agent-pool": { + "data": null + }, + "oauth-tokens": { + "links": { + "related": "/api/v2/organizations/hashicorp/oauth-tokens" + } + }, + "authentication-token": { + "links": { + "related": "/api/v2/organizations/hashicorp/authentication-token" + } + }, + "entitlement-set": { + "data": { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets" + }, + "links": { + "related": "/api/v2/organizations/hashicorp/entitlement-set" + } + }, + "subscription": { + "links": { + "related": "/api/v2/organizations/hashicorp/subscription" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp" + } + } +} +``` + +## Destroy an Organization + +`DELETE /organizations/:organization_name` + +| Parameter | Description | +| -------------------- | --------------------------------------- | +| `:organization_name` | The name of the organization to destroy | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | | The organization was successfully destroyed | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp +``` + +### Sample Response + +The response body will be empty if successful. + +## Show the Entitlement Set + +This endpoint shows the [entitlements](/terraform/enterprise/api-docs#feature-entitlements) for an organization. + +`GET /organizations/:organization_name/entitlement-set` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------ | +| `:organization_name` | The name of the organization's entitlement set to view | + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "entitlement-sets"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/entitlement-set +``` + +### Sample Response + +```json +{ + "data": { + "id": "org-Bzyc2JuegvVLAibn", + "type": "entitlement-sets", + "attributes": { + "agents": false, + "audit-logging": false, + "configuration-designer": true, + "cost-estimation": false, + "global-run-tasks": false, + "module-tests-generation": false, + "operations": true, + "policy-enforcement": false, + "policy-limit": 5, + "policy-mandatory-enforcement-limit": null, + "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, + "run-task-workspace-limit": 10, + "run-tasks": false, + "self-serve-billing": true, + "sentinel": false, + "sso": false, + "state-storage": true, + "teams": false, + "usage-reporting": false, + "user-limit": 5, + "vcs-integrations": true, + "versioned-policy-set-limit": null + }, + "links": { + "self": "/api/v2/entitlement-sets/org-Bzyc2JuegvVLAibn" + } + } +} +``` + +## Show Module Producers + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. + + +This endpoint shows organizations that are configured to share modules with an organization through [Module Sharing](/terraform/enterprise/admin/application/module-sharing). + +`GET /organizations/:organization_name/relationships/module-producers` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------- | +| `:organization_name` | The name of the organization's module producers to view | + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "organizations"`) | The request was successful | +| [404][] | [JSON API error object][] | Organization not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 module producers per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "hc-nomad", + "type": "organizations", + "attributes": { + "name": "hc-nomad", + "external-id": "org-ArQSQMAkFQsSUZjB" + }, + "links": { + "self": "/api/v2/organizations/hc-nomad" + } + } + ], + "links": { + "self": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://tfe.example.com/api/v2/organizations/hashicorp/relationships/module-producers?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 1 + } + } +} +``` + +## Show data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`GET /organizations/:organization_name/relationships/data-retention-policy` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to show the data retention policy for. | + +This endpoint shows the data retention policy set explicitly on the organization. + +When no data retention policy is set for the organization, the endpoint returns the default policy configured for the Terraform Enterprise installation. Read more about [organization data retention policies](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies). + +For additional information, refer to [Data Retention Policy Types](/terraform/enterprise/api-docs/data-retention-policies#data-retention-policy-types) in the Terraform Enterprise documentation. + +## Create or update data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`POST /organizations/:organization_name/relationships/data-retention-policy` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to update the data retention policy for. | + +This endpoint creates a data retention policy for an organization or updates the existing policy. + +Read more about [organization data retention policies](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies). + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#create-or-update-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Remove data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`DELETE /organizations/:organization_name/relationships/data-retention-policy` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to remove the data retention policy for. | + +This endpoint removes the data retention policy explicitly set on an organization. +When the data retention policy is deleted, the organization inherits the default policy configured for the Terraform Enterprise installation. Refer to [Data Retention Policies](/terraform/enterprise/application-administration/general#data-retention-policies) for additional information. + +Refer to [Data Retention Policies](/terraform/enterprise/users-teams-organizations/organizations#data-retention-policies) for information about configuring data retention policies for an organization. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#remove-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ----------------- | ------------------------------------------------------------------------------------------ | +| `entitlement_set` | The entitlement set that determines which HCP Terraform features the organization can use. | + +## Relationships + +The following relationships may be present in various responses. + +| Resource Name | Description | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `module-producers` | Other organizations configured to share modules with the organization. | +| `oauth-tokens` | OAuth tokens associated with VCS configurations for the organization. | +| `authentication-token` | The API token for an organization. | +| `entitlement-set` | The entitlement set that determines which HCP Terraform features the organization can use. | +| `subscription` | The current subscription for an organization. | +| `default-agent-pool` | An organization's default agent pool. Set this value if your `default-execution-mode` is `agent`. | +| `data-retention-policy` | Specifies an organization's data retention policy. Refer to [Data Retention Policy APIs](/terraform/enterprise/api-docs/data-retention-policies) in the Terraform Enterprise documentation for more details. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/plan-exports.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/plan-exports.mdx new file mode 100644 index 0000000000..dabfc4fd47 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/plan-exports.mdx @@ -0,0 +1,226 @@ +--- +page_title: /plan-exports API reference for Terraform Enterprise +description: >- + Use the `/plan-exports` endpoint to manage plan exports for a Terraform run. + Create and show plan exports, or download and delete exported plan data. +source: terraform-docs-common +--- + +# Plan exports API reference + +Plan exports allow users to download data exported from the plan of a Run in a Terraform workspace. Currently, the only supported format for exporting plan data is to generate mock data for Sentinel. + +## Create a plan export + +`POST /plan-exports` + +This endpoint exports data from a plan in the specified format. The export process is asynchronous, and the resulting data becomes downloadable when its status is `"finished"`. The data is then available for one hour before expiring. After the hour is up, a new export can be created. + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "plan-exports"`) | Successfully created a plan export | +| [404][] | [JSON API error object][] | Plan not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.), or a plan export of the provided `data-type` is already pending or downloadable for this plan | + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------ | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"plan-exports"`. | +| `data.attributes.data-type` | string | | The format for the export. Currently, the only supported format is `"sentinel-mock-bundle-v0"`. | +| `data.relationships.plan.data` | object | | A JSON API relationship object that represents the plan being exported. This object must have a `type` of `plans`, and the `id` of a finished Terraform plan that does not already have a downloadable export of the specified `data-type` (e.g: `{"type": "plans", "id": "plan-8F5JFydVYAmtTjET"}`) | + +### Sample Payload + +```json +{ + "data": { + "type": "plan-exports", + "attributes": { + "data-type": "sentinel-mock-bundle-v0" + }, + "relationships": { + "plan": { + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans" + } + } + } + } +} +``` + +### 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/plan-exports +``` + +### Sample Response + +```json +{ + "data": { + "id": "pe-3yVQZvHzf5j3WRJ1", + "type": "plan-exports", + "attributes": { + "data-type": "sentinel-mock-bundle-v0", + "status": "queued", + "status-timestamps": { + "queued-at": "2019-03-04T22:29:53+00:00", + }, + }, + "relationships": { + "plan": { + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans" + } + } + }, + "links": { + "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1", + } + } +} +``` + +## Show a plan export + +`GET /plan-exports/:id` + +| Parameter | Description | +| --------- | ---------------------------------- | +| `id` | The ID of the plan export to show. | + +There is no endpoint to list plan exports. You can find IDs for plan exports in the +`relationships.exports` property of a plan object. + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "plan-exports"`) | The request was successful | +| [404][] | [JSON API error object][] | Plan export not found, or user unauthorized to perform action | + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1 +``` + +### Sample Response + +```json +{ + "data": { + "id": "pe-3yVQZvHzf5j3WRJ1", + "type": "plan-exports", + "attributes": { + "data-type": "sentinel-mock-bundle-v0", + "status": "finished", + "status-timestamps": { + "queued-at": "2019-03-04T22:29:53+00:00", + "finished-at": "2019-03-04T22:29:58+00:00", + "expired-at": "2019-03-04T23:29:58+00:00" + }, + }, + "relationships": { + "plan": { + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans" + } + } + }, + "links": { + "self": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1", + "download": "/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download" + } + } +} +``` + +## Download exported plan data + +`GET /plan-exports/:id/download` + +This endpoint generates a temporary URL to the location of the exported plan data in a `.tar.gz` archive, and then redirects to that link. If using a client that can follow redirects, you can use this endpoint to save the `.tar.gz` archive locally without needing to save the temporary URL. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [302][] | HTTP Redirect | Plan export found and temporary download URL generated | +| [404][] | [JSON API error object][] | Plan export not found, or user unauthorized to perform action | + +[302]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --location \ + https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1/download \ + > export.tar.gz +``` + +## Delete exported plan data + +`DELETE /plan-exports/:id` + +Plan exports expire after being available for one hour, but they can be deleted manually as well. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | No content | Plan export deleted successfully | +| [404][] | [JSON API error object][] | Plan export not found, or user unauthorized to perform action | + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + -X DELETE \ + https://app.terraform.io/api/v2/plan-exports/pe-3yVQZvHzf5j3WRJ1 +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/plans.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/plans.mdx new file mode 100644 index 0000000000..aee7e4eaef --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/plans.mdx @@ -0,0 +1,203 @@ +--- +page_title: /plans API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/plans` endpoint to read a Terraform run + plan or generate JSON-formatted execution plans. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[307]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Plans API reference + +A plan represents the execution plan of a Run in a Terraform workspace. + +## Attributes + +### Plan States + +The plan state is found in `data.attributes.status`, and you can reference the following list of possible states. + +| State | Description | +| ------------------------- | ----------------------------------------------------------------------------- | +| `pending` | The initial status of a plan once it has been created. | +| `managed_queued`/`queued` | The plan has been queued, awaiting backend service capacity to run terraform. | +| `running` | The plan is running. | +| `errored` | The plan has errored. This is a final state. | +| `canceled` | The plan has been canceled. This is a final state. | +| `finished` | The plan has completed successfully. This is a final state. | +| `unreachable` | The plan will not run. This is a final state. | + +## Show a plan + +`GET /plans/:id` + +| Parameter | Description | +| --------- | --------------------------- | +| `id` | The ID of the plan to show. | + +There is no endpoint to list plans. You can find the ID for a plan in the +`relationships.plan` property of a run object. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "plans"`) | The request was successful | +| [404][] | [JSON API error object][] | Plan not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/plans/plan-8F5JFydVYAmtTjET +``` + +### Sample Response + +```json +{ + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans", + "attributes": { + "execution-details": { + "mode": "remote", + }, + "generated-configuration": false, + "has-changes": true, + "resource-additions": 0, + "resource-changes": 1, + "resource-destructions": 0, + "resource-imports": 0, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-07-02T22:29:53+00:00", + "pending-at": "2018-07-02T22:29:53+00:00", + "started-at": "2018-07-02T22:29:54+00:00", + "finished-at": "2018-07-02T22:29:58+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg" + }, + "relationships": { + "state-versions": { + "data": [] + } + }, + "links": { + "self": "/api/v2/plans/plan-8F5JFydVYAmtTjET", + "json-output": "/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output" + } + } +} +``` + +_Using HCP Terraform agents_ + +[HCP Terraform agents](/terraform/enterprise/api-docs/agents) allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. When a workspace is set to use the agent execution mode, the plan response will include additional details about the agent pool and agent used. + +```json +{ + "data": { + "id": "plan-8F5JFydVYAmtTjET", + "type": "plans", + "attributes": { + "execution-details": { + "agent-id": "agent-S1Y7tcKxXPJDQAvq", + "agent-name": "agent_01", + "agent-pool-id": "apool-Zigq2VGreKq7nwph", + "agent-pool-name": "first-pool", + "mode": "agent", + }, + "generated-configuration": false, + "has-changes": true, + "resource-additions": 0, + "resource-changes": 1, + "resource-destructions": 0, + "resource-imports": 0, + "status": "finished", + "status-timestamps": { + "queued-at": "2018-07-02T22:29:53+00:00", + "pending-at": "2018-07-02T22:29:53+00:00", + "started-at": "2018-07-02T22:29:54+00:00", + "finished-at": "2018-07-02T22:29:58+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6OFA1eEdlSFVHRSs4YUcwaW83a1dRRDA0U2E3T3FiWk1HM2NyQlNtcS9JS1hHN3dmTXJmaFhEYTlHdTF1ZlgxZ2wzVC9kVTlNcjRPOEJkK050VFI3U3dvS2ZuaUhFSGpVenJVUFYzSFVZQ1VZYno3T3UyYjdDRVRPRE5pbWJDVTIrNllQTENyTndYd1Y0ak1DL1dPVlN1VlNxKzYzbWlIcnJPa2dRRkJZZGtFeTNiaU84YlZ4QWs2QzlLY3VJb3lmWlIrajF4a1hYZTlsWnFYemRkL2pNOG9Zc0ZDakdVMCtURUE3dDNMODRsRnY4cWl1dUN5dUVuUzdnZzFwL3BNeHlwbXNXZWRrUDhXdzhGNnF4c3dqaXlZS29oL3FKakI5dm9uYU5ZKzAybnloREdnQ3J2Rk5WMlBJemZQTg" + }, + "relationships": { + "state-versions": { + "data": [] + } + }, + "links": { + "self": "/api/v2/plans/plan-8F5JFydVYAmtTjET", + "json-output": "/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output" + } + } +} +``` + +## Retrieve the JSON execution plan + +`GET /plans/:id/json-output` + +`GET /runs/:id/plan/json-output` + +These endpoints generate a temporary authenticated URL to the location of the [JSON formatted execution plan](/terraform/internals/json-format#format-summary). When successful, this endpoint responds with a temporary redirect that should be followed. If using a client that can follow redirects, you can use this endpoint to save the `.json` file locally without needing to save the temporary URL. + +This temporary URL provided by the redirect has a life of **1 minute**, and should not be relied upon beyond the initial request. If you need repeat access, you should use this endpoint to generate a new URL each time. + +-> **Note:** This endpoint is available for plans using Terraform 0.12 and later. For Terraform Enterprise, this endpoint is available from v202005-1, and its stability was improved in v202007-1. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) that has admin level access to the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------- | +| [204][] | No Content | Plan JSON supported, but plan has not yet completed. | +| [307][] | Temporary Redirect | Plan JSON found and temporary download URL generated | +| [422][] | [JSON API error object][] | Plan does not use a supported version of terraform (< 0.12.X) | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --location \ + https://app.terraform.io/api/v2/plans/plan-8F5JFydVYAmtTjET/json-output | + > json-output.json +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policies.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policies.mdx new file mode 100644 index 0000000000..64118b2364 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policies.mdx @@ -0,0 +1,564 @@ +--- +page_title: /policies API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policies` endpoint to list, show, create, + upload, update, and delete Sentinel and OPA policies. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policies API reference + +Policies are rules that HCP Terraform enforces on Terraform runs. You can use policies to validate that the Terraform plan complies with security rules and best practices. HCP Terraform policy enforcement lets you use the policy-as-code frameworks Sentinel and Open Policy Agent (OPA) to apply policy checks to HCP Terraform workspaces. Refer to [Policy Enforcement](/terraform/enterprise/policy-enforcement) for more details. + +[Policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) are collections of policies that you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces, in your organization. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set and displays the results in the UI. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +This page documents the API endpoints to create, read, update, and delete policies in an organization. To manage policy sets, use the [Policy Sets API](/terraform/enterprise/api-docs/policy-sets). To manage the policy results, use the [Runs API](/terraform/enterprise/api-docs/run). + +## Create a Policy + +`POST /organizations/:organization_name/policies` + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The organization to create the policy in. The organization must already exist in the system, and the token authenticating the API request must have permission to manage policies. (([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +\[permissions-citation]: #intentionally-unused---keep-for-maintainers) + +This creates a new policy object for the organization, but does not upload the actual policy code. After creation, you must use the [Upload a Policy endpoint (below)](#upload-a-policy) with the new policy's upload path. (This endpoint's response body includes the upload path in its `links.upload` property.) + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policies"`) | Successfully created a policy | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------- | -------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policies"`. | +| `data.attributes.name` | string | | The name of the policy, which can include letters, numbers, `-`, and `_`. You cannot modify this name after creation. | +| `data.attributes.description` | string | `null` | Text describing the policy's purpose. This field supports Markdown and appears in the HCP Terraform UI. | +| `data.attributes.kind` | string | `sentinel` | The policy-as-code framework for the policy. Valid values are `"sentinel"` and `"opa"`. | +| `data.attributes.query` | string | | The OPA query to run. Only valid for OPA policies. | +| `data.attributes.enforcement-level` | string | | The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | +| `data.attributes.enforce` | array\[object] | | **DEPRECATED** Use `enforcement-level` instead. An array of enforcement configurations that map policy file paths to their enforcement modes. Policies support a single file, so this array should consist of a single element. For Sentinel, if the path in the enforcement map does not match the Sentinel policy (`.sentinel`), then HCP Terraform uses the default `hard-mandatory` enforcement level. For OPA, the default enforcement level is `advisory`. | +| `data.attributes.enforce[].path` | string | | **DEPRECATED** For Sentinel, must be `.sentinel`, where `` has the same value as `data.attributes.name`. For OPA, must be `.rego`. | +| `data.attributes.enforce[].mode` | string | | **DEPRECATED** Use `enforcement-level` instead. The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | +| `data.relationships.policy-sets.data[]` | array\[object] | `[]` | A list of resource identifier objects to define which policy sets include the new policy. These objects must contain `id` and `type` properties, and the `type` property must be `policy-sets`. For example,`{ "id": "polset-3yVQZvHzf5j3WRJ1","type": "policy-sets" }`. | + +### Sample Payload (Sentinel) + +```json +{ + "data": { + "attributes": { + "enforcement-level": "hard-mandatory", + "name": "my-example-policy", + "description": "An example policy.", + "kind": "sentinel" + }, + "relationships": { + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "type": "policies" + } +} +``` + +### Sample Payload (OPA) + +-> **Note**: We have deprecated the `enforce` property in requests and responses but continue to provide it for backward compatibility. The below sample uses the deprecated `enforce` property. + +```json +{ + "data": { + "attributes": { + "enforce": [ + { + "path": "my-example-policy.rego", + "mode": "advisory" + } + ], + "name": "my-example-policy", + "description": "An example policy.", + "kind": "opa", + "query": "terraform.main" + }, + "relationships": { + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "type": "policies" + } +} +``` + +### 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/organizations/my-organization/policies +``` + +### Sample Response (Sentinel) + +```json +{ + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policies", + "attributes": { + "name":"my-example-policy", + "description":"An example policy.", + "enforcement-level":"advisory", + "enforce": [ + { + "path":"my-example-policy.sentinel", + "mode":"advisory" + } + ], + "policy-set-count": 1, + "updated-at": null + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "links": { + "self":"/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload" + } + } +} +``` + +### Sample Response (OPA) + +```json +{ + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policies", + "attributes": { + "name":"my-example-policy", + "description":"An example policy.", + "kind": "opa", + "query": "terraform.main", + "enforcement-level": "advisory", + "enforce": [ + { + "path":"my-example-policy.rego", + "mode":"advisory" + } + ], + "policy-set-count": 1, + "updated-at": null + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "links": { + "self":"/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload" + } + } +} +``` + +## Show a Policy + +`GET /policies/:policy_id` + +| Parameter | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:policy_id` | The ID of the policy to show. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policies"`) | The request was successful | +| [404][] | [JSON API error object][] | Policy not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/policies/pol-oXUppaX2ximkqp8w +``` + +### Sample Response + +```json +{ + "data": { + "id": "pol-oXUppaX2ximkqp8w", + "type": "policies", + "attributes": { + "name": "my-example-policy", + "description":"An example policy.", + "kind": "sentinel", + "enforcement-level": "soft-mandatory", + "enforce": [ + { + "path": "my-example-policy.sentinel", + "mode": "soft-mandatory" + } + ], + "policy-set-count": 1, + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policy-sets": { + "data": [ + { "id": "polset-3yVQZvHzf5j3WRJ1", "type": "policy-sets" } + ] + } + }, + "links": { + "self": "/api/v2/policies/pol-oXUppaX2ximkqp8w", + "upload": "/api/v2/policies/pol-oXUppaX2ximkqp8w/upload", + "download": "/api/v2/policies/pol-oXUppaX2ximkqp8w/download" + } + } +} +``` + +## Upload a Policy + +`PUT /policies/:policy_id/upload` + +| Parameter | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:policy_id` | The ID of the policy to upload code to. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding the policy ID. The ID also appears in the response when you create a policy. | + +This endpoint uploads code to an existing Sentinel or OPA policy. + +-> **Note**: This endpoint does not use JSON-API's conventions for HTTP headers and body serialization. + +-> **Note**: This endpoint limits the size of uploaded policies to 10MB. If a larger payload is uploaded, an HTTP 413 error will be returned, and the policy will not be saved. Consider refactoring policies into multiple smaller, more concise documents if you reach this limit. + +### Request Body + +This PUT endpoint requires the text of a valid Sentinel or OPA policy with a `Content-Type` of `application/octet-stream`. + +- Refer to [Defining Sentinel Policies](/terraform/enterprise/policy-enforcement/sentinel) for details about writing Sentinel code. +- Refer to [Defining OPA Policies](/terraform/enterprise/policy-enforcement/opa) for details about writing OPA code. + +### Sample Payload + +```plain +main = rule { true } +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @payload.file \ + https://app.terraform.io/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload +``` + +## Update a Policy + +`PATCH /policies/:policy_id` + +| Parameter | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:policy_id` | The ID of the policy to update. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding IDs. | + +This endpoint can update the enforcement mode of an existing policy. To update the policy code itself, use the upload endpoint. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policies"`) | Successfully updated the policy | +| [404][] | [JSON API error object][] | Policy not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policies"`. | +| `data.attributes.description` | string | `null` | Text describing the policy's purpose. This field supports Markdown and appears in the HCP Terraform UI. | +| `data.attributes.query` | string | | The OPA query to run. This is only valid for OPA policies. | +| `data.attributes.enforcement-level` | string | | The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | +| `data.attributes.enforce` | array\[object] | | **DEPRECATED** Use `enforcement-level` instead. An array of enforcement configurations that map policy file paths to their enforcement modes. Policies support a single file, so this array should consist of a single element. For Sentinel, if the path in the enforcement map does not match the Sentinel policy (`.sentinel`), then HCP Terraform uses the default `hard-mandatory` enforcement level. For OPA, the default enforcement level is `advisory`. | +| `data.attributes.enforce[].path` | string | | **DEPRECATED** For Sentinel, must be `.sentinel`, where `` has the same value as `data.attributes.name`. For OPA, must be `.rego`. | +| `data.attributes.enforce[].mode` | string | | **DEPRECATED** Use `enforcement-level` instead. The enforcement level of the policy. For Sentinel, valid values are `"hard-mandatory"`, `"soft-mandatory"`, and `"advisory"`. For OPA, Valid values are `"mandatory"`and `"advisory"`. Refer to [Managing Policies](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "enforcement-level": "soft-mandatory" + }, + "type":"policies" + } +} +``` + +### 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/policies/pol-u3S5p2Uwk21keu1s +``` + +### Sample Response + +```json +{ + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policies", + "attributes": { + "name":"my-example-policy", + "description":"An example policy.", + "kind": "sentinel", + "enforcement-level": "soft-mandatory", + "enforce": [ + { + "path":"my-example-policy.sentinel", + "mode":"soft-mandatory" + } + ], + "policy-set-count": 0, + "updated-at":"2017-10-10T20:58:04.621Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + }, + "links": { + "self":"/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload", + "download":"/api/v2/policies/pol-u3S5p2Uwk21keu1s/download" + } + } +} +``` + +## List Policies + +`GET /organizations/:organization_name/policies` + +| Parameter | Description | +| -------------------- | -------------------------------------- | +| `:organization_name` | The organization to list policies for. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | Array of [JSON API document][]s (`type: "policies"`) | Success | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); 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 will return the first page. | | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 policies per page. | | +| `search[name]` | **Optional.** Allows searching the organization's policies by name. | | +| `filter[kind]` | **Optional.** If specified, restricts results to those with the matching policy kind value. Valid values are `sentinel` and `opa` | | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/policies +``` + +### Sample Response + +```json +{ + "data": [ + { + "attributes": { + "enforcement-level": "advisory", + "enforce": [ + { + "mode": "advisory", + "path": "my-example-policy.sentinel" + } + ], + "name": "my-example-policy", + "description": "An example policy.", + "policy-set-count": 0, + "updated-at": "2017-10-10T20:52:13.898Z", + "kind": "sentinel" + }, + "id": "pol-u3S5p2Uwk21keu1s", + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + }, + "links": { + "download": "/api/v2/policies/pol-u3S5p2Uwk21keu1s/download", + "self": "/api/v2/policies/pol-u3S5p2Uwk21keu1s", + "upload": "/api/v2/policies/pol-u3S5p2Uwk21keu1s/upload" + }, + "type": "policies" + }, + { + "id":"pol-vM2rBfj7V2Faq8By", + "type":"policies", + "attributes":{ + "name":"policy1", + "description":null, + "enforcement-level": "advisory", + "enforce":[ + { + "path":"policy1.rego", + "mode":"advisory" + } + ], + "policy-set-count":1, + "updated-at":"2022-09-13T04:57:43.516Z", + "kind":"opa", + "query":"data.terraform.rules.policy1.rule" + }, + "relationships":{ + "organization":{ + "data":{ + "id":"hashicorp", + "type":"organizations" + } + }, + "policy-sets":{ + "data":[ + { + "id":"polset-FYu3k5WY5eecwwdt", + "type":"policy-sets" + } + ] + } + }, + "links":{ + "self":"/api/v2/policies/pol-vM2rBfj7V2Faq8By", + "upload":"/api/v2/policies/pol-vM2rBfj7V2Faq8By/upload", + "download":"/api/v2/policies/pol-vM2rBfj7V2Faq8By/download" + } + } + ] +} +``` + +## Delete a Policy + +`DELETE /policies/:policy_id` + +| Parameter | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:policy_id` | The ID of the policy to delete. Refer to [List Policies](/terraform/enterprise/api-docs/policies#list-policies) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the policy | +| [404][] | [JSON API error object][] | Policy not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/policies/pl-u3S5p2Uwk21keu1s +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | ------------------------------------------------------ | +| `policy_sets` | Policy sets that any returned policies are members of. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-checks.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-checks.mdx new file mode 100644 index 0000000000..621f40d368 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-checks.mdx @@ -0,0 +1,265 @@ +--- +page_title: /policy-checks API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policy-checks` endpoint to manage and + override the Sentinel policy checks that HCP Terraform performs during a run. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy checks API reference + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policy checks are the default workflow for Sentinel. Policy checks use the latest version of the Sentinel runtime and have access to cost estimation data. +This set of APIs provides endpoints to get, list, and override policy checks. + +~> **Warning:** Policy checks are deprecated and will be permanently removed in August 2025. We recommend that you start using policy evaluations to avoid disruptions. + +## List Policy Checks + +This endpoint lists the policy checks in a run. + +-> **Note**: The `sentinel` hash in the `result` attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk. + +`GET /runs/:run_id/policy-checks` + +| Parameter | Description | +| --------- | -------------------------------------------- | +| `run_id` | The ID of the run to list policy checks for. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 policy checks per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/runs/run-CZcmD7eagjhyXavN/policy-checks +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "polchk-9VYRc9bpfJEsnwum", + "type": "policy-checks", + "attributes": { + "result": { + "result": false, + "passed": 0, + "total-failed": 1, + "hard-failed": 0, + "soft-failed": 1, + "advisory-failed": 0, + "duration-ms": 0, + "sentinel": {...} + }, + "scope": "organization", + "status": "soft_failed", + "status-timestamps": { + "queued-at": "2017-11-29T20:02:17+00:00", + "soft-failed-at": "2017-11-29T20:02:20+00:00" + }, + "actions": { + "is-overridable": true + }, + "permissions": { + "can-override": false + } + }, + "relationships": { + "run": { + "data": { + "id": "run-veDoQbv6xh6TbnJD", + "type": "runs" + } + } + }, + "links": { + "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output" + } + } + ] +} +``` + +## Show Policy Check + +This endpoint gets information about a specific policy check ID. Policy check IDs can appear in audit logs. + +-> **Note**: The `sentinel` hash in the `result` attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk. + +`GET /policy-checks/:id` + +| Parameter | Description | +| --------- | ----------------------------------- | +| `id` | The ID of the policy check to show. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum +``` + +### Sample Response + +```json +{ + "data": { + "id": "polchk-9VYRc9bpfJEsnwum", + "type": "policy-checks", + "attributes": { + "result": { + "result": false, + "passed": 0, + "total-failed": 1, + "hard-failed": 0, + "soft-failed": 1, + "advisory-failed": 0, + "duration-ms": 0, + "sentinel": {...} + }, + "scope": "organization", + "status": "soft_failed", + "status-timestamps": { + "queued-at": "2017-11-29T20:02:17+00:00", + "soft-failed-at": "2017-11-29T20:02:20+00:00" + }, + "actions": { + "is-overridable": true + }, + "permissions": { + "can-override": false + } + }, + "relationships": { + "run": { + "data": { + "id": "run-veDoQbv6xh6TbnJD", + "type": "runs" + } + } + }, + "links": { + "output": "/api/v2/policy-checks/polchk-9VYRc9bpfJEsnwum/output" + } + } +} +``` + +## Override Policy + +This endpoint overrides a soft-mandatory or warning policy. + +-> **Note**: The `sentinel` hash in the `result` attribute structure represents low-level Sentinel details generated by the policy engine. The keys or structure may change over time. Use the data in this hash at your own risk. + +`POST /policy-checks/:id/actions/override` + +| Parameter | Description | +| --------- | --------------------------------------- | +| `id` | The ID of the policy check to override. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/actions/override +``` + +### Sample Response + +```json +{ + "data": { + "id": "polchk-EasPB4Srx5NAiWAU", + "type": "policy-checks", + "attributes": { + "result": { + "result": false, + "passed": 0, + "total-failed": 1, + "hard-failed": 0, + "soft-failed": 1, + "advisory-failed": 0, + "duration-ms": 0, + "sentinel": {...} + }, + "scope": "organization", + "status": "overridden", + "status-timestamps": { + "queued-at": "2017-11-29T20:13:37+00:00", + "soft-failed-at": "2017-11-29T20:13:40+00:00", + "overridden-at": "2017-11-29T20:14:11+00:00" + }, + "actions": { + "is-overridable": true + }, + "permissions": { + "can-override": false + } + }, + "links": { + "output": "/api/v2/policy-checks/polchk-EasPB4Srx5NAiWAU/output" + } + } +} +``` + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| --------------- | ------------------------------------- | +| `run` | The run this policy check belongs to. | +| `run.workspace` | The associated workspace of the run. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-evaluations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-evaluations.mdx new file mode 100644 index 0000000000..9733bfbed1 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-evaluations.mdx @@ -0,0 +1,288 @@ +--- +page_title: /policy-evaluations API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policy-evaluations` endpoint to read + policy outcomes and evaluations from Sentinel and OPA policies that HCP + Terraform performs during a Terraform run. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy evaluations API reference + +Policy evaluations are run within the [HCP Terraform agents](/terraform/enterprise/api-docs/agents) in HCP Terraform's infrastructure. Policy evaluations do not have access to cost estimation data. +This set of APIs provides endpoints to list and get policy evaluations and policy outcomes. + +## List Policy Evaluations in the Task Stage + +Each run passes through several stages of action (pending, plan, policy check, apply, and completion), and shows the progress through those stages as [run states](/terraform/enterprise/run/states). +This endpoint allows you to list policy evaluations that are part of the task stage. + +`GET /task-stages/:task_stage_id/policy-evaluations` + +| Parameter | Description | +| ---------------- | ------------------------- | +| `:task_stage_id` | The task stage ID to get. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------- | +| [200][] | [JSON API document][] | Success | +| [404][] | [JSON API error object][] | Task stage not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not 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 agent pools per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/policy-evaluations +``` + +### Sample Response + +```json +{ + "data":[ + { + "id":"poleval-8Jj9Hfoz892D9WMX", + "type":"policy-evaluations", + "attributes":{ + "status":"passed", + "policy-kind":"opa", + "policy-tool-version": "0.44.0", + "result-count": { + "advisory-failed":0, + "errored":0, + "mandatory-failed":0, + "passed":1 + } + "status-timestamps":{ + "passed-at":"2022-09-16T01:40:30+00:00", + "queued-at":"2022-09-16T01:40:04+00:00", + "running-at":"2022-09-16T01:40:08+00:00" + }, + "created-at":"2022-09-16T01:39:07.782Z", + "updated-at":"2022-09-16T01:40:30.010Z" + }, + "relationships":{ + "policy-attachable":{ + "data":{ + "id":"ts-yxskot8Gz5yHa38W", + "type":"task-stages" + } + }, + "policy-set-outcomes":{ + "links":{ + "related":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes" + } + } + }, + "links":{ + "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX" + } + } + ] +} +``` + +## List Policy Outcomes + +`GET /policy-evaluations/:policy_evaluation_id/policy-set-outcomes` + +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------- | +| `:policy_evaluation_id` | The ID of the policy evaluation the outcome belongs to get | + +This endpoint allows you to list policy set outcomes that are part of the policy evaluation. + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------- | +| [200][] | [JSON API document][] | Success | +| [404][] | [JSON API error object][] | Policy evaluation not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not 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 policy sets per page. | +| `filter[n][status]` | **Optional.** If omitted, the endpoint returns all policies regardless of status. Must be either "passed", "failed", or "errored". | +| `filter[n][enforcementLevel]` | **Optional.** Only used if paired with a non-errored status filter. Must be either "advisory" or "mandatory." | + +-> **Note**: You can use `filter[n]` to combine combinations of statuses and enforcement levels. Policy outcomes with an errored status do not have an enforcement level. + +### Sample Request + +The following example requests demonstrate how to call the `policy-set-outcomes` endpoint using cuRL. + +#### All Policy Outcomes + +The following example call returns all policy set outcomes. + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes +``` + +#### Failed and Errored Policy Outcomes + +The following example call filters the response so that it only contains failed outcomes and errors. + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?filter[0][status]=errored&filter[1][status]=failed&filter[1][enforcementLevel]=mandatory +``` + +### Sample Response + +The following example response shows that the `policyVCS` policy failed. + +```json +{ + "data":[ + { + "id":"psout-cu8E9a97LBepZZXd", + "type":"policy-set-outcomes", + "attributes":{ + "outcomes":[ + { + "enforcement_level":"advisory", + "query":"data.terraform.main.main", + "status":"failed", + "policy_name":"policyVCS", + "description":"" + } + ], + "error":"", + "overridable":true, + "policy-set-name":"opa-policies-vcs", + "policy-set-description":null, + "result-count":{ + "advisory-failed":1, + "errored":0, + "mandatory-failed":0, + "passed":0 + }, + "policy-tool-version": "0.54.0" + }, + "relationships":{ + "policy-evaluation":{ + "data":{ + "id":"poleval-8Jj9Hfoz892D9WMX", + "type":"policy-evaluations" + } + } + } + } + ], + "links":{ + "self":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "first":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "prev":null, + "next":null, + "last":"/api/v2/policy-evaluations/poleval-8Jj9Hfoz892D9WMX/policy-set-outcomes?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20" + }, + "meta":{ + "pagination":{ + "current-page":1, + "page-size":20, + "prev-page":null, + "next-page":null, + "total-pages":1, + "total-count":1 + } + } +} +``` + +## Show a Policy Outcome + +`GET /policy-set-outcomes/:policy_set_outcome_id` + +| Parameter | Description | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `:policy_set_outcome_id` | The ID of the policy outcome to show. Refer to [List the Policy Outcomes](#list-policy-outcomes) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] | The request was successful | +| [404][] | [JSON API error object][] | Policy set outcome not found or user unauthorized to perform action | + +### Sample Request + +The following example request gets the outcomes for the `psout-cu8E9a97LBepZZXd` policy set. + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/policy-set-outcomes/psout-cu8E9a97LBepZZXd +``` + +### Sample Response + +The following example response shows that the `policyVCS` policy failed. + +```json +{ + "data":{ + "id":"psout-cu8E9a97LBepZZXd", + "type":"policy-set-outcomes", + "attributes":{ + "outcomes":[ + { + "enforcement_level":"advisory", + "query":"data.terraform.main.main", + "status":"failed", + "policy_name":"policyVCS", + "description":"" + } + ], + "error":"", + "overridable":true, + "policy-set-name":"opa-policies-vcs", + "policy-set-description":null, + "result-count":{ + "advisory-failed":1, + "errored":0, + "mandatory-failed":0, + "passed":0 + }, + "policy-tool-version": "0.54.0" + }, + "relationships":{ + "policy-evaluation":{ + "data":{ + "id":"poleval-8Jj9Hfoz892D9WMX", + "type":"policy-evaluations" + } + } + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-set-params.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-set-params.mdx new file mode 100644 index 0000000000..4065a72ca9 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-set-params.mdx @@ -0,0 +1,290 @@ +--- +page_title: /parameters API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/parameters` endpoint to manage the + key/value pairs that Sentinel uses for policy checks. Read, create, update, + and delete parameters. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy set parameters API references + +[Sentinel parameters](/sentinel/docs/language/parameters) are a list of key/value pairs that HCP Terraform sends to the Sentinel runtime when performing policy checks on workspaces. They can help you avoid hardcoding sensitive parameters into a policy. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Parameters are only available for Sentinel policies. This set of APIs provides endpoints to create, update, list and delete parameters. + +## Create a Parameter + +`POST /policy-sets/:policy_set_id/parameters` + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:policy_set_id` | The ID of the policy set to create the parameter in. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the parameter. | +| `data.attributes.value` | string | `""` | The value of the parameter. | +| `data.attributes.category` | string | | The category of the parameters. Must be `"policy-set"`. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the parameter is written once and not visible thereafter. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "category":"policy-set", + "sensitive":false + } + } +} +``` + +### 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/policy-sets/polset-u3S5p2Uwk21keu1s/parameters +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "sensitive":false, + "category":"policy-set" + }, + "relationships": { + "configurable": { + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policy-sets" + }, + "links": { + "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s" + } + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-EavQ1LztoRTQHSNT" + } + } +} +``` + +## List Parameters + +`GET /policy-sets/:policy_set_id/parameters` + +| Parameter | Description | +| ---------------- | ------------------------------------------------ | +| `:policy_set_id` | The ID of the policy set to list parameters for. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 parameters per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ +"https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"var-AD4pibb9nxo1468E", + "type":"vars", + "attributes": { + "key":"name", + "value":"hello", + "sensitive":false, + "category":"policy-set", + }, + "relationships": { + "configurable": { + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policy-sets" + }, + "links": { + "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s" + } + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-AD4pibb9nxo1468E" + } + } + ] +} +``` + +## Update Parameters + +`PATCH /policy-sets/:policy_set_id/parameters/:parameter_id` + +| Parameter | Description | +| ---------------- | ------------------------------------------------- | +| `:policy_set_id` | The ID of the policy set that owns the parameter. | +| `:parameter_id` | The ID of the parameter to be updated. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.id` | string | | The ID of the parameter to update. | +| `data.attributes` | object | | New attributes for the parameter. This object can include `key`, `value`, `category` and `sensitive` properties, which are described above under [create a parameter](#create-a-parameter). All of these properties are optional; if omitted, a property will be left unchanged. | + +### Sample Payload + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "attributes": { + "key":"name", + "value":"mars", + "category":"policy-set", + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "sensitive":false, + "category":"policy-set", + }, + "relationships": { + "configurable": { + "data": { + "id":"pol-u3S5p2Uwk21keu1s", + "type":"policy-sets" + }, + "links": { + "related":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s" + } + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG" + } + } +} +``` + +## Delete Parameters + +`DELETE /policy-sets/:policy_set_id/parameters/:parameter_id` + +| Parameter | Description | +| ---------------- | ------------------------------------------------- | +| `:policy_set_id` | The ID of the policy set that owns the parameter. | +| `:parameter_id` | The ID of the parameter to be deleted. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/policy-sets/polset-u3S5p2Uwk21keu1s/parameters/var-yRmifb4PJj7cLkMG +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-sets.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-sets.mdx new file mode 100644 index 0000000000..a0e73b0a9e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/policy-sets.mdx @@ -0,0 +1,1298 @@ +--- +page_title: /policy-sets API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/policy-sets` endpoint to read, create, + delete, update and version Sentinel and OPA policy sets. Also, attach, + exclude, and detach policy sets to workspaces and projects. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Policy sets API reference + +[Policy Enforcement](/terraform/enterprise/policy-enforcement) lets you use the policy-as-code frameworks Sentinel and Open Policy Agent (OPA) to apply policy checks to HCP Terraform workspaces. + +[Policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) are collections of policies that you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +This API provides endpoints to create, read, update, and delete policy sets in an HCP Terraform organization. To view and manage individual policies, use the [Policies API](/terraform/enterprise/api-docs/policies). + +Many of these endpoints let you create policy sets from a designated repository in a Version Control System (VCS). For more information about how to configure a policy set VCS repository, refer to [Sentinel Policy Set VCS Repositories](/terraform/enterprise/policy-enforcement/sentinel/vcs) and [OPA Policy Set VCS Repositories](/terraform/enterprise/policy-enforcement/opa/vcs). + +Instead of connecting HCP Terraform to a VCS repository, you can use the the [Policy Set Versions endpoint](#create-a-policy-set-version) to create an entire policy set from a `tar.gz` file. + +Interacting with policy sets requires permission to manage policies. ([More about permissions](/terraform/enterprise/users-teams-organizations/permissions).) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a policy set + +`POST /organizations/:organization_name/policy-sets` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The organization to create the policy set in. The organization must already exist in the system, and the token authenticating the API request must have permission to manage policies. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "policy-sets"`) | Successfully created a policy set | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------------------------- | -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policy-sets"`. | +| `data.attributes.name` | string | | The name of the policy set. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.description` | string | `null` | Text describing the policy set's purpose. This field supports Markdown and appears in the HCP Terraform UI. | +| `data.attributes.global` | boolean | `false` | Whether HCP Terraform should automatically apply this policy set to all of an organization's workspaces. | +| `data.attributes.kind` | string | `sentinel` | The policy-as-code framework associated with the policy. Valid values are `sentinel` and `opa`. | +| `data.attributes.overridable` | boolean | `false` | Whether or not users can override this policy when it fails during a run. Valid for sentinel policies only if `agent-enabled` is set to `true`. | +| `data.attributes.vcs-repo` | object | `null` | VCS repository information. When present, HCP Terraform sources the policies and configuration from the specified VCS repository. This attribute and `policies` relationships are mutually exclusive, and you cannot use them simultaneously. | +| `data.attributes.vcs-repo.branch` | string | `null` | The branch of the VCS repository where HCP Terraform should retrieve the policy set. If empty, HCP Terraform uses the default branch. | +| `data.attributes.vcs-repo.identifier` | string | | The VCS repository identifier in the format `/`. For example, `hashicorp/my-policy-set`. The format for Azure DevOps is `//_git/`. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The OAuth Token ID HCP Terraform should use to connect to the VCS host. This value must not be specified if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | `false` | Whether HCP Terraform should instantiate repository submodules when retrieving the policy set. | +| `data.attributes.policies-path` | string | `null` | The VCS repository subdirectory that contains the policies for this policy set. HCP Terraform ignores files and directories outside of this sub-path and does not update the policy set when those files change. This attribute is only valid when you specify a VCS repository for the policy set. | +| `data.relationships.projects.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which projects are associated with the policy set. These objects must contain `id` and `type` properties, and the `type` property must be `projects`. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspaces.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which workspaces are associated with the policy set. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces`. For example, `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`. Obtain workspace IDs from the [workspace's settings page](/terraform/enterprise/workspaces/settings) or the [Show Workspace endpoint](/terraform/enterprise/api-docs/workspaces#show-workspace). You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspace-exclusions.data[]` | array\[object] | `[]` | A list of resource identifier objects specifying which workspaces HCP Terraform excludes from a policy set's enforcement. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces`. For example, `{ "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" }`. | +| `data.relationships.policies.data[]` | array\[object] | `[]` | A list of resource identifier objects that defines which policies are members of the policy set. These objects must contain `id` and `type` properties, and the `type` property must be `policies`. For example, `{ "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }`. | +| `data.attributes.agent-enabled` | boolean | `false` | Only valid for `sentinel` policy sets. Whether this policy set should run as a policy evaluation in the HCP Terraform agent. | +| `data.attributes.policy-tool-version` | string | `latest` | The version of the tool that HCP Terraform uses to evaluate policies. You can only set a policy tool version for 'sentinel' policy sets if `agent-enabled` is `true`. | + +### Sample Payload + +```json +{ + "data": { + "type": "policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "global": false, + "kind": "sentinel", + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policies-path": "/policy-sets/foo", + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + } + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + } + } + } +} +``` + +### Sample payload with individual policy relationships + +```json +{ + "data": { + "type": "policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true + }, + "relationships": { + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + } + } +} +``` + +### 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/organizations/my-organization/policy-sets +``` + +### Sample Response + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "workspace-count": 1, + "policies-path": "/policy-sets/foo", + "versioned": true, + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + }, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + }, + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +### Sample response with individual policy relationships + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## List policy sets + +`GET /organizations/:organization_name/policy-sets` + +| Parameter | Description | +| -------------------- | ----------------------------------------- | +| `:organization_name` | The organization to list policy sets for. | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-sets"`) | Request was successful | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `filter[versioned]` | **Optional.** Allows filtering policy sets based on whether they are versioned (VCS-managed or API-managed), or use individual policy relationships. Accepts a boolean true/false value. A `true` value returns versioned sets, and a `false` value returns sets with individual policy relationships. If omitted, all policy sets are returned. | +| `filter[kind]` | **Optional.** If specified, restricts results to those with the matching policy kind value. Valid values are `sentinel` and `opa`. | +| `include` | **Optional.** Enables you to include related resource data. Value must be a comma-separated list containing one or more of `projects`, `workspaces`, `workspace-exclusions`, `policies`, `newest_version`, or `current_version`. See the [relationships section](#relationships) for details. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 policy sets per page. | +| `search[name]` | **Optional.** Allows searching the organization's policy sets by name. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/policy-sets +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "workspace-count": 1, + "policies-path": "/policy-sets/foo", + "versioned": true, + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + }, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + }, + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } + ] +} +``` + +### Sample response with individual policy relationships + +```json +{ + "data": [ + { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + }, + ] +} +``` + +## Show a policy set + +`GET /policy-sets/:id` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to show. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-sets"`) | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `include` | **Optional.** Enables you to include related resource data. Value must be a comma-separated list containing one or more of `projects`, `workspaces`, `workspace-exclusions`, `policies`, `newest_version`, or `current_version`. See the [relationships section](#relationships) for details. | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1?include=current_version +``` + +### Sample Response + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 0, + "workspace-count": 1, + "policies-path": "/policy-sets/foo", + "versioned": true, + "vcs-repo": { + "branch": "main", + "identifier": "hashicorp/my-policy-sets", + "ingress-submodules": false, + "oauth-token-id": "ot-7Fr9d83jWsi8u23A" + }, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "current-version": { + "data": { + "id": "polsetver-m4yhbUBCgyDVpDL4", + "type": "policy-set-versions" + } + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + }, + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + }, + "included": [ + { + "id": "polsetver-m4yhbUBCgyDVpDL4", + "type": "policy-set-versions", + "attributes": { + "source": "github", + "status": "ready", + "status-timestamps": { + "ready-at": "2019-06-21T21:29:48+00:00", + "ingressing-at": "2019-06-21T21:29:47+00:00" + }, + "error": null, + "ingress-attributes": { + "commit-sha": "8766a423cb902887deb0f7da4d9beaed432984bb", + "commit-url": "https://github.com/hashicorp/my-policy-sets/commit/8766a423cb902887deb0f7da4d9beaed432984bb", + "identifier": "hashicorp/my-policy-sets" + }, + "created-at": "2019-06-21T21:29:47.792Z", + "updated-at": "2019-06-21T21:29:48.887Z" + }, + "relationships": { + "policy-set": { + "data": { + "id": "polset-a2mJwtmKygrA11dh", + "type": "policy-sets" + } + } + }, + "links": { + "self": "/api/v2/policy-set-versions/polsetver-E4S7jz8HMjBienLS" + } + } + ] +} +``` + +### Sample response with individual policy relationships + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "production", + "description": "This set contains policies that should be checked on all production infrastructure workspaces.", + "kind": "sentinel", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z", + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +-> **Note:** The `data.relationships.projects` and `data.relationships.workspaces` refer to the projects and workspaces attached to the policy set. HCP Terraform omits these keys for policy sets marked as global, which are implicitly related to all of the organization's workspaces. + +## Update a policy set + +`PATCH /policy-sets/:id` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to update. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-sets"`) | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------- | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"policy-sets"`. | +| `data.attributes.name` | string | (previous value) | The name of the policy set. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.description` | string | (previous value) | A description of the set's purpose. This field supports markdown and appears in the HCP Terraform UI. | +| `data.attributes.global` | boolean | (previous value) | Whether or not the policies in this set should be checked in all of the organization's workspaces or only in workspaces directly attached to the set. | +| `data.attributes.vcs-repo` | object | (previous value) | VCS repository information. When present, HCP Terraform sources the policies and configuration from the specified VCS repository instead of using definitions from HCP Terraform. Note that this option and `policies` relationships are mutually exclusive and may not be used simultaneously. | +| `data.attributes.vcs-repo.branch` | string | (previous value) | The branch of the VCS repo. When empty, HCP Terraform uses the VCS provider's default branch value. | +| `data.attributes.vcs-repo.identifier` | string | (previous value) | The VCS repository identifier in the the following format: `/`. An example identifier in GitHub is `hashicorp/my-policy-set`. The format for Azure DevOps is `//_git/`. | +| `data.attributes.vcs-repo.oauth-token-id` | string | (previous value) | The OAuth token ID to use to connect to the VCS host. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | (previous value) | Determines whether HCP Terraform instantiates repository submodules during the clone operation. | +| `data.attributes.policies-path` | boolean | (previous value) | The subdirectory of the attached VCS repository that contains the policies for this policy set. HCP Terraform ignores files and directories outside of the sub-path. Changes to the unrelated files do not update the policy set. You can only enable this option when a VCS repository is present. | +| `data.relationships.projects` | array\[object] | (previous value) | An array of references to projects that the policy set should be assigned to. Sending an empty array clears all project assignments. You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspaces` | array\[object] | (previous value) | An array of references to workspaces that the policy set should be assigned to. Sending an empty array clears all workspace assignments. You can only specify this attribute when `data.attributes.global` is `false`. | +| `data.relationships.workspace-exclusions` | array\[object] | (previous value) | An array of references to excluded workspaces that HCP Terraform will not enforce this policy set upon. Sending an empty array clears all exclusions assignments. | +| `data.attributes.agent-enabled` | boolean | `false` | Only valid for `sentinel` policy sets. Whether this policy set should run as a policy evaluation in the HCP Terraform agent. | +| `data.attributes.policy-tool-version` | string | `latest` | The version of the tool that HCP Terraform uses to evaluate policies. You can only set a policy tool version for 'sentinel' policy sets if `agent-enabled` is `true`. | + +### Sample Payload + +```json +{ + "data": { + "type": "policy-sets", + "attributes": { + "name": "workspace-scoped-policy-set", + "description": "Policies added to this policy set will be enforced on specified workspaces", + "global": false, + "agent-enabled": true, + "policy-tool-version": "0.23.0" + }, + "relationships": { + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + } + } + } +} +``` + +### 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/policy-sets/polset-3yVQZvHzf5j3WRJ1 +``` + +### Sample Response + +```json +{ + "data": { + "id":"polset-3yVQZvHzf5j3WRJ1", + "type":"policy-sets", + "attributes": { + "name": "workspace-scoped-policy-set", + "description": "Policies added to this policy set will be enforced on specified workspaces", + "global": false, + "kind": "sentinel", + "agent-enabled": true, + "policy-tool-version": "0.23.0", + "overridable": true, + "policy-count": 1, + "workspace-count": 1, + "versioned": false, + "created-at": "2018-09-11T18:21:21.784Z", + "updated-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "organization": { + "data": { "id": "my-organization", "type": "organizations" } + }, + "policies": { + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" } + ] + }, + "projects": { + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" } + ] + }, + "workspaces": { + "data": [ + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] + }, + "workspace-exclusions": { + "data": [ + { "id": "ws-FVVvzCDaykN1oHiw", "type": "workspaces" } + ] + } + }, + "links": { + "self":"/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## Add policies to the policy set + +`POST /policy-sets/:id/relationships/policies` + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to add policies to. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more policies not found, wrong types, etc.) | + +~> **Note:** This endpoint may only be used when there is no VCS repository associated with the policy set. + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which policies will be added to the set. These objects must contain `id` and `type` properties, and the `type` property must be `policies` (e.g. `{ "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }, + { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies +``` + +## Attach a policy set to projects + +`POST /policy-sets/:id/relationships/projects` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to attach to projects. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** You can not attach global policy sets to individual projects. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which projects to attach the policy set to. These objects must contain `id` and `type` properties, and the `type` property must be `projects` (e.g. `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/projects +``` + +## Attach a policy set to workspaces + +`POST /policy-sets/:id/relationships/workspaces` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to attach to workspaces. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** Policy sets marked as global cannot be attached to individual workspaces. + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more workspaces not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines the workspaces the policy set will be attached to. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces +``` + +## Exclude a workspace from a policy set + +`POST /policy-sets/:id/relationships/workspace-exclusions` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:id` | The ID of a policy set that you want HCP Terraform to exclude from the workspaces you specify. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more excluded workspaces not found, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines the excluded workspaces the policy set will be attached to. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspace-exclusions +``` + +## Remove policies from the policy set + +`DELETE /policy-sets/:id/relationships/policies` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to remove policies from. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (wrong types, etc.) | + +~> **Note:** This endpoint may only be used when there is no VCS repository associated with the policy set. + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which policies will be removed from the set. These objects must contain `id` and `type` properties, and the `type` property must be `policies` (e.g. `{ "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }`). | + +### Sample Payload + +```json +{ + "data": [ + { "id": "pol-u3S5p2Uwk21keu1s", "type": "policies" }, + { "id": "pol-2HRvNs49EWPjDqT1", "type": "policies" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/policies +``` + +## Detach a policy set from projects + +`DELETE /policy-sets/:id/relationships/projects` + +| Parameter | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set you want to detach from the specified projects. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** You can not attach global policy sets to individual projects. + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------- | +| [204][] | Nothing | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (one or more projects not found, wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines the projects the policy set will be detached from. These objects must contain `id` and `type` properties, and the `type` property must be `projects`. For example, `{ "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }`. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "prj-AwfuCJTkdai4xj9w", "type": "projects" }, + { "id": "prj-2HRvNs49EWPjDqT1", "type": "projects" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/projects +``` + +## Detach the policy set from workspaces + +`DELETE /policy-sets/:id/relationships/workspaces` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to detach from workspaces. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +-> **Note:** Policy sets marked as global cannot be detached from individual workspaces. + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which workspaces the policy set will be detached from. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspaces +``` + +## Reinclude a workspace to a policy set + +`DELETE /policy-sets/:id/relationships/workspace-exclusions` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:id` | The ID of the policy set HCP Terraform should reinclude (enforce) on the specified workspaces. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (wrong types, etc.) | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data[]` | array\[object] | | A list of resource identifier objects that defines which workspaces HCP Terraform should reinclude (enforce) this policy set on. These objects must contain `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Sample Payload + +```json +{ + "data": [ + { "id": "ws-u3S5p2Uwk21keu1s", "type": "workspaces" }, + { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" } + ] +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/relationships/workspace-exclusions +``` + +## Delete a policy set + +`DELETE /policy-sets/:id` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the policy set to delete. Refer to [List Policy Sets](#list-policy-sets) for reference information about finding IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | No Content | Successfully deleted the policy set | +| [404][] | [JSON API error object][] | Policy set not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1 +``` + +## Create a policy set version + +For versioned policy sets which have no VCS repository attached, versions of policy code may be uploaded directly to the API by creating a new policy set version and, in a subsequent request, uploading a tarball (tar.gz) of data to it. + +`POST /policy-sets/:id/versions` + +| Parameter | Description | +| --------- | ----------------------------------------------------- | +| `:id` | The ID of the policy set to create a new version for. | + +| Status | Response | Reason | +| ------- | ----------------------------------------------------- | ----------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "policy-set-versions"`) | The request was successful. | +| [404][] | [JSON API error object][] | Policy set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | The policy set does not support uploading versions. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/policy-sets/polset-3yVQZvHzf5j3WRJ1/versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "polsetver-cXciu9nQwmk9Cfrn", + "type": "policy-set-versions", + "attributes": { + "source": "tfe-api", + "status": "pending", + "status-timestamps": {}, + "error": null, + "created-at": "2019-06-28T23:53:15.875Z", + "updated-at": "2019-06-28T23:53:15.875Z" + }, + "relationships": { + "policy-set": { + "data": { + "id": "polset-ws1CZBzm2h5K6ZT5", + "type": "policy-sets" + } + } + }, + "links": { + "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn", + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..." + } + } +} +``` + +The `upload` link URL in the above response is valid for one hour after creation. Make a `PUT` request to this URL directly, sending the policy set contents in `tar.gz` format as the request body. Once uploaded successfully, you can request the [Show Policy Set](#show-a-policy-set) endpoint again to verify that the status has changed from `pending` to `ready`. + +## Upload policy set versions + +`PUT https://archivist.terraform.io/v1/object/` + +The URL is provided in the `upload` attribute in the `policy-set-versions` resource. + +### Sample Request + +In the example below, `policy-set.tar.gz` is the local filename of the policy set version file to upload. + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @policy-set.tar.gz \ + https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox... +``` + +## Show a policy set version + +`GET /policy-set-versions/:id` + +| Parameter | Description | +| --------- | ----------------------------------------- | +| `:id` | The ID of the policy set version to show. | + +| Status | Response | Reason | +| ------- | ----------------------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "policy-set-versions"`) | The request was successful. | +| [404][] | [JSON API error object][] | Policy set version not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --request GET \ + https://app.terraform.io/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn +``` + +### Sample Response + +```json +{ + "data": { + "id": "polsetver-cXciu9nQwmk9Cfrn", + "type": "policy-set-versions", + "attributes": { + "source": "tfe-api", + "status": "pending", + "status-timestamps": {}, + "error": null, + "created-at": "2019-06-28T23:53:15.875Z", + "updated-at": "2019-06-28T23:53:15.875Z" + }, + "relationships": { + "policy-set": { + "data": { + "id": "polset-ws1CZBzm2h5K6ZT5", + "type": "policy-sets" + } + } + }, + "links": { + "self": "/api/v2/policy-set-versions/polsetver-cXciu9nQwmk9Cfrn", + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..." + } + } +} +``` + +The `upload` link URL in the above response is valid for one hour after the `created_at` timestamp of the policy set version. Make a `PUT` request to this URL directly, sending the policy set contents in `tar.gz` format as the request body. Once uploaded successfully, you can request the [Show Policy Set Version](#show-a-policy-set-version) endpoint again to verify that the status has changed from `pending` to `ready`. + +## Available related resources + +The GET endpoints above can optionally return related resources for policy sets, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `current_version` | The most recent **successful** policy set version. | +| `newest_version` | The most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors. | +| `policies` | Individually managed policies which are associated with the policy set. | +| `projects` | The projects this policy set applies to. | +| `workspaces` | The workspaces this policy set applies to. | +| `workspace-exclusions` | The workspaces excluded from this policy set's enforcement. | + +The following resource types may be included for policy set versions: + +| Resource Name | Description | +| ------------- | ---------------------------------------------------------------- | +| `policy_set` | The policy set associated with the specified policy set version. | + +## Relationships + +The following relationships may be present in various responses for policy sets: + +| Resource Name | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `current-version` | The most recent **successful** policy set version. | +| `newest-version` | The most recently created policy set version, regardless of status. Note that this relationship may include an errored and unusable version, and is intended to allow checking for VCS errors. | +| `organization` | The organization associated with the specified policy set. | +| `policies` | Individually managed policies which are associated with the policy set. | +| `projects` | The projects this policy set applies to. | +| `workspaces` | The workspaces this policy set applies to. | +| `workspace-exclusions` | The workspaces excluded from this policy set's enforcement. | + +The following relationships may be present in various responses for policy set versions: + +| Resource Name | Description | +| ------------- | ---------------------------------------------------------------- | +| `policy-set` | The policy set associated with the specified policy set version. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/gpg-keys.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/gpg-keys.mdx new file mode 100644 index 0000000000..3386ea42c3 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/gpg-keys.mdx @@ -0,0 +1,388 @@ +--- +page_title: /gpg-keys API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/gpg-keys` endpoint to read, add, get, + update, and delete the GPG keys that HCP Terraform uses to sign private + providers. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# GPG keys API reference + +These endpoints are only relevant to private providers. When you [publish a private provider](/terraform/enterprise/registry/publish-providers) to the HCP Terraform private registry, you must upload the public key of the GPG key-pair that you used to sign the release. The HCP Terraform registry supports RSA or DSA formatted GPG keys. Refer to [Preparing and adding a signing key](/terraform/registry/providers/publishing#preparing-and-adding-a-signing-key) for more details. + +You need [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or [Manage Private Registry](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) permissions to add, update, or delete GPG keys in a private registry. + +## List GPG Keys + +`GET /api/registry/:registry_name/v2/gpg-keys` + +### Parameters + +| Parameter | Description | +| ---------------- | ------------------ | +| `:registry_name` | Must be `private`. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not automatically encode URLs. + +| Parameter | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[namespace]` | **Required.** A comma-separated list of one or more namespaces. The namespaces must be an authorized HCP Terraform or Terraform Enterprise organization name. | +| `page[number]` | **Optional.** If omitted, the endpoint returns the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint returns 20 GPG keys per page. | + +Gets a list of GPG keys belonging to the specified namespaces. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully fetched GPG keys | +| [400][] | [JSON API error object][] | Error - missing namespaces in request | +| [403][] | [JSON API error object][] | Forbidden - no authorized namespaces specified in request | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + "https://app.terraform.io/api/registry/private/v2/gpg-keys?filter%5Bnamespace%5D=my-organization,my-other-organization" +``` + +### Sample Response + +```json +{ + "data": [ + { + "type": "gpg-keys", + "id": "1", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----...", + "created-at": "2022-02-08T19:15:47Z", + "key-id": "C4E5E6C66C79C778", + "namespace": "my-other-organization", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-08T19:15:47Z" + }, + "links": { + "self": "/v2/gpg-keys/1" + } + }, + { + "type": "gpg-keys", + "id": "140", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----...", + "created-at": "2022-04-28T21:32:11Z", + "key-id": "C4E5E6C66C79C778", + "namespace": "my-organization", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-04-28T21:32:11Z" + }, + "links": { + "self": "/v2/gpg-keys/140" + } + } + ], + "links": { + "first": "/v2/gpg-keys?filter%5Bnamespace%5D=my-organization%2Cmy-other-organization&page%5Bnumber%5D=1&page%5Bsize%5D=15", + "last": "/v2/gpg-keys?filter%5Bnamespace%5D=my-organization%2Cmy-other-organization&page%5Bnumber%5D=1&page%5Bsize%5D=15", + "next": null, + "prev": null + }, + "meta": { + "pagination": { + "page-size": 15, + "current-page": 1, + "next-page": null, + "prev-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Add a GPG Key + +`POST /api/registry/:registry_name/v2/gpg-keys` + +### Parameters + +| Parameter | Description | +| ---------------- | ------------------ | +| `:registry_name` | Must be `private`. | + +Uploads a GPG Key to a private registry scoped with a namespace. The response will provide a "key-id", which is required to [Create a Provider Version](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-version). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully uploads a GPG key to a private provider | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"gpg-keys"`. | +| `data.attributes.namespace` | string | | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `data.attributes.ascii-armor` | string | | A valid gpg-key string. | + +### Sample Payload + +```json +{ + "data": { + "type": "gpg-keys", + "attributes": { + "namespace": "hashicorp", + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n" + } } +} +``` + +### 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/registry/private/v2/gpg-keys +``` + +### Sample Response + +```json +{ + "data": { + "type": "gpg-keys", + "id": "23", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n", + "created-at": "2022-02-11T19:16:59Z", + "key-id": "32966F3FB5AC1129", + "namespace": "hashicorp", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-11T19:16:59Z" + }, + "links": { + "self": "/v2/gpg-keys/23" + } + } +} +``` + +## Get GPG Key + +`GET /api/registry/:registry_name/v2/gpg-keys/:namespace/:key_id` + +### Parameters + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider scoped to the GPG key. | +| `:key_id` | The id of the GPG key. | + +Gets the content of a GPG key. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ---------------------------------------------- | +| [200][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully fetched GPG key | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | GPG key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/registry/private/v2/gpg-keys/hashicorp/32966F3FB5AC1129 +``` + +### Sample Response + +```json +{ + "data": { + "type": "gpg-keys", + "id": "2", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n", + "created-at": "2022-02-24T17:07:25Z", + "key-id": "32966F3FB5AC1129", + "namespace": "hashicorp", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-24T17:07:25Z" + }, + "links": { + "self": "/v2/gpg-keys/2" + } + } +} +``` + +## Update a GPG Key + +`PATCH /api/registry/:registry_name/v2/gpg-keys/:namespace/:key_id` + +### Parameters + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider scoped to the GPG key. | +| `:key_id` | The id of the GPG key. | + +Updates the specified GPG key. Only the `namespace` attribute can be updated, and `namespace` has to match an `organization` the user has permission to access. + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully updates a GPG key | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | GPG key not found or user not authorized | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"gpg-keys"`. | +| `data.attributes.namespace` | string | | The namespace of the provider. Must be the same as the `organization_name` for the provider. | + +### Sample Payload + +```json +{ + "data": { + "type": "gpg-keys", + "attributes": { + "namespace": "new-namespace", + } + } +} +``` + +### 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/registry/private/v2/gpg-keys/hashicorp/32966F3FB5AC1129 +``` + +### Sample Response + +```json +{ + "data": { + "type": "gpg-keys", + "id": "2", + "attributes": { + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n", + "created-at": "2022-02-24T17:07:25Z", + "key-id": "32966F3FB5AC1129", + "namespace": "new-name", + "source": "", + "source-url": null, + "trust-signature": "", + "updated-at": "2022-02-24T17:12:10Z" + }, + "links": { + "self": "/v2/gpg-keys/2" + } + } +} +``` + +## Delete a GPG Key + +`DELETE /api/registry/:registry_name/v2/gpg-keys/:namespace/:key_id` + +### Parameters + +| Parameter | Description | +| ---------------- | ---------------------------------------------------- | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider scoped to the GPG key. | +| `:key_id` | The id of the GPG key. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "gpg-keys"`) | Successfully deletes a GPG key | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | GPG key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/registry/private/v2/gpg-keys/hashicorp/32966F3FB5AC1129 +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx new file mode 100644 index 0000000000..7fe7e2a61b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/manage-module-versions.mdx @@ -0,0 +1,531 @@ +--- +page_title: Manage module versions API reference for Terraform Enterprise +description: >- + 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 +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[503]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Manage module versions API reference + +Use the module version management API endpoints to deprecate, revoke, and revert of status of module versions in your organization’s private registry. + +<>{/* TODO: remove revoke references here */} + + + +@include "tfc-package-callouts/manage-module-versions.mdx" + + + +## 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 + +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 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. + +| 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 deprecated 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 deprecate 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 deprecating a module version. | + +### Sample payload + +```json +{ + "data": { + "type": "module-versions", + "attributes": { + "deprecation": { + "deprecated-status": "Deprecated", + "reason": "Deprecated due to a security vulnerability issue.", + "link": "https://www.hashicorp.com/" + } + } + } +} +``` + +### 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 response + +```json +{ + "data": { + "type": "module-versions", + "id": "1", + "relationships": { + "deprecation": { + "data": { + "id": "2", + "type": "deprecations" + } + } + } + }, + "included": [ + { + "type": "deprecations", + "id": "2", + "attributes": { + "link": "https://www.hashicorp.com/", + "reason": "Deprecated due to a security vulnerability issue. Applies will be blocked in 15 days." + } + } + ] +} +``` + +## Revert the deprecation status for a module version + +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 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. + +| 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 deprecation status and reinstated 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 depreciation 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 deprecation 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": { + "deprecation": { + "deprecated-status": "Undeprecated" + } + } + } +} +``` + +### Sample response + +```json +{ + "data": { + "type": "module-versions", + "id": "1" + } +} +``` + +## 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. + +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: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/0.0.1 +``` + +If the module is deprecated, your response includes a `deprecation` key with the details of that module version’s deprecation. + +```json +{ + "id": "hashicorp/consul/aws/0.0.1", + "owner": "gruntwork-team", + "namespace": "hashicorp", + "name": "consul", + "version": "0.0.1", + "provider": "aws", + "description": "A Terraform Module for how to run Consul on AWS using Terraform and Packer" + // ... // + "deprecation": { + "reason": "This version was deprecated due to a vulnerability issue. Please upgrade to 0.0.2.", + "link": "https://hashicorp.com" + } +} +``` + +To check the deprecation status of all of the `consul` module’s versions, you could perform the following API call: + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/versions +``` + +The response includes multiple versions, and each version has a `deprecation` key listing the details of that module’s deprecation. If a module version has not been deprecated, the `deprecation` field returns `null`. + +```json +{ + "modules": [ + { + "source": "hashicorp/consul/aws", + "versions": [ + { + "version": "0.0.1", + // ... // + "deprecation": { + "reason": "security vulnerability", + "link": "www.hashicorp.com" + } + }, + { + "version": "0.0.2", + "submodules": [], + "root": { + "dependencies": [], + "providers": [ + { + "name": "template", + "version": "" + }, + { + "name": "aws", + "version": "" + } + ] + }, + "deprecation": null + } + ] + } + ] +} +``` + + + +## 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/v000011-1/docs/enterprise/api-docs/private-registry/modules.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/modules.mdx new file mode 100644 index 0000000000..d5df734ece --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/modules.mdx @@ -0,0 +1,942 @@ +--- +page_title: /registry-modules API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/registry-modules` endpoint to read, + publish, update, delete, and add versions to modules in your organization's + private registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Registry modules API reference + +-> **Note:** Public Module Curation is only available in HCP Terraform. Where applicable, the `registry_name` parameter must be `private` for Terraform Enterprise. + +## HCP Terraform Registry Implementation + +The HCP Terraform Module Registry implements the [Registry standard API](/terraform/registry/api-docs) for consuming/exposing private modules. Refer to the [Module Registry HTTP API](/terraform/registry/api-docs) to perform the following: + +- Browse available modules +- Search modules by keyword +- List available versions for a specific module +- Download source code for a specific module version +- List latest version of a module for all providers +- Get the latest version for a specific module provider +- Get a specific module +- Download the latest version of a module + +For publicly curated modules, the HCP Terraform Module Registry acts as a proxy to the [Terraform Registry](https://registry.terraform.io) for the following: + +- List available versions for a specific module +- Get a specific module +- Get the latest version for a specific module provider + +The HCP Terraform Module Registry endpoints differs from the Module Registry endpoints in the following ways: + +- The `:namespace` parameter should be replaced with the organization name for private modules. +- The private module registry discovery endpoints have the path prefix provided in the [discovery document](/terraform/registry/api-docs#service-discovery) which is currently `/api/registry/v1`. +- The public module registry discovery endpoints have the path prefix provided in the [discovery document](/terraform/registry/api-docs#service-discovery) which is currently `/api/registry/public/v1`. +- [Authentication](/terraform/enterprise/api-docs#authentication) is handled the same as all other HCP Terraform endpoints. + +### Sample Registry Request (private module) + +List available versions for the `consul` module for the `aws` provider on the module registry published from the Github organization `my-gh-repo-org`: + +```shell +$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions +``` + +The same request for the same module and provider on the HCP Terraform module registry for the `my-cloud-org` organization: + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/v1/modules/my-cloud-org/consul/aws/versions +``` + +### Sample Proxy Request (public module) + +List available versions for the `consul` module for the `aws` provider on the module registry published from the Github organization `my-gh-repo-org`: + +```shell +$ curl https://registry.terraform.io/v1/modules/my-gh-repo-org/consul/aws/versions +``` + +The same request for the same module and provider on the HCP Terraform module registry: + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/registry/public/v1/modules/my-gh-repo-org/consul/aws/versions +``` + +## List Registry Modules for an Organization + +`GET /organizations/:organization_name/registry-modules` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------ | +| `:organization_name` | The name of the organization to list available modules from. | + +Lists the modules that are available to a given organization. This includes the full list of publicly curated and private modules and is filterable. + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-modules"`) | The request was successful | +| [404][] | [JSON API error object][] | Modules not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `q` | **Optional.** A search query string. Modules are searchable by name, namespace, provider fields. | +| `filter[field name]` | **Optional.** If specified, restricts results to those with the matching field name value. Valid values are `registry_name`, `provider`, and `organization_name`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 registry modules per page. | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "mod-kwt1cBiX2SdDz38w", + "type": "registry-modules", + "attributes": { + "name": "api-gateway", + "namespace": "my-organization", + "provider": "alicloud", + "status": "setup_complete", + "version-statuses": [ + { + "version": "1.1.0", + "status": "ok" + } + ], + "created-at": "2021-04-07T19:01:18.528Z", + "updated-at": "2021-04-07T19:01:19.863Z", + "registry-name": "private", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/api-gateway/alicloud" + } + }, + { + "id": "mod-PopQnMtYDCcd3PRX", + "type": "registry-modules", + "attributes": { + "name": "aurora", + "namespace": "my-organization", + "provider": "aws", + "status": "setup_complete", + "version-statuses": [ + { + "version": "4.1.0", + "status": "ok" + } + ], + "created-at": "2021-04-07T19:04:41.375Z", + "updated-at": "2021-04-07T19:04:42.828Z", + "registry-name": "private", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/aurora/aws" + } + }, + ..., + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "prev": null, + "next": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=2&page%5Bsize%5D=6", + "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-modules?page%5Bnumber%5D=29&page%5Bsize%5D=6" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 6, + "prev-page": null, + "next-page": 2, + "total-pages": 29, + "total-count": 169 + } + } +} +``` + +## Publish a Private Module from a VCS + +~> **Deprecation warning**: the following endpoint `POST /registry-modules` is replaced by the below endpoint and will be removed from future versions of the API! + +`POST /organizations/:organization_name/registry-modules/vcs` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to a team or team member with the **Manage modules** permission enabled. | + +Publishes a new registry private module from a VCS repository, with module versions managed automatically by the repository's tags. The publishing process will fetch all tags in the source repository that look like [SemVer](https://semver.org/) versions with optional 'v' prefix. For each version, the tag is cloned and the config parsed to populate module details (input and output variables, readme, submodules, etc.). The [Module Registry Requirements](/terraform/registry/modules/publish#requirements) define additional requirements on naming, standard module structure and tags for releases. + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-modules"`) | Successfully published module | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-modules"`. | +| `data.attributes.vcs-repo.identifier` | string | | The repository from which to ingress the configuration. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS Connection (OAuth Connection + Token) to use as identified. Get this ID from the [oauth-tokens](/terraform/enterprise/api-docs/oauth-tokens) endpoint. You can not specify this value if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.display_identifier` | string | | The display identifier for the repository. For most VCS providers outside of Bitbucket Cloud, this identifier matches the `data.attributes.vcs-repo.identifier` string. | +| `data.attributes.no-code` | boolean | | Allows you to enable or disable the no-code publishing workflow for a module. | +| `data.attributes.vcs-repo.branch` | string | | The repository branch to publish the module from if you are using the branch-based publishing workflow. If omitted, the module will be published using the tag-based publishing workflow. | + +A VCS repository identifier is a reference to a VCS repository in the format `:org/:repo`, where `:org` and `:repo` refer to the organization, or project key for Bitbucket Data Center, and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`. + +The OAuth Token ID identifies the VCS connection, and therefore the organization, that the module will be created in. + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "vcs-repo": { + "identifier":"lafentres/terraform-aws-my-module", + "oauth-token-id":"ot-hmAyP66qk2AMVdbJ", + "display_identifier":"lafentres/terraform-aws-my-module", + "branch": "main" + }, + "no-code": true + }, + "type":"registry-modules" + } +} +``` + +### 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/organizations/my-organization/registry-modules/vcs +``` + +### Sample Response + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "namespace": "my-organization", + "registry-name": "private", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "vcs-repo": { + "branch": "", + "ingress-submodules": true, + "identifier": "lafentres/terraform-aws-my-module", + "display-identifier": "lafentres/terraform-aws-my-module", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..." + }, + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +## Create a Module (with no VCS connection) + +`POST /organizations/:organization_name/registry-modules` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to a team or team member with the **Manage modules** permission enabled. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Creates a new registry module without a backing VCS repository. + +#### Private modules + +After creating a module, a version must be created and uploaded in order to be usable. Modules created this way do not automatically update with new versions; instead, you must explicitly create and upload each new version with the [Create a Module Version](#create-a-module-version) endpoint. + +#### Public modules + +When created, the public module record will be available in the organization's registry module list. You cannot create versions for public modules as they are maintained in the public registry. + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-modules"`) | Successfully published module | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - public module curation disabled | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-modules"`. | +| `data.attributes.name` | string | | The name of this module. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters. | +| `data.attributes.provider` | string | | Specifies the Terraform provider that this module is used for. May contain lowercase alphanumeric characters. Maximum length is 64 characters. | +| `data.attributes.namespace` | string | | The namespace of this module. Cannot be set for private modules. May contain alphanumeric characters, with dashes and underscores allowed in non-leading or trailing positions. Maximum length is 64 characters. | +| `data.attributes.registry-name` | string | | Indicates whether this is a publicly maintained module or private. Must be either `public` or `private`. | +| `data.attributes.no-code` | boolean | | Allows you to enable or disable the no-code publishing workflow for a module. | + +### Sample Payload (private module) + +```json +{ + "data": { + "type": "registry-modules", + "attributes": { + "name": "my-module", + "provider": "aws", + "registry-name": "private", + "no-code": true + } + } +} +``` + +### Sample Payload (public module) + +```json +{ + "data": { + "type": "registry-modules", + "attributes": { + "name": "vpc", + "namespace": "terraform-aws-modules", + "provider": "aws", + "registry-name": "public", + "no-code": true + } + } +} +``` + +### 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/organizations/my-organization/registry-modules +``` + +### Sample Response (private module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "namespace": "my-organization", + "registry-name": "private", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +### Sample Response (public module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "vpc", + "namespace": "terraform-aws-modules", + "registry-name": "public", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws" + } + } +} +``` + +## Create a Module Version + +~> **Deprecation warning**: the following endpoint `POST /registry-modules/:organization_name/:name/:provider/versions` is replaced by the below endpoint and will be removed from future versions of the API! + +`POST /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/versions` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a module in. The organization must already exist, and the token authenticating the API request must belong to a team or team member with the **Manage modules** permission enabled. | +| `:namespace` | The namespace of the module for which the version is being created. For private modules this is the same as the `:organization_name` parameter | +| `:name` | The name of the module for which the version is being created. | +| `:provider` | The name of the provider for which the version is being created. | +| `:registry-name` | Must be `private`. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Creates a new registry module version. This endpoint only applies to private modules without a VCS repository and VCS-linked branch based modules. VCS-linked tag-based modules automatically create new versions for new tags. After creating the version for a non-VCS backed module, you should upload the module to the link that HCP Terraform returns. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-module-versions"`) | Successfully published module version | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public modules | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------------- | ------ | ------- | --------------------------------------------------- | +| `data.type` | string | | Must be `"registry-module-versions"`. | +| `data.attributes.version` | string | | A valid semver version string. | +| `data.attributes.commit-sha` | string | | The commit SHA to use to create the module version. | + +### Sample Payload + +```json +{ + "data": { + "type": "registry-module-versions", + "attributes": { + "version": "1.2.3", + "commit-sha": "abcdef12345" + } + } +} +``` + +### 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/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "modver-qjjF7ArLXJSWU3WU", + "type": "registry-module-versions", + "attributes": { + "source": "tfe-api", + "status": "pending", + "version": "1.2.3", + "created-at": "2018-09-24T20:47:20.931Z", + "updated-at": "2018-09-24T20:47:20.931Z" + }, + "relationships": { + "registry-module": { + "data": { + "id": "1881", + "type": "registry-modules" + } + } + }, + "links": { + "upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox..." + } + } +} +``` + +## Add a Module Version (Private Module) + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided in the `upload` links attribute in the `registry-module-versions` resource.** + +### Expected Archive Format + +HCP Terraform expects the module version uploaded to be a gzip tarball with the module in the root (not in a subdirectory). + +Given the following folder structure: + + terraform-null-test + ├── README.md + ├── examples + │   └── default + │   ├── README.md + │   └── main.tf + └── main.tf + +Package the files in an archive format by running `tar zcvf module.tar.gz *` in the module's directory. + + ~$ cd terraform-null-test + terraform-null-test$ tar zcvf module.tar.gz * + a README.md + a examples + a examples/default + a examples/default/main.tf + a examples/default/README.md + a main.tf + +### Sample Request + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @module.tar.gz \ + https://archivist.terraform.io/v1/object/dmF1bHQ6djE6NWJPbHQ4QjV4R1ox... +``` + +After the registry module version is successfully parsed, its status will become `"ok"`. + +## Get a Module + +~> **Deprecation warning**: the following endpoint `GET /registry-modules/show/:organization_name/:name/:provider` is replaced by the below endpoint and will be removed from future versions of the API! + +`GET /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` + +### Parameters + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the module belongs to. | +| `:namespace` | The namespace of the module. For private modules this is the name of the organization that owns the module. | +| `:name` | The module name. | +| `:provider` | The module provider. Must be lowercase alphanumeric. | +| `:registry-name` | Either `public` or `private`. | + +| Status | Response | Reason | +| ------- | -------------------------------------------------- | ------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-modules"`) | The request was successful | +| [403][] | [JSON API error object][] | Forbidden - public module curation disabled | +| [404][] | [JSON API error object][] | Module not found or user unauthorized to perform action | + +### Sample Request (private module) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws +``` + +### Sample Request (public module) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws +``` + +### Sample Response (private module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "provider": "aws", + "namespace": "my-organization", + "registry-name": "private", + "status": "setup_complete", + "version-statuses": [ + { + "version": "1.0.0", + "status": "ok" + } + ], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T20:16:20.538Z", + "vcs-repo": { + "branch": "", + "ingress-submodules": true, + "identifier": "lafentres/terraform-aws-my-module", + "display-identifier": "lafentres/terraform-aws-my-module", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..." + }, + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +### Sample Response (public module) + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "vpc", + "provider": "aws", + "namespace": "terraform-aws-modules", + "registry-name": "public", + "status": "setup_complete", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T20:16:20.538Z", + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws" + } + } +} +``` + +## Update a Private Registry Module + +`PATCH /organizations/:organization_name/registry-modules/private/:namespace/:name/:provider/` + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to update a module from. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The module namespace that the update affects. For private modules this is the name of the organization that owns the module. | +| `:name` | The module name that the update affects. | +| `:provider` | The name of the provider of the module that is being updated. | + +### Request Body + +These PATCH endpoints require a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-modules"`. | +| `data.attributes.vcs-repo.branch` | string | (previous value) | The repository branch that Terraform executes tests and publishes new versions from. This cannot be used with the `data.attributes.vcs-repo.tags` key. | +| `data.attributes.vcs-repo.tags` | boolean | (previous value) | Whether the registry module should be tag-based. This cannot be used with the `data.attributes.vcs-repo.branch` key. | +| `data.attributes.test-config.tests-enabled` | boolean | (previous value) | Allows you to enable or disable tests for the module. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "vcs-repo": { + "branch": "main", + "tags": false + }, + "test-config": { + "tests-enabled": true + } + }, + "type": "registry-modules" + } +} +``` + +### 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/my-organization/registry-modules/private/my-organization/registry-name/registry-provider/ +``` + +### Sample Response + +```json +{ + "data": { + "id": "mod-fZn7uHu99ZCpAKZJ", + "type": "registry-modules", + "attributes": { + "name": "my-module", + "namespace": "my-organization", + "registry-name": "private", + "provider": "aws", + "status": "pending", + "version-statuses": [], + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "vcs-repo": { + "branch": "main", + "ingress-submodules": true, + "identifier": "lafentres/terraform-aws-my-module", + "display-identifier": "lafentres/terraform-aws-my-module", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "webhook-url": "https://app.terraform.io/webhooks/vcs/a12b3456..." + }, + "permissions": { + "can-delete": true, + "can-resync": true, + "can-retry": true + }, + "test-config": { + "id": "tc-tcR6bxV5zE75Zb3B", + "tests-enabled": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws" + } + } +} +``` + +## Delete a Module + +
+ **Deprecation warning**: the following endpoints: + +- `POST /registry-modules/actions/delete/:organization_name/:name/:provider/:version` +- `POST /registry-modules/actions/delete/:organization_name/:name/:provider` +- `POST /registry-modules/actions/delete/:organization_name/:name` + +are replaced by the below endpoints and will be removed from future versions of the API! + +
+ +- `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider/:version` +- `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name/:provider` +- `DELETE /organizations/:organization_name/registry-modules/:registry_name/:namespace/:name` + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to delete a module from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The module namespace that the deletion will affect. For private modules this is the name of the organization that owns the module. | +| `:name` | The module name that the deletion will affect. | +| `:provider` | If specified, the provider for the module that the deletion will affect. | +| `:version` | If specified, the version for the module and provider that will be deleted. | +| `:registry_name` | Either `public` or `private` | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +When removing modules, there are three versions of the endpoint, depending on how many parameters are specified. + +- If all parameters (module namespace, name, provider, and version) are specified, the specified version for the given provider of the module is deleted. +- If module namespace, name, and provider are specified, the specified provider for the given module is deleted along with all its versions. +- If only module namespace and name are specified, the entire module is deleted. + +For public modules, only the the endpoint specifying the module namespace and name is valid. The other DELETE endpoints will 404. +For public modules, this only removes the record from the organization's HCP Terraform Registry and does not remove the public module from registry.terraform.io. + +If a version deletion would leave a provider with no versions, the provider will be deleted. If a provider deletion would leave a module with no providers, the module will be deleted. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public module curation disabled | +| [404][] | [JSON API error object][] | Module, provider, or version not found or user not authorized | + +### Sample Request (private module) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/private/my-organization/my-module/aws/2.0.0 +``` + +### Sample Request (public module) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-modules/public/terraform-aws-modules/vpc/aws +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/provider-versions-platforms.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/provider-versions-platforms.mdx new file mode 100644 index 0000000000..029dda55df --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/provider-versions-platforms.mdx @@ -0,0 +1,707 @@ +--- +page_title: /registry-providers API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/registry-providers` endpoint to read, + create, and delete private providers versions and platforms in your private + registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Private provider versions and platforms API reference + +These endpoints are only relevant to private providers. When you [publish a private provider](/terraform/enterprise/registry/publish-providers) to the HCP Terraform private registry, you must also create at least one version and at least one platform for that version before consumers can use the provider in configurations. Unlike the public Terraform Registry, the private registry does not automatically upload new releases. You must manually add new provider versions and the associated release files. + +All members of an organization can view and use both public and private providers, but you need [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or [Manage Private Registry](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) permissions to add, update, or delete provider versions and platforms in private registry. + +## Create a Provider Version + +`POST /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions` + +The private registry does not automatically update private providers when you release new versions. You must use this endpoint to add each new version. Consumers cannot use new versions until you upload all [required release files](/terraform/enterprise/registry/publish-providers#release-files) and [Create a Provider Platform](#create-a-provider-platform). + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a provider in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the version is being created. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the version is being created. | + +Creates a new registry provider version. This endpoint only applies to private providers. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-provider-versions"`) | Success | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"registry-provider-versions"`. | +| `data.attributes.version` | string | | A valid semver version string. | +| `data.attributes.key-id` | string | | A valid gpg-key string. | +| `data.attributes.protocols` | array | | An array of Terraform provider API versions that this version supports. Must be one or all of the following values `["4.0","5.0","6.0"]`. | + +-> **Note:** Only Terraform 0.13 and later support third-party provider registries, and that Terraform version requires provider API version 5.0 or later. So you do not need to list major versions 4.0 or earlier in the `protocols` attribute. + +### Sample Payload + +```json +{ + "data": { + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"] + } + } +} +``` + +### 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/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "created-at": "2022-02-11T19:16:59.876Z", + "updated-at": "2022-02-11T19:16:59.876Z", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"], + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "shasums-uploaded": false, + "shasums-sig-uploaded": false + }, + "relationships": { + "registry-provider": { + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers" + } + }, + "platforms": { + "data": [], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms" + } + } + }, + "links": { + "shasums-upload": "https://archivist.terraform.io/v1/object/dmF1b...", + "shasums-sig-upload": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} + +``` + +## Get All Versions for a Single Provider + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "created-at": "2022-02-11T19:16:59.876Z", + "updated-at": "2022-02-11T19:16:59.876Z", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"], + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "shasums-uploaded": true, + "shasums-sig-uploaded": true + }, + "relationships": { + "registry-provider": { + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers" + } + }, + "platforms": { + "data": [ + { + "id": "provpltfrm-GSHhNzptr9s3WoLD", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-A1PHitiM2KkKpVoM", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-qQYosUguetYtXGzJ", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-pjDHFN46y193bS7t", + "type": "registry-provider-platforms" + } + ], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms" + } + } + }, + "links": { + "shasums-download": "https://archivist.terraform.io/v1/object/dmF1b...", + "shasums-sig-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions?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 + } + } +} +``` + +**Note:** The `shasums-uploaded` and `shasums-sig-uploaded` properties will be false if those files have not been uploaded to Archivist. In this case, instead of including links to `shasums-download` and `shasums-sig-download`, the response will include upload links (`shasums-upload` and `shasums-sig-upload`). + +## Get a Version + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | +| `:version` | The version of the provider being created to which different platforms can be added. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1 +``` + +### Sample Response + +```json +{ + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions", + "attributes": { + "version": "3.1.1", + "created-at": "2022-02-11T19:16:59.876Z", + "updated-at": "2022-02-11T19:16:59.876Z", + "key-id": "32966F3FB5AC1129", + "protocols": ["5.0"], + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "shasums-uploaded": true, + "shasums-sig-uploaded": true + }, + "relationships": { + "registry-provider": { + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers" + } + }, + "platforms": { + "data": [ + { + "id": "provpltfrm-GSHhNzptr9s3WoLD", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-A1PHitiM2KkKpVoM", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-qQYosUguetYtXGzJ", + "type": "registry-provider-platforms" + }, + { + "id": "provpltfrm-pjDHFN46y193bS7t", + "type": "registry-provider-platforms" + } + ], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms" + } + } + }, + "links": { + "shasums-download": "https://archivist.terraform.io/v1/object/dmF1b...", + "shasums-sig-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} +``` + +**Note:** `shasums-uploaded` and `shasums-sig-uploaded` will be false if those files haven't been uploaded to Archivist yet. In this case, instead of including links to `shasums-download` and `shasums-sig-download`, the response will include upload links (`shasums-upload` and `shasums-sig-upload`). + +## Delete a Version + +`DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:provider_version` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to delete a provider version from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the version is being deleted. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the version is being deleted. | +| `:version` | The version for the provider that will be deleted along with its corresponding platforms. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user not authorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/public/hashicorp/aws/versions/3.1.1 +``` + +## Create a Provider Platform + +`POST /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms` + +Platforms are binaries that allow the provider to run on a particular operating system and architecture combination (e.g., Linux and AMD64). GoReleaser creates binaries automatically when you [create a release on GitHub](/terraform/registry/providers/publishing#creating-a-github-release) or [create a release locally](/terraform/registry/providers/publishing#using-goreleaser-locally). + +You must upload one or more platforms for each version of a private provider. After you create a platform, you must upload the platform binary file to the `provider-binary-upload` URL. + +### Parameters + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a provider platform in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the platform is being created. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the platform is being created. | +| `:version` | The provider version of the provider for which the platform is being created. | + +Creates a new registry provider platform. This endpoint only applies to private providers. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-provider-platforms"`) | Success | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - not available for public providers | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | ---------------------------------------- | +| `data.type` | string | | Must be `"registry-provider-platforms"`. | +| `data.attributes.os` | string | | A valid operating system string. | +| `data.attributes.arch` | string | | A valid architecture string. | +| `data.attributes.shasum` | string | | A valid shasum string. | +| `data.attributes.filename` | string | | A valid filename string. | + +### Sample Payload + +```json +{ + "data": { + "type": "registry-provider-version-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "shasum": "8f69533bc8afc227b40d15116358f91505bb638ce5919712fbb38a2dec1bba38", + "filename": "terraform-provider-aws_3.1.1_linux_amd64.zip" + } + } +} +``` + +### 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/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms +``` + +### Sample Response + +```json +{ + "data": { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "filename": "terraform-provider-aws_3.1.1_linux_amd64.zip", + "shasum": "8f69533bc8afc227b40d15116358f91505bb638ce5919712fbb38a2dec1bba38", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": false + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-upload": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} + +``` + +## Get All Platforms for a Single Version + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | +| `:version` | The version of the provider. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "provpltfrm-GSHhNzptr9s3WoLD", + "type": "registry-provider-platforms", + "attributes": { + "os": "darwin", + "arch": "amd64", + "filename": "terraform-provider-aws_3.1.1_darwin_amd64.zip", + "shasum": "fd580e71bd76d76913e1925f2641be9330c536464af9a08a5b8994da65a26cbc", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": true + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + }, + { + "id": "provpltfrm-A1PHitiM2KkKpVoM", + "type": "registry-provider-platforms", + "attributes": { + "os": "darwin", + "arch": "arm64", + "filename": "terraform-provider-aws_3.1.1_darwin_arm64.zip", + "shasum": "de3c351d7f35a3c8c583c0da5c1c4d558b8cea3731a49b15f63de5bbbafc0165", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": true + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +**Note:** The `provider-binary-uploaded` property will be `false` if that file has not been uploaded to Archivist. In this case, instead of including a link to `provider-binary-download`, the response will include an upload link `provider-binary-upload`. + +## Get a Platform + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms/:os/:arch` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider. Must be the same as the `organization_name` for the provider. | +| `:name` | The provider name. | +| `:version` | The version of the provider. | +| `:os` | The operating system of the provider platform. | +| `:arch` | The architecture of the provider platform. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms/linux/amd64 +``` + +### Sample Response + +```json +{ + "data": { + "id": "provpltfrm-BLJWvWyJ2QMs525k", + "type": "registry-provider-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "filename": "terraform-provider-aws_3.1.1_linux_amd64.zip", + "shasum": "8f69533bc8afc227b40d15116358f91505bb638ce5919712fbb38a2dec1bba38", + "permissions": { + "can-delete": true, + "can-upload-asset": true + }, + "provider-binary-uploaded": true + }, + "relationships": { + "registry-provider-version": { + "data": { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + } + }, + "links": { + "provider-binary-download": "https://archivist.terraform.io/v1/object/dmF1b..." + } + } +} +``` + +**Note:** The `provider-binary-uploaded` property will be `false` if that file has not been uploaded to Archivist. In this case, instead of including a link to `provider-binary-download`, the response will include an upload link `provider-binary-upload`. + +## Delete a Platform + +`DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name/versions/:version/platforms/:os/:arch` + +### Parameters + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to delete a provider platform from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Must be `private`. | +| `:namespace` | The namespace of the provider for which the platform is being deleted. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The name of the provider for which the platform is being deleted. | +| `:version` | The version for which the platform is being deleted. | +| `:os` | The operating system of the provider platform that is being deleted. | +| `:arch` | The architecture of the provider platform that is being deleted. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user not authorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws/versions/3.1.1/platforms/linux/amd64 +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/providers.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/providers.mdx new file mode 100644 index 0000000000..44719c2f16 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/providers.mdx @@ -0,0 +1,471 @@ +--- +page_title: /registry-providers API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's organization `/registry-providers` endpoint + to list, create, get, and delete providers in your private registry. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Registry providers API reference + +You can add publicly curated providers from the [Terraform Registry](https://registry.terraform.io/) and custom, private providers to your HCP Terraform private registry. The private registry stores a pointer to public providers so that you can view their data from within HCP Terraform. This lets you clearly designate all of the providers that are recommended for the organization and makes them centrally accessible. + +All members of an organization can view and use both public and private providers, but you need [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or [Manage Private Registry](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) permissions to add, update, or delete them them in private registry. + +## HCP Terraform Registry Implementation + +For publicly curated providers, the HCP Terraform Registry acts as a proxy to the [Terraform Registry](https://registry.terraform.io) for the following: + +- The public registry discovery endpoints have the path prefix provided in the [discovery document](/terraform/registry/api-docs#service-discovery) which is currently `/api/registry/public/v1`. +- [Authentication](/terraform/enterprise/api-docs#authentication) is handled the same as all other HCP Terraform endpoints. + +## List Terraform Registry Providers for an Organization + +`GET /organizations/:organization_name/registry-providers` + +### Parameters + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------- | +| `:organization_name` | The name of the organization to list available providers from. | + +Lists the providers included in the private registry for the specified organization. + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | ---------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [404][] | [JSON API error object][] | Providers not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** A search query string. Providers are searchable by both their name and their namespace fields. | +| `filter[field name]` | **Optional.** If specified, restricts results to those with the matching field name value. Valid values are `registry_name`, and `organization_name`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 registry providers per page. | + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "prov-kwt1cBiX2SdDz38w", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "my-organization", + "created-at": "2021-04-07T19:01:18.528Z", + "updated-at": "2021-04-07T19:01:19.863Z", + "registry-name": "public", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aws" + } + }, + { + "id": "prov-PopQnMtYDCcd3PRX", + "type": "registry-providers", + "attributes": { + "name": "aurora", + "namespace": "my-organization", + "created-at": "2021-04-07T19:04:41.375Z", + "updated-at": "2021-04-07T19:04:42.828Z", + "registry-name": "public", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/my-organization/aurora" + } + }, + ..., + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=1&page%5Bsize%5D=6", + "prev": null, + "next": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=2&page%5Bsize%5D=6", + "last": "https://app.terraform.io/api/v2/organizations/my-organization/registry-providers?page%5Bnumber%5D=29&page%5Bsize%5D=6" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 6, + "prev-page": null, + "next-page": 2, + "total-pages": 29, + "total-count": 169 + } + } +} +``` + +## Create a Provider + +`POST /organizations/:organization_name/registry-providers` + +Use this endpoint to create both public and private providers: + +- **Public providers:** The public provider record will be available in the organization's registry provider list immediately after creation. You cannot create versions for public providers; you must use the versions available on the Terraform Registry. +- **Private providers:** The private provider record will be available in the organization's registry provider list immediately after creation, but you must [create a version and upload release assets](/terraform/enterprise/registry/publish-providers#publishing-a-provider-and-creating-a-version) before consumers can use it. The private registry does not automatically update private providers when you release new versions. You must add each new version with the [Create a Provider Version](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-version) endpoint. + +### Parameters + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create a provider in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "registry-providers"`) | Successfully published provider | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +~> **Important:** For private providers, you must also create a version, a platform, and upload release assets before consumers can use the provider. Refer to [Publishing a Private Provider](/terraform/enterprise/registry/publish-providers) for more details. + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"registry-providers"`. | +| `data.attributes.name` | string | | The name of the provider. | +| `data.attributes.namespace` | string | | The namespace of the provider. For private providers this is the same as the `:organization_name` parameter. | +| `data.attributes.registry-name` | string | | Whether this is a publicly maintained provider or private. Must be either `public` or `private`. | + +### Sample Payload (Private Provider) + +```json +{ + "data": { + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "private" + } + } +} +``` + +### Sample Payload (Public Provider) + +```json +{ + "data": { + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "public" + } + } +} +``` + +### 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/organizations/my-organization/registry-providers +``` + +### Sample Response (Private Provider) + +```json +{ + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "private", + "created-at": "2022-02-11T19:16:59.533Z", + "updated-at": "2022-02-11T19:16:59.533Z", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "versions": { + "data": [], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } +} +``` + +### Sample Response (Public Provider) + +```json +{ + "data": { + "id": "prov-fZn7uHu99ZCpAKZJ", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "public", + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T19:36:56.288Z", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws" + } + } +} +``` + +## Get a Provider + +`GET /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name` + +### Parameters + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization the provider belongs to. | +| `:registry_name` | Whether this is a publicly maintained provider or private. Must be either `public` or `private`. | +| `:namespace` | The namespace of the provider. For private providers this is the same as the `:organization_name` parameter. | +| `:name` | The provider name. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "registry-providers"`) | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user unauthorized to perform action | + +### Sample Request (Private Provider) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws +``` + +### Sample Request (Public Provider) + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws +``` + +### Sample Response (Private Provider) + +```json +{ + "data": { + "id": "prov-cmEmLstBfjNNA9F3", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "created-at": "2022-02-11T19:16:59.533Z", + "updated-at": "2022-02-11T19:16:59.533Z", + "registry-name": "private", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "versions": { + "data": [ + { + "id": "provver-y5KZUsSBRLV9zCtL", + "type": "registry-provider-versions" + } + ], + "links": { + "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } + }, + "links": { + "self": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws" + } + } +} +``` + +### Sample Response (Public Provider) + +```json +{ + "data": { + "id": "prov-fZn7uHu99ZCpAKZJ", + "type": "registry-providers", + "attributes": { + "name": "aws", + "namespace": "hashicorp", + "registry-name": "public", + "created-at": "2020-07-09T19:36:56.288Z", + "updated-at": "2020-07-09T20:16:20.538Z", + "permissions": { + "can-delete": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + }, + "links": { + "self": "/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws" + } + } +} +``` + +## Delete a Provider + +`DELETE /organizations/:organization_name/registry-providers/:registry_name/:namespace/:name` + +### Parameters + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to delete a provider from. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:registry_name` | Whether this is a publicly maintained provider or private. Must be either `public` or `private`. | +| `:namespace` | The namespace of the provider that will be deleted. | +| `:name` | The name of the provider that will be deleted. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Success | +| [403][] | [JSON API error object][] | Forbidden - public provider curation disabled | +| [404][] | [JSON API error object][] | Provider not found or user not authorized to perform action | + +### Sample Request (Private Provider) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/aws +``` + +### Sample Request (Public Provider) + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/registry-providers/public/hashicorp/aws +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/tests.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/tests.mdx new file mode 100644 index 0000000000..ea1b7f4b60 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/private-registry/tests.mdx @@ -0,0 +1,755 @@ +--- +page_title: /tests API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/tests` endpoint to list, get, create, and + cancel Terraform test runs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Tests API reference + +Tests are terraform operations(runs) and are referred to as Test Runs within the HCP Terraform API. + +Performing a test on a new configuration is a multi-step process. + +1. [Create a configuration version on the registry module](#create-a-configuration-version-for-a-test). +2. [Upload configuration files to the configuration version](#upload-configuration-files-for-a-test). +3. [Create a test on the module](#create-a-test-run); HCP Terraform completes this step automatically when you upload a configuration file. + +Alternatively, you can create a test with a pre-existing configuration version, even one from another module. This is useful for promoting known good code from one module to another. + +## Attributes + +The `tests` API endpoint has the following attributes. + +### Test Run States + +The state of the test operation is found in `data.attributes.status`, and you can reference the following list of possible states. + +| State | Description | +| ---------- | ----------------------------------------------------- | +| `pending` | The initial status of a run after creation. | +| `queued` | HCP Terraform has queued the test operation to start. | +| `running` | HCP Terraform is executing the test. | +| `errored` | The test has errored. This is a final state. | +| `canceled` | The test has been canceled. This is a final state. | +| `finished` | The test has completed. This is a final state. | + +### Test run status + +The final test status is found in `data.attributes.test-status`, and you can reference the following list of possible states. + +| Status | Description | +| ------ | ---------------------------- | +| `pass` | The given tests have passed. | +| `fail` | The given tests have failed. | + +### Detailed test status + +The test results can be found via the following attributes + +| Status | Description | | +| ------------------------------- | ------------------------------------------- | - | +| `data.attributes.tests-passed` | The number of tests that have passed. | | +| `data.attributes.tests-failed` | The number of tests that have failed. | | +| `data.attributes.tests-errored` | The number of tests that have errored out. | | +| `data.attributes.tests-skipped` | The number of tests that have been skipped. | | + +### Test Sources + +List tests for a module. You can use the following sources as [tests list](/terraform/enterprise/api-docs/private-registry/tests#list-tests-for-a-module) query parameters. + +| Source | Description | +| --------------------------- | ---------------------------------------------------------------------------------------- | +| `terraform` | Indicates a test was queued from HCP Terraform CLI. | +| `tfe-api` | Indicates a test was queued from HCP Terraform API. | +| `tfe-configuration-version` | Indicates a test was queued from a Configuration Version, triggered from a VCS provider. | + +## Create a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the test is being created. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test is being created. | +| `:provider` | The name of the provider for which the test is being created. | + +A test run executes tests against a registry module, using a configuration version and the modules’s current environment variables. + +Creating a test run requires permission to access the specified module. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for more information. + +When creating a test run, you may optionally provide a list of variable objects containing key and value attributes. These values apply to that test run specifically and take precedence over variables with the same key that are created within the module. All values must be expressed as an HCL literal in the same syntax you would use when writing Terraform code. + +**Sample Test Variables:** + +```json +"attributes": { + "variables": [ + { "key": "replicas", "value": "2" }, + { "key": "access_key", "value": "\"ABCDE12345\"" } + ] +} +``` + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------------------------------------- | -------------------- | ------------- | -------------------------------------------------------------------------------------------------- | +| `data.attributes.verbose` | bool | `false` | Specifies whether Terraform should print the plan or state for each test run block as it executes. | +| `data.attributes.test-directory` | string | `"tests"` | Sets the directory where HCP Terraform executes the tests. | +| `data.attributes.filters` | array\[string] | (empty array) | When specified, HCP Terraform only executes the test files contained within this array. | +| `data.attributes.variables` | array\[{key, value}] | (empty array) | Specifies an optional list of test-specific environment variable values. | +| `data.relationships.configuration-version.data.id` | string | none | Specifies the configuration version that HCP Terraform executes the test against. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "verbose": true, + "filters": ["tests/test.tftest.hcl"], + "test-directory": "tests", + "variables": [ + { "key" : "number", "value": 4} + ] + }, + "type":"test-runs" + } +} +``` + +### 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/organizations/my-organization/tests/registry-modules/private/my-organization/private/registry-provider/test-runs +``` + +### Sample Response + +```json +{ + "data": { + "id": "trun-KFg8DSiRz4E37mdJ", + "type": "test-runs", + "attributes": { + "status": "queued", + "status-timestamps": { + "queued-at": "2023-10-03T18:27:39+00:00" + }, + "created-at": "2023-10-03T18:27:39.239Z", + "updated-at": "2023-10-03T18:27:39.264Z", + "test-configurable-type": "RegistryModule", + "test-configurable-id": "mod-9rjVHLCUE9QD3k6L", + "variables": [ + { + "key": "number", + "value": "4" + } + ], + "filters": [ + "tests/test.tftest.hcl" + ], + "test-directory": "tests", + "verbose": true, + "test-status": null, + "tests-passed": null, + "tests-failed": null, + "tests-errored": null, + "tests-skipped": null, + "source": "tfe-api", + "message": "Queued manually via the Terraform Enterprise API" + }, + "relationships": { + "configuration-version": { + "data": { + "id": "cv-d3zBGFf5DfWY4GY9", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9" + } + }, + "created-by": { + "data": { + "id": "user-zsRFs3AGaAHzbEfs", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs" + } + } + } + } +} +``` + +## Create a Configuration Version for a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/configuration-versions` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the configuration version is being created. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the configuration version is being created. | +| `:provider` | The name of the provider for which the configuration version is being created. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/configuration-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "cv-aaady7niJMY1wAvx", + "type": "configuration-versions", + "attributes": { + "auto-queue-runs": true, + "error": null, + "error-message": null, + "source": "tfe-api", + "speculative": false, + "status": "pending", + "status-timestamps": {}, + "changed-files": [], + "provisional": false, + "upload-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv" + }, + "relationships": { + "ingress-attributes": { + "data": null, + "links": { + "related": "/api/v2/configuration-versions/cv-aaady7niJMY1wAvx/ingress-attributes" + } + } + }, + "links": { + "self": "/api/v2/configuration-versions/cv-aaady7niJMY1wAvx" + } + } +} +``` + +## Upload Configuration Files for a Test + +`PUT https://archivist.terraform.io/v1/object/` + +**The URL is provided in the `upload-url` attribute when creating a `configuration-versions` resource. After creation, the URL is hidden on the resource and no longer available.** + +### Sample Request + +**@filename is the name of the configuration file you wish to upload.** + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @filename \ + https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da +``` + +## List Tests for a Module + +`GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module which the tests have executed against. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module which the tests have executed against. | +| `:provider` | The name of the provider which the tests have executed against. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling does not automatically encode URLs. + +| Parameter | Description | Required | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `page[number]` | If omitted, the endpoint returns the first page. | Optional | +| `page[size]` | If omitted, the endpoint returns 20 runs per page. | Optional | +| `filter[source]` | **Optional.** A comma-separated list of test sources; the result will only include tests that came from one of these sources. Options are listed in [Test Sources](/terraform/enterprise/api-docs/private-registry/tests#test-sources). | | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "trun-KFg8DSiRz4E37mdJ", + "type": "test-runs", + "attributes": { + "status": "finished", + "status-timestamps": { + "queued-at": "2023-10-03T18:27:39+00:00", + "started-at": "2023-10-03T18:27:41+00:00", + "finished-at": "2023-10-03T18:27:53+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv", + "created-at": "2023-10-03T18:27:39.239Z", + "updated-at": "2023-10-03T18:27:53.574Z", + "test-configurable-type": "RegistryModule", + "test-configurable-id": "mod-9rjVHLCUE9QD3k6L", + "variables": [ + { + "key": "number", + "value": "4" + } + ], + "filters": [ + "tests/test.tftest.hcl" + ], + "test-directory": "tests", + "verbose": true, + "test-status": "pass", + "tests-passed": 1, + "tests-failed": 0, + "tests-errored": 0, + "tests-skipped": 0, + "source": "tfe-api", + "message": "Queued manually via the Terraform Enterprise API" + }, + "relationships": { + "configuration-version": { + "data": { + "id": "cv-d3zBGFf5DfWY4GY9", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9" + } + }, + "created-by": { + "data": { + "id": "user-zsRFs3AGaAHzbEfs", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs" + } + } + } + }, + {...} + ] +} +``` + +## Get Test Details + +`GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module which the test was executed against. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module which the test was executed against. | +| `:provider` | The name of the provider which the test was executed against. | +| `:test_run_id` | The test ID to get. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7 +``` + +### Sample Response + +```json +{ + "data": { + "id": "trun-KFg8DSiRz4E37mdJ", + "type": "test-runs", + "attributes": { + "status": "finished", + "status-timestamps": { + "queued-at": "2023-10-03T18:27:39+00:00", + "started-at": "2023-10-03T18:27:41+00:00", + "finished-at": "2023-10-03T18:27:53+00:00" + }, + "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv", + "created-at": "2023-10-03T18:27:39.239Z", + "updated-at": "2023-10-03T18:27:53.574Z", + "test-configurable-type": "RegistryModule", + "test-configurable-id": "mod-9rjVHLCUE9QD3k6L", + "variables": [ + { + "key": "number", + "value": "4" + } + ], + "filters": [ + "tests/test.tftest.hcl" + ], + "test-directory": "tests", + "verbose": true, + "test-status": "pass", + "tests-passed": 1, + "tests-failed": 0, + "tests-errored": 0, + "tests-skipped": 0, + "source": "tfe-api", + "message": "Queued manually via the Terraform Enterprise API" + }, + "relationships": { + "configuration-version": { + "data": { + "id": "cv-d3zBGFf5DfWY4GY9", + "type": "configuration-versions" + }, + "links": { + "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9" + } + }, + "created-by": { + "data": { + "id": "user-zsRFs3AGaAHzbEfs", + "type": "users" + }, + "links": { + "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs" + } + } + } + } +} +``` + +## Cancel a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id/cancel` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create a test in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the test is being canceled. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test is being canceled. | +| `:provider` | The name of the provider for which the test is being canceled. | +| `:test_run_id` | The test ID to cancel. | + +Use the `cancel` action to interrupt a test that is currently running. The action sends an `INT` signal to the running Terraform process, which instructs Terraform to safely end the tests and attempt to teardown any infrastructure that your tests create. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------ | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Test was not running; cancel not allowed. | +| [404][] | [JSON API error object][] | Test was not found or user not authorized. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7/cancel +``` + +## Forcefully cancel a Test + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id/force-cancel` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The namespace of the module for which the test is being force-canceled. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test is being force-canceled. | +| `:provider` | The name of the provider for which the test is being force-canceled. | +| `:test_run_id` | The test ID to cancel. | + +The `force-cancel` action ends the test immediately. Once invoked, Terraform places the test into a `canceled` state and terminates the running Terraform process. + +~> **Warning:** This endpoint has potentially dangerous side-effects, including loss of any in-flight state in the running Terraform process. Use this operation with extreme caution. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | -------------------------------------------------------------- | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Test was not running, or has not been canceled non-forcefully. | +| [404][] | [JSON API error object][] | Test was not found or user not authorized. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7/force-cancel +``` + +## Create an Environment Variable for Module Tests + +`POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization of the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the testing environment variable is being created. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the testing environment variable is being created. | +| `:provider` | The name of the provider for which the testing environment variable is being created. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"vars"`. | +| `data.attributes.key` | string | none | The variable's name. Test variable keys must begin with a letter or underscore and can only contain letters, numbers, and underscores. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | none | The description of the variable. | +| `data.attributes.category` | string | none | This must be `"env"`. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. When set to `true`, Terraform writes the variable once and is not visible thereafter. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "category":"env", + "sensitive":false + } + } +} +``` + +### 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/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars +``` + +### Sample Response + + { + "data": { + "id": "var-xSCUzCxdqMs2ygcg", + "type": "vars", + "attributes": { + "key": "keykey", + "value": "some_value", + "sensitive": false, + "category": "env", + "hcl": false, + "created-at": "2023-10-03T19:47:05.393Z", + "description": "some description", + "version-id": "699b14ea5d5e5c02f6352fac6bfd0a1424c21d32be14d1d9eb79f5e1f28f663a" + }, + "links": { + "self": "/api/v2/vars/var-xSCUzCxdqMs2ygcg" + } + } + } + +## List Test Variables for a Module + +`GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The namespace of the module which the test environment variables were created for. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module which the test environment variables were created for. | +| `:provider` | The name of the provider which the test environment variables were created for. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "var-xSCUzCxdqMs2ygcg", + "type": "vars", + "attributes": { + "key": "keykey", + "value": "some_value", + "sensitive": false, + "category": "env", + "hcl": false, + "created-at": "2023-10-03T19:47:05.393Z", + "description": "some description", + "version-id": "699b14ea5d5e5c02f6352fac6bfd0a1424c21d32be14d1d9eb79f5e1f28f663a" + }, + "links": { + "self": "/api/v2/vars/var-xSCUzCxdqMs2ygcg" + } + } + ] +} +``` + +## Update Test Variables for a Module + +`PATCH /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars/variable_id` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. | +| `:namespace` | The namespace of the module for which the test environment variable is being updated. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test environment variable is being updated. | +| `:provider` | The name of the provider for which the test environment variable is being updated. | +| `:variable_id` | The ID of the variable to update. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes` | object | none | New attributes for the variable. This object can include `key`, `value`, `description`, `category`, and `sensitive` properties. Refer to [Create an Environment Variable for Module Tests](#create-an-environment-variable-for-module-tests) for additional information. All properties are optional. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "key":"name", + "value":"mars", + "description": "new description", + "category":"env", + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "description":"new description", + "sensitive":false, + "category":"env", + "hcl":false + } + } +} +``` + +## Delete Test Variable for a Module + +`DELETE /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars/variable_id` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the `owners` team or a member of the `owners` team. | +| `:namespace` | The namespace of the module for which the test environment variable is being deleted. For private modules this is the same as the `:organization_name` parameter. | +| `:name` | The name of the module for which the test environment variable is being deleted. | +| `:provider` | The name of the provider for which the test environment variable is being deleted. | +| `:variable_id` | The ID of the variable to delete. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars/var-yRmifb4PJj7cLkMG +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/project-team-access.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/project-team-access.mdx new file mode 100644 index 0000000000..84b479ca00 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/project-team-access.mdx @@ -0,0 +1,523 @@ +--- +page_title: /team-projects API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/team-projects` endpoint to read, add, + update, and remove team access from a project. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Project team access API reference + + + +@include 'tfc-package-callouts/project-permissions.mdx' + + + +The team access APIs are used to associate a team to permissions on a project. A single `team-project` resource contains the relationship between the Team and Project, including the privileges the team has on the project. + +## Resource permissions + +A `team-project` resource represents a team's local permissions on a specific project. Teams can also have organization-level permissions that grant access to projects. HCP Terraform uses the more restrictive access level. For example, a team with the **Manage projects** permission enabled has admin access on all projects, even if their `team-project` on a particular project only grants read access. For more information, refer to [Managing Project Access](/terraform/enterprise/users-teams-organizations/teams/manage#managing-project-access). + +Any member of an organization can view team access relative to their own team memberships, including secret teams of which they are a member. Organization owners and project admins can modify team access or view the full set of secret team accesses. The organization token and the owners team token can act as an owner on these endpoints. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +## Project Team Access Levels + +| Access Level | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `read` | Read project and Read workspace access role on project workspaces | +| `write` | Read project and Write workspace access role on project workspaces | +| `maintain` | Read project and Admin workspace access role on project workspaces | +| `admin` | Admin project, Admin workspace access role on project workspaces, create workspaces within project, move workspaces between projects, manage project team access | +| `custom` | Custom access permissions on project and project's workspaces | + +## List Team Access to a Project + +`GET /team-projects` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Project not found or user unauthorized to perform action | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). + +| Parameter | Description | +| --------------------- | ----------------------------------------------------- | +| `filter[project][id]` | **Required.** The project ID to list team access for. | +| `page[number]` | **Optional.** | +| `page[size]` | **Optional.** | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tprj-TLznAnYdcsD2Dcmm", + "type": "team-projects", + "attributes": { + "access": "read", + "project-access": { + "settings": "read", + "teams": "none" + }, + "workspace-access": { + "create": false, + "move": false, + "locking": false, + "delete": false, + "runs": "read", + "variables": "read", + "state-versions": "read", + "sentinel-mocks": "none", + "run-tasks": false + } + }, + "relationships": { + "team": { + "data": { + "id": "team-KpibQGL5GqRAWBwT", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-KpibQGL5GqRAWBwT" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-TLznAnYdcsD2Dcmm" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/team-projects?filter%5Bproject%5D%5Bid%5D=prj-ckZoJwdERaWcFHwi&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 + } + } +} +``` + +## Show a Team Access relationship + +`GET /team-projects/:id` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Team access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/project relationship. Obtain this from the [list team access action](#list-team-access-to-a-project) described above. | + +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". + +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). + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/team-projects/tprj-s68jV4FWCDwWvQq8 +``` + +### Sample Response + +```json +{ + "data": { + "id": "tprj-TLznAnYdcsD2Dcmm", + "type": "team-projects", + "attributes": { + "access": "read", + "project-access": { + "settings": "read", + "teams": "none" + }, + "workspace-access": { + "create": false, + "move": false, + "locking": false, + "delete": false, + "runs": "read", + "variables": "read", + "state-versions": "read", + "sentinel-mocks": "none", + "run-tasks": false + } + }, + "relationships": { + "team": { + "data": { + "id": "team-KpibQGL5GqRAWBwT", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-KpibQGL5GqRAWBwT" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-TLznAnYdcsD2Dcmm" + } + } +} +``` + +## Add Team Access to a Project + +`POST /team-projects` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | ---------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Project or Team not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"team-projects"`. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `write`, `maintain`, `admin`, or `custom`. | +| `data.relationships.project.data.type` | string | | Must be `projects`. | +| `data.relationships.project.data.id` | string | | The project ID to which the team is to be added. | +| `data.relationships.team.data.type` | string | | Must be `teams`. | +| `data.relationships.team.data.id` | string | | The ID of the team to add to the project. | +| `data.attributes.project-access.settings` | string | "read" | If `access` is `custom`, the permission to grant for the project's settings. Can only be used when `access` is `custom`. Valid values include `read`, `update`, or `delete`. | +| `data.attributes.project-access.teams` | string | "none" | If `access` is `custom`, the permission to grant for the project's teams. Can only be used when `access` is `custom`. Valid values include `none`, `read`, or `manage`. | +| `data.attributes.workspace-access.runs` | string | "read" | If `access` is `custom`, the permission to grant for the project's workspaces' runs. Can only be used when `access` is `custom`. Valid values include `read`, `plan`, or `apply`. | +| `data.attributes.workspace-access.sentinel-mocks` | string | "none" | If `access` is `custom`, the permission to grant for the project's workspaces' Sentinel mocks. Can only be used when `access` is `custom`. Valid values include `none`, or `read`. | +| `data.attributes.workspace-access.state-versions` | string | "none" | If `access` is `custom`, the permission to grant for the project's workspaces state versions. Can only be used when `access` is `custom`. Valid values include `none`, `read-outputs`, `read`, or `write`. | +| `data.attributes.workspace-access.variables` | string | "none" | If `access` is `custom`, the permission to grant for the project's workspaces' variables. Can only be used when `access` is `custom`. Valid values include `none`, `read`, or `write`. | +| `data.attributes.workspace-access.create` | boolean | false | If `access` is `custom`, this permission allows the team to create workspaces in the project. | +| `data.attributes.workspace-access.locking` | boolean | false | If `access` is `custom`, the permission granting the ability to manually lock or unlock the project's workspaces. Can only be used when `access` is `custom`. | +| `data.attributes.workspace-access.delete` | boolean | false | If `access` is `custom`, the permission granting the ability to delete the project's workspaces. Can only be used when `access` is `custom`. | +| `data.attributes.workspace-access.move` | boolean | false | If `access` is `move`, this permission allows the team to move workspaces into and out of the project. The team must also have permissions to the project(s) receiving the the workspace(s). | +| `data.attributes.workspace-access.run-tasks` | boolean | false | If `access` is `custom`, this permission allows the team to manage run tasks within the project's workspaces. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "access": "read" + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-ckZoJwdERaWcFHwi" + } + }, + "team": { + "data": { + "type": "teams", + "id": "team-xMGyoUhKmTkTzmAy" + } + } + }, + "type": "team-projects" + } +} +``` + +### 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/team-projects +``` + +### Sample Response + +```json +{ + "data": { + "id": "tprj-WbG7p5KnT7S7HZqw", + "type": "team-projects", + "attributes": { + "access": "read", + "project-access": { + "settings": "read", + "teams": "none" + }, + "workspace-access": { + "create": false, + "move": false, + "locking": false, + "runs": "read", + "variables": "read", + "state-versions": "read", + "sentinel-mocks": "none", + "run-tasks": false + } + }, + "relationships": { + "team": { + "data": { + "id": "team-xMGyoUhKmTkTzmAy", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-xMGyoUhKmTkTzmAy" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw" + } + } +} +``` + +## Update Team Access to a Project + +`PATCH /team-projects/:id` + +| Status | Response | Reason | +| ------- | ----------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-projects"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +| Parameter | | | Description | +| ------------------------ | ------ | - | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | | | The ID of the team/project relationship. Obtain this from the [list team access action](#list-team-access-to-a-project) described above. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `write`, `maintain`, `admin`, or `custom`. | + +### 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/team-projects/tprj-WbG7p5KnT7S7HZqw +``` + +### Sample Payload + +```json +{ + "data": { + "id": "tprj-WbG7p5KnT7S7HZqw", + "attributes": { + "access": "custom", + "project-access": { + "settings": "delete" + "teams": "manage", + }, + "workspace-access" : { + "runs": "apply", + "sentinel-mocks": "read", + "state-versions": "write", + "variables": "write", + "create": true, + "locking": true, + "delete": true, + "move": true, + "run-tasks": true + } + } + } +} +``` + +### Sample Response + +```json +{ + "data": { + "id": "tprj-WbG7p5KnT7S7HZqw", + "type": "team-projects", + "attributes": { + "access": "custom", + "project-access": { + "settings": "delete" + "teams": "manage", + }, + "workspace-access" : { + "runs": "apply", + "sentinel-mocks": "read", + "state-versions": "write", + "variables": "write", + "create": true, + "locking": true, + "delete": true, + "move": true, + "run-tasks": true + } + }, + "relationships": { + "team": { + "data": { + "id": "team-xMGyoUhKmTkTzmAy", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-xMGyoUhKmTkTzmAy" + } + }, + "project": { + "data": { + "id": "prj-ckZoJwdERaWcFHwi", + "type": "projects" + }, + "links": { + "related": "/api/v2/projects/prj-ckZoJwdERaWcFHwi" + } + } + }, + "links": { + "self": "/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw" + } + } +} +``` + +## Remove Team Access from a Project + +`DELETE /team-projects/:id` + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | | The Team Access was successfully destroyed | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/project relationship. Obtain this from the [list team access action](#list-team-access-to-a-project) described above. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/team-projects/tprj-WbG7p5KnT7S7HZqw +``` + +## Implied Custom Permission Levels + +As mentioned above, when setting team access levels (`read`, `write`, `maintain`, or `admin`), you can individually set the following permissions if you use the `custom` access level. +The below table lists each access level alongside its implicit custom permission level. If you use the `custom` access level and do not specify a certain permission's level, that permission uses the default value listed below. + +| Permissions | `read` | `write` | `maintain` | `admin ` | `custom` default | +| ------------------------------- | ------ | ------- | ---------- | -------- | ---------------- | +| project-access.settings | "read" | "read" | "read" | "delete" | "read" | +| project-access.teams | "none" | "none" | "none" | "manage" | "none" | +| workspace-access.runs | "read" | "apply" | "apply" | "apply" | "read" | +| workspace-access.sentinel-mocks | "none" | "read" | "read" | "read" | "none" | +| workspace-access.state-versions | "read" | "write" | "write" | "write" | "none" | +| workspace-access.variables | "read" | "write" | "write" | "write" | "none" | +| workspace-access.create | false | false | true | true | false | +| workspace-access.locking | false | true | true | true | false | +| workspace-access.delete | false | false | true | true | false | +| workspace-access.move | false | false | false | true | false | +| workspace-access.run-tasks | false | false | true | true | false | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/projects.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/projects.mdx new file mode 100644 index 0000000000..ef2f797665 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/projects.mdx @@ -0,0 +1,718 @@ +--- +page_title: /projects API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/projects` endpoint to list, show, create, + update, and delete an organization's projects. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Projects API reference + +This topic provides reference information about the projects API. + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +| -------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST` | `/organizations/:organization_name/projects` | Call this endpoint to [create a project](#create-a-project). | +| `PATCH` | `/projects/:project_id` | Call this endpoint to [update an existing project](#update-a-project). | +| `GET` | `/organizations/:organization_name/projects` | Call this endpoint to [list existing projects](#list-projects). | +| `GET` | `/projects/:project_id` | Call this endpoint to [show project details](#show-project). | +| `DELETE` | `/projects/:project_id` | Call this endpoint to [delete a project](#delete-a-project). | +| `GET` | `/projects/:project_id/tag-bindings` | Call this endpoint to [list project tag bindings](#list-project-tag-bindings). (For projects, this returns the same result set as the `effective-tag-bindings` endpoint.) | +| `GET` | `/projects/:project_id/effective-tag-bindings` | Call this endpoint to [list project effective tag bindings](#list-project-tag-bindings). (For projects, this returns the same result set as the `tag-bindings` endpoint.) | + +## Requirements + +You must be on a team with one of the **Owners** or **Manage projects** permissions settings enabled to create and manage projects. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +You can also provide an organization API token to call project API endpoints. Refer to [Organization API Tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) for additional information. + +## Create a Project + +`POST /organizations/:organization_name/projects` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `: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. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"projects"`. | +| `data.attributes.name` | string | | The name of the project. The name can contain letters, numbers, spaces, `-`, and `_`, but cannot start or end with spaces. It must be at least three characters long and no more than 40 characters long. | +| `data.attributes.description` | string | none | Optional. The description of the project. It must be no more than 256 characters long. | +| `data.attributes.auto-destroy-activity-duration` | string | none | Specifies the default for how long each workspace in the project should wait before automatically destroying its infrastructure. You can specify a duration up to four digits that is greater than `0` followed by either a `d` for days or `h` hours. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. All future workspaces in this project inherit this default value. Refer to [Automatically destroy inactive workspaces](/terraform/enterprise/projects/managing#automatically-destroy-inactive-workspaces) for additional information. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to bind to the project. Workspaces inherit the tags bound to their project. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "Test Project", + "description": "An example project for documentation.", + }, + "type": "projects", + "relationships": { + "tag-bindings": { + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "environment", + "value": "development" + } + }, + ] + } + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/projects +``` + +### Sample Response + +```json +{ + "data": { + "id": "prj-WsVcWRr7SfxRci1v", + "type": "projects", + "attributes": { + "name": "Test Project", + "description": "An example project for documentation.", + "permissions": { + "can-update": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v" + } + } +} +``` + +## Update a Project + +Call the following endpoint to update a project: + +`PATCH /projects/:project_id` + +| Parameter | Description | +| ------------- | ------------------------------- | +| `:project_id` | The ID of the project to update | + +### Request Body + +These PATCH endpoints require a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"projects"`. | +| `data.attributes.name` | string | existing value | A new name for the project. The name can contain letters, numbers, spaces, `-`, and `_`, but cannot start or end with spaces. It must be at least 3 characters long and no more than 40 characters long. | +| `data.attributes.description` | string | existing value | The new description for the project. It must be no more than 256 characters long. | +| `data.attributes.auto-destroy-activity-duration` | string | none | Specifies how long each workspace in the project should wait before automatically destroying its infrastructure by default. You can specify a duration up to four digits that is greater than `0` followed by either a `d` for days or `h` hours. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. When you update this value, all workspaces in the project receive the new value unless you previously configured an override. Refer to [Automatically destroy inactive workspaces](/terraform/enterprise/projects/managing#automatically-destroy-inactive-workspaces) for additional information. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to bind to the project. Workspaces inherit the tags bound to their project. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "Infrastructure Project" + }, + "type": "projects", + "relationships": { + "tag-bindings": { + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "environment", + "value": "staging" + } + } + ] + } + } + } +} +``` + +### 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/projects/prj-WsVcWRr7SfxRci1v +``` + +### Sample Response + +```json +{ + "data": { + "id": "prj-WsVcWRr7SfxRci1v", + "type": "projects", + "attributes": { + "name": "Infrastructure Project", + "description": null, + "workspace-count": 4, + "team-count": 2, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v" + } + } +} +``` + +## List projects + +This endpoint lists projects in the organization. + +`GET /organizations/:organization_name/projects` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------- | +| `:organization_name` | The name of the organization to list the projects of. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 projects per page. | +| `q` | **Optional.** A search query string. This query searches projects by name. This search is case-insensitive. If both `q` and `filter[names]` are specified, `filter[names]` will be used. | +| `filter[names]` | **Optional.** If specified, returns the project with the matching name. This filter is case-insensitive. If multiple comma separated values are specified, projects matching any of the names are returned. | +| `filter[permissions][create-workspace]` | **Optional.** If present, returns a list of projects that the authenticated user can create workspaces in. | +| `filter[permissions][update]` | **Optional.** If present, returns a list of projects that the authenticated user can update. | +| `sort` | **Optional.** Allows sorting the organization's projects by `"name"`. Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/projects +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "prj-W6k9K23oSXRHGpj3", + "type": "projects", + "attributes": { + "name": "Default Project", + "description": null, + "workspace-count": 2, + "team-count": 1, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-W6k9K23oSXRHGpj3/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-W6k9K23oSXRHGpj3" + } + }, + { + "id": "prj-YoriCxAawTMDLswn", + "type": "projects", + "attributes": { + "name": "Infrastructure Project", + "description": null, + "workspace-count": 4, + "team-count": 2, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-YoriCxAawTMDLswn/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-YoriCxAawTMDLswn" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/projects?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "status-counts": { + "total": 2, + "matching": 2 + }, + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show project + +`GET /projects/:project_id` + +| Parameter | Description | +| ------------- | -------------- | +| `:project_id` | The project ID | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v +``` + +### Sample Response + +```json +{ + "data": { + "id": "prj-WsVcWRr7SfxRci1v", + "type": "projects", + "attributes": { + "name": "Infrastructure Project", + "description": null, + "workspace-count": 4, + "team-count": 2, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-create-workspace": true + }, + "auto-destroy-activity-duration": "2d" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings" + } + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/projects/prj-WsVcWRr7SfxRci1v/effective-tag-bindings" + } + } + }, + "links": { + "self": "/api/v2/projects/prj-WsVcWRr7SfxRci1v" + } + } +} +``` + +## Delete a project + +A project cannot be deleted if it contains stacks or workspaces. + +`DELETE /projects/:project_id` + +| Parameter | Description | +| ------------- | ------------------------------- | +| `:project_id` | The ID of the project to delete | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the project | +| [403][] | [JSON API error object][] | Not authorized to perform a force delete on the project | +| [404][] | [JSON API error object][] | Project not found, or user unauthorized to perform project delete | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v +``` + +## List project tag bindings + +Call the following endpoints to list the tags bound to a project. + +- `GET /projects/:project_id/tag-bindings`: Lists the set of tags associated with the project. Tags set on the project are inherited by its workspaces. + +| Parameter | Description | +| ------------- | ---------------------- | +| `:project_id` | The ID of the project. | + +### Sample request + +The following request returns all tags bound to a project with the ID +`prj-WsVcWRr7SfxRci1v`. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/projects/prj-WsVcWRr7SfxRci1v/tag-bindings +``` + +### Sample response + +```json +{ + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "added", + "value": "new", + "created-at": "2024-11-20T00:04:47.948Z" + } + }, + { + "type": "tag-bindings", + "attributes": { + "key": "aww", + "value": "aww", + "created-at": "2024-11-20T00:04:47.948Z" + } + } + ] +} +``` + +## Add or update tag bindings on a project + +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 the following constraints and behaviors: + +- 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` + +| Parameter | Description | +| ------------- | ------------------------------- | +| `:project_id` | The ID of the project to update | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that for each data item, `type`, as well as `attributes.key` is required. + +| Key path | Type | Default | Description | +| ------------------------- | ------ | ------- | ------------------------------------- | +| `data[].type` | string | | Must be `"tag-bindings"`. | +| `data[].attributes.key` | string | | The key of the tag to add or update. | +| `data[].attributes.value` | string | | The name of the tag to add or update. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + +### 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/projects/prj-82d2281aa259ba09/tag-bindings +``` + +### Sample Response + +Example status code 200 response after updating tag bindings: + + + +```json +{ + "data": [ + { + "id": "tb-e4a5847b2cf06559", + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "id": "tb-97ce954636f93a6c", + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + + + +## Move workspaces into a project + +This endpoint allows you to move one or more workspaces into a project. You must have permission to move workspaces on +the destination project as well as any source project(s). If you are not authorized to move any of the workspaces in the +request, or if any workspaces in the request are not found, then no workspaces will be moved. + +`POST /projects/:project_id/relationships/workspaces` + +| Parameter | Description | +| ------------- | --------------------------------- | +| `:project_id` | The ID of the destination project | + +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 `"workspaces"` | +| `data[].id` | string | | The ids of workspaces to move into the destination project | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | +| [204][] | No Content | Successfully moved workspace(s) | +| [403][] | [JSON API error object][] | Workspace(s) not found, or user is not authorized to move all workspaces out of their current project(s) | +| [404][] | [JSON API error object][] | Project not found, or user unauthorized to move workspaces into project | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-AQEct2XFuH4HBsmS" + } + ] +} + +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/projects/prj-zXm4y2BjeGPgHtkp/relationships/workspaces +``` + +### Sample Error Response + +```json +{ + "errors": [ + { + "status": "403", + "title": "forbidden", + "detail": "Workspace(s) not found, or you are not authorized to move them: ws-AQEct2XFuH4HBmS" + } + ] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/reserved-tag-keys.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/reserved-tag-keys.mdx new file mode 100644 index 0000000000..51655fd031 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/reserved-tag-keys.mdx @@ -0,0 +1,271 @@ +--- +page_title: /reserved-tag-keys API reference for Terraform Enterprise +description: >- + Use the `/reserved-tag-keys` API endpoints to reserve tag keys that have + special meaning for your organization. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Reserved tag keys API reference + +Use the `/reserved-tag-keys` API endpoints to define and manage tag keys that +have special meaning for your organization. Reserving tag keys enable project +and workspace managers to follow a consistent tagging strategy across the +organization. You can also use them to provide project managers with a means of +disabling overrides for inherited tags. + +The following table describes the available endpoints: + +| Method | Path | Description | +| -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------- | +| `GET` | `/organizations/:organization_name/reserved-tag-keys` | [List reserved tag keys](#list-reserved-tag-keys) for the specified organization. | +| `POST` | `/organizations/:organization_name/reserved-tag-keys` | [Add a reserved tag key](#add-a-reserved-tag-key) to the specified organization. | +| `PATCH` | `/reserved-tags/:reserved_tag_key_id` | [Update a reserved tag key](#add-a-reserved-tag-value) with the specified ID. | +| `DELETE` | `/reserved-tags/:reserved_tag_key_id` | [Delete a reserved tag key](#delete-a-reserved-tag-key) with the specified ID. | + +## Path parameters + +The `/reserved-tag-keys/` API endpoints require the following path parameters: + +| Parameter | Description | +| ---------------------- | ---------------------------------------------------------- | +| `:reserved_tag_key_id` | The external ID of the reserved tag key. | +| `:organization_name` | The name of the organization containing the reserved tags. | + +## List reserved tag keys + +`GET /organizations/:organization_name/reserved-tag-keys` + +### Sample payload + +This endpoint does not require a payload. + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys +``` + +### Sample response + +```json +{ + "data": [ + { + "id": "rtk-jjnTseo8NN1jACbk", + "type": "reserved-tag-keys", + "attributes": { + "key": "environment", + "disable-overrides": false, + "created-at": "2024-08-13T23:06:42.523Z", + "updated-at": "2024-08-13T23:06:42.523Z" + } + }, + { + "id": "rtk-F1s7kKUShAQxhA1b", + "type": "reserved-tag-keys", + "attributes": { + "key": "cost-center", + "disable-overrides": false, + "created-at": "2024-08-13T23:06:51.445Z", + "updated-at": "2024-08-13T23:06:51.445Z" + } + }, + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} + +``` + +## Create a reserved tag key + +`POST /organizations/:organization_name/reserved-tag-keys` + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------ | ------- | ------- | --------------------------------- | +| `data.type` | string | none | Must be `reserved-tag-keys`. | +| `data.attributes.key` | string | none | The key targeted by this reserved | +| tag key. | | | | +| `data.attributes.disable-overrides` | boolean | none | If `true`, disables | +| overriding inherited tags with the specified key at the workspace level. | | | | + +### Sample payload + +```json +{ + "data": { + "type": "reserved-tag-keys", + "attributes": { + "key": "environment", + "disable-overrides": false + } + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/organizations/${ORGANIZATION_NAME}/reserved-tag-keys +``` + +### Sample response + +```json +{ + "data": { + "id": "rtk-Tj86UdGahKGDiYXY", + "type": "reserved-tag-keys", + "attributes": { + "key": "environment", + "disable-overrides": false, + "created-at": "2024-09-04T05:02:06.794Z", + "updated-at": "2024-09-04T05:02:06.794Z" + } + } +} +``` + +## Update a reserved tag key + +`PATCH /reserved-tags/:reserved_tag_key_id` + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------------------------ | ------- | ------- | --------------------------------- | +| `data.type` | string | none | Must be `reserved-tag-keys`. | +| `data.attributes.key` | string | none | The key targeted by this reserved | +| tag key. | | | | +| `data.attributes.disable-overrides` | boolean | none | If `true`, disables | +| overriding inherited tags with the specified key at the workspace level. | | | | + +### Sample payload + +```json +{ + "data": { + "id": "rtk-Tj86UdGahKGDiYXY", + "type": "reserved-tag-keys", + "attributes": { + "key": "env", + "disable-overrides": true, + "created-at": "2024-09-04T05:02:06.794Z", + "updated-at": "2024-09-04T05:02:06.794Z" + } + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + https://app.terraform.io/api/v2/reserved-tags/${RESERVED_TAG_ID} +``` + +### Sample response + +```json +{ + "data": { + "id": "rtk-zMtWLDftAjY3b5pA", + "type": "reserved-tag-keys", + "attributes": { + "key": "env", + "disable-overrides": true, + "created-at": "2024-09-04T05:05:10.449Z", + "updated-at": "2024-09-04T05:05:13.486Z" + } + } +} +``` + +## Delete a reserved tag key + +`DELETE /reserved-tags/:reserved_tag_key_id` + +### Sample payload + +This endpoint does not require a payload. + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/reserved-tags/rtk-zMtWLDftAjY3b5pA +``` + +### Sample response + +This endpoint does not return a response body. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-task-stages-and-results.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-task-stages-and-results.mdx new file mode 100644 index 0000000000..40c8a1f250 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-task-stages-and-results.mdx @@ -0,0 +1,366 @@ +--- +page_title: /task-stages API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/task-stages` endpoint to read run tasks + and their results, and override run task stages. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API documents]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[run]: /terraform/enterprise/run/states + +# Run task stages and results API reference + +HCP Terraform uses run task stages and run task results to track [run task](/terraform/enterprise/workspaces/settings/run-tasks) execution. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +When HCP Terraform creates a [run][], it reads the run tasks associated to the workspace. Each run task in the workspace is configured to begin during a specific [run stage](/terraform/enterprise/run/states). HCP Terraform creates a run task stage object for each run stage that triggers run tasks. You can configure run tasks during the [Pre-Plan Stage](/terraform/enterprise/run/states#the-pre-plan-stage), [Post-Plan Stage](/terraform/enterprise/run/states#the-post-plan-stage), [Pre-Apply Stage](/terraform/enterprise/run/states#the-pre-apply-stage) and [Post-Apply Stage](/terraform/enterprise/run/states#the-post-apply-stage). + +Run task stages then create a run task result for each run task. For example, a workspace has two run tasks called `alpha` and `beta`. For each run, HCP Terraform creates one run task stage called `post-plan`. That run task stage has two run task results: one for the `alpha` run task and one for the `beta` run task. + +This page lists the endpoints to retrieve run task stages and run task results. Refer to the [Run Tasks API](/terraform/enterprise/api-docs/run-tasks/run-tasks) for endpoints to create and manage run tasks within HCP Terraform. Refer to the [Run Tasks Integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) for endpoints to build custom run tasks for the HCP Terraform ecosystem. + +## Attributes + +### Run Task Stage Status + +The run task stage status is found in `data.attributes.status`, and you can reference the following list of possible values. + +| Status | Description | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `pending` | The initial status of a run task stage after creation. | +| `running` | The run task stage is executing one or more tasks, which have not yet completed. | +| `passed` | All of the run task results in the stage passed. | +| `failed` | One more results in the run task stage failed. | +| `awaiting_override` | The task stage is waiting for user input. Once a user manually overrides the failed run tasks, the run returns to the `running` state. | +| `errored` | The run task stage has errored. | +| `canceled` | The run task stage has been canceled. | +| `unreachable` | The run task stage could not be executed. | + +### Run Task Result Status + +The run task result status is found in `data.attributes.status`, and you can reference the following list of possible values. + +| Status | Description | +| ------------- | --------------------------------------------------------------------- | +| `pending` | The initial status of a run task result after creation. | +| `running` | The associated run task is begun execution and has not yet completed. | +| `passed` | The associated run task executed and returned a passing result. | +| `failed` | The associated run task executed and returned a failed result. | +| `errored` | The associated run task has errored during execution. | +| `canceled` | The associated run task execution has been canceled. | +| `unreachable` | The associated run task could not be executed. | + +## List the Run Task Stages in a Run + +`GET /runs/:run_id/task-stages` + +| Parameter | Description | +| --------- | ----------------------------------- | +| `run_id` | The run ID to list task stages for. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------- | +| [200][] | Array of [JSON API documents][] (`type: "task-stages"`) | Successfully listed task-stages | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 runs per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/runs/run-XdgtChJuuUwLoSmw/task-stages +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ts-rL5ZsuwfjqfPJcdi", + "type": "task-stages", + "attributes": { + "status": "passed", + "stage": "post_plan", + "status-timestamps": { + "passed-at": "2022-06-08T20:32:12+08:00", + "running-at": "2022-06-08T20:32:11+08:00" + }, + "created-at": "2022-06-08T12:31:56.94Z", + "updated-at": "2022-06-08T12:32:12.315Z" + }, + "relationships": { + "run": { + "data": { + "id": "run-XdgtChJuuUwLoSmw", + "type": "runs" + } + }, + "task-results": { + "data": [ + { + "id": "taskrs-EmnmsEDL1jgd1GTP", + "type": "task-results" + } + ] + }, + "policy-evaluations":{ + "data":[ + { + "id":"poleval-iouaha9KLgGWkBRQ", + "type":"policy-evaluations" + } + ] + } + }, + "links": { + "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi" + } + } + ] +} +``` + +## Show a Run Task Stage + +`GET /task-stages/:task_stage_id` + +| Parameter | Description | +| ---------------- | ----------------------------- | +| `:task_stage_id` | The run task stage ID to get. | + +This endpoint shows details of a specific task stage. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ------------------------------------------- | +| [200][] | [JSON API document][] (`type: "task-stages"`) | Success | +| [404][] | [JSON API error object][] | Task stage not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi +``` + +### Sample Response + +```json +{ + "data": { + "id": "ts-rL5ZsuwfjqfPJcdi", + "type": "task-stages", + "attributes": { + "status": "passed", + "stage": "post_plan", + "status-timestamps": { + "passed-at": "2022-06-08T20:32:12+08:00", + "running-at": "2022-06-08T20:32:11+08:00" + }, + "created-at": "2022-06-08T12:31:56.94Z", + "updated-at": "2022-06-08T12:32:12.315Z" + }, + "relationships": { + "run": { + "data": { + "id": "run-XdgtChJuuUwLoSmw", + "type": "runs" + } + }, + "task-results": { + "data": [ + { + "id": "taskrs-EmnmsEDL1jgd1GTP", + "type": "task-results" + } + ] + }, + "policy-evaluations":{ + "data":[ + { + "id":"poleval-iouaha9KLgGWkBRQ", + "type":"policy-evaluations" + } + ] + } + }, + "links": { + "self": "/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi" + } + } +} +``` + +## Show a Run Task Result + +`GET /task-results/:task_result_id` + +| Parameter | Description | +| ----------------- | ------------------------------ | +| `:task_result_id` | The run task result ID to get. | + +This endpoint shows the details for a specific run task result. + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------- | +| [200][] | [JSON API document][] (`type: "task-results"`) | Success | +| [404][] | [JSON API error object][] | Task result not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/task-results/taskrs-EmnmsEDL1jgd1GZz +``` + +### Sample Response + +```json +{ + "data": { + "id": "taskrs-EmnmsEDL1jgd1GZz", + "type": "task-results", + "attributes": { + "message": "No issues found.\nSeverity threshold is set to low.", + "status": "passed", + "status-timestamps": { + "passed-at": "2022-06-08T20:32:12+08:00", + "running-at": "2022-06-08T20:32:11+08:00" + }, + "url": "https://external.service/project/task-123abc", + "created-at": "2022-06-08T12:31:56.954Z", + "updated-at": "2022-06-08T12:32:12.27Z", + "task-id": "task-b6MaHZmGopHDtqhn", + "task-name": "example-task", + "task-url": "https://external.service/task-123abc", + "stage": "post_plan", + "is-speculative": false, + "workspace-task-id": "wstask-258juqenQeWb3DZz", + "workspace-task-enforcement-level": "mandatory" + }, + "relationships": { + "task-stage": { + "data": { + "id": "ts-rL5ZsuwfjqfPJczZ", + "type": "task-stages" + } + } + }, + "links": { + "self": "/api/v2/task-results/taskrs-EmnmsEDL1jgd1GZz" + } + } +} +``` + +## Available Related Resources + +### Task Stage + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource | Description | +| -------------------- | ---------------------------------------------------------- | +| `run` | Information about the associated run. | +| `run.workspace` | Information about the associated workspace. | +| `task-results` | Information about the results for a task-stage. | +| `policy-evaluations` | Information about the policy evaluations for a task-stage. | + +## Override a Task Stage + +`POST /task-stages/:task_stage_id/actions/override` + +| Parameter | Description | +| ---------------- | ------------------------------------- | +| `:task_stage_id` | The ID of the task stage to override. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/task-stages/ts-rL5ZsuwfjqfPJcdi/actions/override +``` + +### Sample Response + +```json +{ + "data":{ + "id":"ts-F7MumZQcJzVh1ZZk", + "type":"task-stages", + "attributes":{ + "status":"running", + "stage":"post_plan", + "status-timestamps":{ + "running-at":"2022-09-21T06:36:54+00:00", + "awaiting-override-at":"2022-09-21T06:31:50+00:00" + }, + "created-at":"2022-09-21T06:29:44.632Z", + "updated-at":"2022-09-21T06:36:54.952Z", + "permissions":{ + "can-override-policy":true, + "can-override-tasks":false, + "can-override":true + }, + "actions":{ + "is-overridable":false + } + }, + "relationships":{ + "run":{ + "data":{ + "id":"run-K6N4BAz8NfUyR2QB", + "type":"runs" + } + }, + "task-results":{ + "data":[ + + ] + }, + "policy-evaluations":{ + "data":[ + { + "id":"poleval-atNKxwvjYy4Gwk3k", + "type":"policy-evaluations" + } + ] + } + }, + "links":{ + "self":"/api/v2/task-stages/ts-F7MumZQcJzVh1ZZk" + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx new file mode 100644 index 0000000000..eaa3fe1fca --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-tasks-integration.mdx @@ -0,0 +1,298 @@ +--- +page_title: Run tasks integration API for Terraform Enterprise +description: >- + Use Terraform Enterprise API's run task integration API to trigger run tasks + at specific run phases and learn how to read run task responses. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Run tasks integration API + +[Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. +This page lists the API endpoints used to trigger a run task and the expected response from the integration. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +Refer to [run tasks](/terraform/enterprise/api-docs/run-tasks/run-tasks) for the API endpoints to create and manage run tasks within HCP Terraform. You can also access a complete list of all run tasks in the [Terraform Registry](https://registry.terraform.io/browse/run-tasks). + +## 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` + +| Parameter | Description | +| --------- | ------------------------------------------------------- | +| `:url` | The URL configured in the run task to send requests to. | + +| Status | Response | Reason | +| ------- | ---------- | --------------------------------- | +| [200][] | No Content | Successfully submitted a run task | + +### Request Body + +The POST request submits a JSON object with the following properties as a request payload. + +#### Common Properties + +All request payloads contain the following properties. + +| Key path | Type | Values | Description | +| ------------------------------------ | ------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `payload_version` | integer | `1` | Schema version of the payload. Only `1` is supported. | +| `stage` | string | `pre_plan`, `post_plan`, `pre_apply`, `post_apply` | The [run stage](/terraform/enterprise/run/states) when HCP Terraform triggers the run task. | +| `access_token` | string | | Bearer token to use when calling back to HCP Terraform. | +| `capabilities` | object | | A map of the capabilities that the caller supports. | +| `capabilities.outcomes` | bool | | A flag indicating the caller accepts detailed run task outcomes. | +| `configuration_version_download_url` | string | | The URL to [download the configuration version](/terraform/enterprise/api-docs/configuration-versions#download-configuration-files). This is `null` if the configuration version is not available to download. | +| `configuration_version_id` | string | | The ID of the [configuration version](/terraform/enterprise/api-docs/configuration-versions) for the run. | +| `is_speculative` | bool | | Whether the task is part of a [speculative run](/terraform/enterprise/run/remote-operations#speculative-plans). | +| `organization_name` | string | | Name of the organization the task is configured within. | +| `run_app_url` | string | | URL within HCP Terraform to the run. | +| `run_created_at` | string | | When the run was started. | +| `run_created_by` | string | | Who created the run. | +| `run_id` | string | | Id of the run this task is part of. | +| `run_message` | string | | Message that was associated with the run. | +| `task_result_callback_url` | string | | URL that should called back with the result of this task. | +| `task_result_enforcement_level` | string | `mandatory`, `advisory` | Enforcement level for this task. | +| `task_result_id` | string | | ID of task result within HCP Terraform. | +| `vcs_branch` | string | | Repository branch that the workspace executes from. This is `null` if the workspace does not have a VCS repository. | +| `vcs_commit_url` | string | | URL to the commit that triggered this run. This is `null` if the workspace does not a VCS repository. | +| `vcs_pull_request_url` | string | | URL to the Pull Request/Merge Request that triggered this run. This is `null` if the run was not triggered. | +| `vcs_repo_url` | string | | URL to the workspace's VCS repository. This is `null` if the workspace does not have a VCS repository. | +| `workspace_app_url` | string | | URL within HCP Terraform to the workspace. | +| `workspace_id` | string | | Id of the workspace the task is associated with. | +| `workspace_name` | string | | Name of the workspace. | +| `workspace_working_directory` | string | | The working directory specified in the run's [workspace settings](/terraform/enterprise/workspaces/settings#terraform-working-directory). | + +#### Post-Plan, Pre-Apply, and Post-Apply Properties + +Requests with `stage` set to `post_plan`, `pre_apply` or `post_apply` contain the following additional properties. + +| Key path | Type | Values | Description | +| ------------------- | ------ | ------ | --------------------------------------------------------- | +| `plan_json_api_url` | string | | The URL to retrieve the JSON Terraform plan for this run. | + +### Sample Payload + +```json +{ + "payload_version": 1, + "stage": "post_plan", + "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q", + "capabilities": { + "outcomes": true + }, + "configuration_version_download_url": "https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download", + "configuration_version_id": "cv-ntv3HbhJqvFzamy7", + "is_speculative": false, + "organization_name": "hashicorp", + "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output", + "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ", + "run_created_at": "2021-09-02T14:47:13.036Z", + "run_created_by": "username", + "run_id": "run-i3Df5to9ELvibKpQ", + "run_message": "Triggered via UI", + "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback", + "task_result_enforcement_level": "mandatory", + "task_result_id": "taskrs-2nH5dncYoXaMVQmJ", + "vcs_branch": "main", + "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22", + "vcs_pull_request_url": null, + "vcs_repo_url": "https://github.com/hashicorp/terraform-random", + "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace", + "workspace_id": "ws-ck4G5bb1Yei5szRh", + "workspace_name": "tfr_github_0", + "workspace_working_directory": "/terraform" +} +``` + +### Request Headers + +The POST request submits the following properties as the request headers. + +| Name | Value | Description | +| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Content-Type` | `application/json` | Specifies the type of data in the request body | +| `User-Agent` | `TFC/1.0 (+https://app.terraform.io; TFC)` | Identifies the request is coming from HCP Terraform | +| `X-TFC-Task-Signature` | string | If the run task is configured with an [HMAC Key](/terraform/enterprise/integrations/run-tasks#securing-your-run-task), this header contains the signed SHA512 sum of the request payload using the configured HMAC key. Otherwise, this is an empty string. | + +## Run Task Callback + +While a run task runs, it may send progressive updates to HCP Terraform with a `running` status. Once an integrator determines that Terraform supports detailed run task outcomes, they can send these outcomes by appending to the run task's callback payload. + +Once the external integration fulfills the request, that integration must call back into HCP Terraform with the overall result of either `passed` or `failed`. Terraform expects this callback within 10 minutes, or the request is considered errored. + +You can send outcomes with a status of `running`, `passed`, or `failed`, but it is a good practice only to send outcomes when a run task is `running`. + +`PATCH :callback_url` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------- | +| `:callback_url` | The `task_result_callback_url` specified in the run task request. Typically `/task-results/:guid/callback`. | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------------------- | +| [200][] | No Content | Successfully submitted a run task result | +| [401][] | [JSON API error object][] | Not authorized to perform action | +| [422][] | [JSON API error object][] | Invalid response payload. This could be caused by invalid attributes, or sending a status that is not accepted. | + +### Request Body + +The PATCH request submits a JSON object with the following properties as a request payload. This payload is also described in the [JSON API schema for run task results](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json). + +| Key path | Type | Description | +| ----------------------------- | ------ | --------------------------------------------------------------------------------- | +| `data.type` | string | Must be `"task-results"`. | +| `data.attributes.status` | string | The current status of the task. Only `passed`, `failed` or `running` are allowed. | +| `data.attributes.message` | string | (Recommended, but optional) A short message describing the status of the task. | +| `data.attributes.url` | string | (Optional) A URL where users can obtain more information about the task. | +| `relationships.outcomes.data` | array | (Recommended, but optional) A collection of detailed run task outcomes. | + +Status values other than passed, failed, or running return an error. Both the passed and failed statuses represent a final state for a run task. The running status allows one or more partial updates until the task has reached a final state. + +```json +{ + "data": { + "type": "task-results", + "attributes": { + "status": "passed", + "message": "4 passed, 0 skipped, 0 failed", + "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ" + }, + "relationships": { + "outcomes": { + "data": [...] + } + } + } +} +``` + +#### Outcomes Payload Body + +A run task result may optionally contain one or more detailed outcomes, which improves result visibility and content in the HCP Terraform user interface. The following attributes define the outcome. + +| Key path | Type | Description | +| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `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. 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. | +| `tags.key[].label` | string | The text value of the tag. | +| `tags.key[].level` | enum string | (Optional) The error level for the tag. Defaults to `none`, but accepts `none`, `info`, `warning`, or `error`. For levels other than `none`, labels render with a color and icon for that level. | + +##### Severity and Status Tags + +Run task outcomes with tags named "severity" or "status" are enriched within the outcomes display list in HCP Terraform, enabling an earlier response to issues with severity and status. + +```json +{ + "type": "task-result-outcomes", + "attributes": { + "outcome-id": "PRTNR-CC-TF-127", + "description": "ST-2942: S3 Bucket will not enforce MFA login on delete requests", + "tags": { + "Status": [ + { + "label": "Denied", + "level": "error" + } + ], + "Severity": [ + { + "label": "High", + "level": "error" + }, + { + "label": "Recoverable", + "level": "info" + } + ], + "Cost Centre": [ + { + "label": "IT-OPS" + } + ] + }, + "body": "# Resolution for issue ST-2942\n\n## Impact\n\nFollow instructions in the [AWS S3 docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) to manually configure the MFA setting.\n—-- Payload truncated —--", + "url": "https://external.service.dev/result/PRTNR-CC-TF-127" + } +} +``` + +##### Complete Callback Payload Example + +The example below shows a complete payload explaining the data structure of a callback payload, including all the necessary fields. + +```json +{ + "data": { + "type": "task-results", + "attributes": { + "status": "failed", + "message": "0 passed, 0 skipped, 1 failed", + "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ" + }, + "relationships": { + "outcomes": { + "data": [ + { + "type": "task-result-outcomes", + "attributes": { + "outcome-id": "PRTNR-CC-TF-127", + "description": "ST-2942: S3 Bucket will not enforce MFA login on delete requests", + "tags": { + "Status": [ + { + "label": "Denied", + "level": "error" + } + ], + "Severity": [ + { + "label": "High", + "level": "error" + }, + { + "label": "Recoverable", + "level": "info" + } + ], + "Cost Centre": [ + { + "label": "IT-OPS" + } + ] + }, + "body": "# Resolution for issue ST-2942\n\n## Impact\n\nFollow instructions in the [AWS S3 docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/MultiFactorAuthenticationDelete.html) to manually configure the MFA setting.\n—-- Payload truncated —--", + "url": "https://external.service.dev/result/PRTNR-CC-TF-127" + } + } + ] + } + } + } +} +``` + +### Request Headers + +The PATCH request must use the token supplied in the originating request (`access_token`) for [authentication](/terraform/enterprise/api-docs#authentication). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx new file mode 100644 index 0000000000..c0b0a8fcc7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-tasks/run-tasks.mdx @@ -0,0 +1,831 @@ +--- +page_title: /tasks API reference for Terraform Enterprise +description: >- + Use Terraform Enterprise API's `/tasks` endpoint to read, create, update, and + delete run tasks, and read, update, delete and associate run tasks to + workspaces. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[JSON API Schema document]: https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-results.json + +# Run tasks API reference + +[Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. Run tasks are reusable configurations that you can associate to any workspace in an organization. This page lists the API endpoints for run tasks in an organization and explains how to associate run tasks to workspaces. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +Refer to [run tasks Integration](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) for the API endpoints related triggering run tasks and the expected integration response. + +## Required Permissions + +To interact with run tasks on an organization, you need the [Manage Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#manage-run-tasks). To associate or dissociate run tasks in a workspace, you need the [Manage Workspace Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) on that particular workspace. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a Run Task + +`POST /organizations/:organization_name/tasks` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The organization to create a run task in. The organization must already exist in HCP Terraform, and the token authenticating the API request must have [owner permission](/terraform/enterprise/users-teams-organizations/permissions). | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "tasks"`) | Successfully created a run task | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +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"`. | +| `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 + +```json +{ + "data": { + "type": "tasks", + "attributes": { + "name": "example", + "url": "http://example.com", + "description": "Simple description", + "hmac_key": "secret", + "enabled": "true", + "category": "task", + "global-configuration": { + "enabled": true, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + }, + "relationships": { + "agent-pool": { + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools" + } + } + } + } +} +``` + +### 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/organizations/my-organization/tasks +``` + +### Sample Response + +```json +{ + "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" + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [] + }, + "agent-pool": { + "data": { + "id": "apool-yoGUFz5zcRMMz53i", + "type": "agent-pools" + } + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } +} +``` + +## List Run Tasks + +`GET /organizations/:organization_name/tasks` + +| Parameter | Description | +| -------------------- | ----------------------------------- | +| `:organization_name` | The organization to list tasks for. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | Request was successful | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `include` | **Optional.** Allows including related resource data. Value must be a comma-separated list containing one or more of `workspace_tasks` or `workspace_tasks.workspace`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 run tasks per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/tasks +``` + +### Sample Response + +```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" + } + } + ], + "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 + } + } +} +``` + +## Show a Run Task + +`GET /tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------- | +| `:id` | The ID of the task to show. Use the ["List Run Tasks"](#list-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | --------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Run task not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `include` | **Optional.** Allows including related resource data. Value must be a comma-separated list containing one or more of `workspace_tasks` or `workspace_tasks.workspace`. | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV +``` + +### Sample Response + +```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, + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [ + { + "id": "task-xjKZw9KaeXda61az", + "type": "tasks" + } + ] + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } +} +``` + +## Update a Run Task + +`PATCH /tasks/:id` + +| Parameter | Description | +| --------- | ----------------------------------------------------------------------------------------------- | +| `:id` | The ID of the task to update. Use the ["List Run Tasks"](#list-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Run task not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +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 | (previous value) | The name of the run task. Can include letters, numbers, `-`, and `_`. | +| `data.attributes.url` | string | (previous value) | 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 | (previous value) | Must be `"task"`. | +| `data.attributes.hmac-key` | string | (previous value) | (Optional) HMAC key to verify run task. | +| `data.attributes.enabled` | bool | (previous value) | (Optional) Whether the task will be run. | +| `data.attributes.global-configuration.enabled` | bool | (previous value) | (Optional) Whether the task will be associated on all workspaces. | +| `data.attributes.global-configuration.stages` | array | (previous value) | (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 | (previous value) | (Optional) The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "tasks", + "attributes": { + "name": "new-example", + "url": "http://new-example.com", + "description": "New description", + "hmac_key": "new-secret", + "enabled": "false", + "category": "task", + "global-configuration": { + "enabled": false + } + } + } +} +``` + +### 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/tasks/task-7oD7doVTQdAFnMLV +``` + +### Sample Response + +```json +{ + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks", + "attributes": { + "category": "task", + "name": "new-example", + "url": "http://new-example.com", + "description": "New description", + "enabled": "false", + "hmac-key": null, + "global-configuration": { + "enabled": false, + "stages": ["pre_plan"], + "enforcement-level": "mandatory" + } + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "tasks": { + "data": [ + { + "id": "wstask-xjKZw9KaeXda61az", + "type": "workspace-tasks" + } + ] + } + }, + "links": { + "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV" + } + } +} +``` + +## Delete a Run Task + +`DELETE /tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the run task to delete. Use the ["List Run Tasks"](#list-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the run task | +| [404][] | [JSON API error object][] | Run task not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV +``` + +## Associate a Run Task to a Workspace + +`POST /workspaces/:workspace_id/tasks` + +| Parameter | Description | +| --------------- | ------------------------ | +| `:workspace_id` | The ID of the workspace. | + +This endpoint associates an existing run task to a specific workspace. + +This involves setting the run task enforcement level, which determines whether the run task blocks runs from completing. + +- Advisory run tasks can not block a run from completing. If the task fails, the run will proceed with a warning. + +- Mandatory run tasks block a run from completing. If the task fails (including a timeout or unexpected remote error condition), the run stops with an error. + +You may also configure the run task to begin during specific [run stages](/terraform/enterprise/run/states). Run tasks use the [Post-Plan Stage](/terraform/enterprise/run/states#the-post-plan-stage) by default. + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------------------------------------- | +| [204][] | No Content | The request was successful | +| [404][] | [JSON API error object][] | Workspace or run task not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"workspace-tasks"`. | +| `data.attributes.enforcement-level` | string | | The enforcement level of the workspace task. Must be `"advisory"` or `"mandatory"`. | +| `data.attributes.stage` | string | `"post_plan"` | **DEPRECATED** Use `stages` instead. The stage in the run lifecycle when the run task should begin. Must be `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`. | +| `data.attributes.stages` | array | `["post_plan"]` | 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.relationships.task.data.id` | string | | The ID of the run task. | +| `data.relationships.task.data.type` | string | | Must be `"tasks"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-PphL7ix3yGasYGrq/tasks +``` + +### Sample Response + +```json +{ + "data": { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-7oD7doVTQdAFnMLV", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-PphL7ix3yGasYGrq", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-PphL7ix3yGasYGrq/tasks/task-tBXYu8GVAFBpcmPm" + } + } +} +``` + +## List Workspace Run Tasks + +`GET /workspaces/:workspace_id/tasks` + +| Parameter | Description | +| --------------- | -------------------------------- | +| `:workspace_id` | The workspace to list tasks for. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | Request was successful | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 run tasks per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-hu74ST39g566Q4m5", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-kRsDRPtTmtcEme4t", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/task-tBXYu8GVAFBpcmPm" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/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 + } + } +} +``` + +## Show Workspace Run Task + +`GET /workspaces/:workspace_id/tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the workspace task to show. Use the ["List Workspace Run Tasks"](#list-workspace-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace run task not found or user unauthorized to perform action | + +### Sample Request + +```shell +curl --request GET \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm +``` + +### Sample Response + +```json +{ + "data": { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "advisory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-hu74ST39g566Q4m5", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-kRsDRPtTmtcEme4t", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm" + } + } +} +``` + +## Update Workspace Run Task + +`PATCH /workspaces/:workspace_id/tasks/:id` + +| Parameter | Description | +| --------- | ------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the task to update. Use the ["List Workspace Run Tasks"](#list-workspace-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "tasks"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace run task not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------------- | ------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | (previous value) | Must be `"workspace-tasks"`. | +| `data.attributes.enforcement-level` | string | (previous value) | The enforcement level of the workspace run task. Must be `"advisory"` or `"mandatory"`. | +| `data.attributes.stage` | string | (previous value) | **DEPRECATED** Use `stages` instead. The stage in the run lifecycle when the run task should begin. Must be `"pre_plan"` or `"post_plan"`. | +| `data.attributes.stages` | array | (previous value) | 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"`. | + +### Sample Payload + +```json +{ + "data": { + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "mandatory", + "stages": ["post_plan"] + } + } +} +``` + +#### Deprecated Payload + +```json +{ + "data": { + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "mandatory", + "stages": ["post_plan"] + } + } +} +``` + +### 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/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm +``` + +### Sample Response + +```json +{ + "data": { + "id": "wstask-tBXYu8GVAFBpcmPm", + "type": "workspace-tasks", + "attributes": { + "enforcement-level": "mandatory", + "stage": "post_plan", + "stages": ["post_plan"] + }, + "relationships": { + "task": { + "data": { + "id": "task-hu74ST39g566Q4m5", + "type": "tasks" + } + }, + "workspace": { + "data": { + "id": "ws-kRsDRPtTmtcEme4t", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/task-tBXYu8GVAFBpcmPm" + } + } +} +``` + +## Delete Workspace Run Task + +`DELETE /workspaces/:workspace_id/tasks/:id` + +| Parameter | Description | +| --------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the Workspace run task to delete. Use the ["List Workspace Run Tasks"](#list-workspace-run-tasks) endpoint to find IDs. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the workspace run task | +| [404][] | [JSON API error object][] | Workspace run task not found, or user unauthorized to perform action | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-triggers.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-triggers.mdx new file mode 100644 index 0000000000..e557a25a36 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run-triggers.mdx @@ -0,0 +1,349 @@ +--- +page_title: /run-triggers API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/run-triggers` endpoint to read, create, + and delete run triggers. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Run triggers API reference + +## Create a Run Trigger + +`POST /workspaces/:workspace_id/run-triggers` + +| Parameter | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to create the run trigger in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------------------ | +| [201][] | [JSON API document][] (`type: "run-triggers"`) | Successfully created a run trigger | +| [404][] | [JSON API error object][] | Workspace or sourceable not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Permissions + +In order to create a run trigger, the user must have admin access to the specified workspace and permission to read runs for the sourceable workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.relationships.sourceable.data` | object | | A JSON API relationship object that represents the source workspace for the run trigger. This object must have `id` and `type` properties, and the `type` property must be `workspaces` (e.g. `{ "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }`). Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +### Sample Payload + +```json +{ + "data": { + "relationships": { + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + } + } +} +``` + +### Sample Request + +```shell +curl \ + --request POST \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/run-triggers +``` + +### Sample Response + +```json +{ + "data": { + "id": "rt-3yVQZvHzf5j3WRJ1", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-2", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## List Run Triggers + +`GET /workspaces/:workspace_id/run-triggers` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list run triggers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "run-triggers"`) | Request was successful | +| [400][] | [JSON API error object][] | Required parameter `filter[run-trigger][type]` is missing or has been given an invalid value | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[run-trigger][type]` | **Required** Which type of run triggers to list; valid values are `inbound` or `outbound`. `inbound` run triggers create runs in the specified workspace, and `outbound` run triggers create runs in other workspaces. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 run triggers per page. | + +### Permissions + +In order to list run triggers, the user must have permission to read runs for the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "rt-WygcwSBuYaQWrM39", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-2", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-WygcwSBuYaQWrM39" + } + }, + { + "id": "rt-8F5JFydVYAmtTjET", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-3", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-BUHBEM97xboT8TVz", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-8F5JFydVYAmtTjET" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show a Run Trigger + +`GET /run-triggers/:run_trigger_id` + +| Parameter | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:run_trigger_id` | The ID of the run trigger to show. Send a `GET` request to the `run-triggers` endpoint to find IDs. Refer to [List Run Triggers](#list-run-triggers) for details. | + +| Status | Response | Reason | +| ------- | ---------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "run-triggers"`) | The request was successful | +| [404][] | [JSON API error object][] | Run trigger not found or user unauthorized to perform action | + +### Permissions + +In order to show a run trigger, the user must have permission to read runs for either the workspace or sourceable workspace of the specified run trigger. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1 +``` + +### Sample Response + +```json +{ + "data": { + "id": "rt-3yVQZvHzf5j3WRJ1", + "type": "run-triggers", + "attributes": { + "workspace-name": "workspace-1", + "sourceable-name": "workspace-2", + "created-at": "2018-09-11T18:21:21.784Z" + }, + "relationships": { + "workspace": { + "data": { + "id": "ws-XdeUVMWShTesDMME", + "type": "workspaces" + } + }, + "sourceable": { + "data": { + "id": "ws-2HRvNs49EWPjDqT1", + "type": "workspaces" + } + } + }, + "links": { + "self": "/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1" + } + } +} +``` + +## Delete a Run Trigger + +`DELETE /run-triggers/:run_trigger_id` + +| Parameter | Description | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:run_trigger_id` | The ID of the run trigger to delete. Send a `GET` request to the `run-triggers` endpoint o find IDs. Refer to [List Run Triggers](#list-run-triggers) for details. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | No Content | Successfully deleted the run trigger | +| [404][] | [JSON API error object][] | Run trigger not found or user unauthorized to perform action | + +### Permissions + +In order to delete a run trigger, the user must have admin access to the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request DELETE \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1 +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +These includes respect read permissions. If you do not have access to read the related resource, it will not be returned. + +- `workspace` - The full workspace object. +- `sourceable` - The full source workspace object. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run.mdx new file mode 100644 index 0000000000..950e1d8880 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/run.mdx @@ -0,0 +1,902 @@ +--- +page_title: /runs API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/runs` endpoint to read, get, create, + apply, discard, execute, and cancel Terraform runs. You can also list a + workspace's or organization's runs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Runs API reference + +-> **Note:** Before working with the runs or configuration versions APIs, read the [API-driven run workflow](/terraform/enterprise/run/api) page, which includes both a full overview of this workflow and a walkthrough of a simple implementation of it. + +Performing a run on a new configuration is a multi-step process. + +1. [Create a configuration version on the workspace](/terraform/enterprise/api-docs/configuration-versions#create-a-configuration-version). +2. [Upload configuration files to the configuration version](/terraform/enterprise/api-docs/configuration-versions#upload-configuration-files). +3. [Create a run on the workspace](#create-a-run); this is done automatically when a configuration file is uploaded. +4. [Create and queue an apply on the run](#apply-a-run); if the run can't be auto-applied. + +Alternatively, you can create a run with a pre-existing configuration version, even one from another workspace. This is useful for promoting known good code from one workspace to another. + +## Attributes + +### Run States + +The run state is found in `data.attributes.status`, and you can reference the following list of possible states. + +| State | Description | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pending` | The initial status of a run after creation. | +| `fetching` | The run is waiting for HCP Terraform to fetch the configuration from VCS. | +| `fetching_completed` | HCP Terraform has fetched the configuration from VCS and the run will continue. | +| `pre_plan_running` | The pre-plan phase of the run is in progress. | +| `pre_plan_completed` | The pre-plan phase of the run has completed. | +| `queuing` | HCP Terraform is queuing the run to start the planning phase. | +| `plan_queued` | HCP Terraform is waiting for its backend services to start the plan. | +| `planning` | The planning phase of a run is in progress. | +| `planned` | The planning phase of a run has completed. | +| `cost_estimating` | The cost estimation phase of a run is in progress. | +| `cost_estimated` | The cost estimation phase of a run has completed. | +| `policy_checking` | The sentinel policy checking phase of a run is in progress. | +| `policy_override` | A sentinel policy has soft failed, and a user can override it to continue the run. | +| `policy_soft_failed` | A sentinel policy has soft failed for a plan-only run. This is a final state. | +| `policy_checked` | The sentinel policy checking phase of a run has completed. | +| `confirmed` | A user has confirmed the plan. | +| `post_plan_running` | The post-plan phase of the run is in progress. | +| `post_plan_completed` | The post-plan phase of the run has completed. | +| `planned_and_finished` | The run is completed. This status only exists for plan-only runs and runs that produce a plan with no changes to apply. This is a final state. | +| `planned_and_saved` | The run has finished its planning, checks, and estimates, and can be confirmed for apply. This status is only used for saved plan runs. | +| `apply_queued` | Once the changes in the plan have been confirmed, the run will transition to `apply_queued`. This status indicates that the run should start as soon as the backend services that run terraform have available capacity. In HCP Terraform, you should seldom see this status, as our aim is to always have capacity. However, in Terraform Enterprise this status will be more common due to the self-hosted nature. | +| `applying` | Terraform is applying the changes specified in the plan. | +| `applied` | Terraform has applied the changes specified in the plan. | +| `discarded` | The run has been discarded. This is a final state. | +| `errored` | The run has errored. This is a final state. | +| `canceled` | The run has been canceled. | +| `force_canceled` | A workspace admin forcefully canceled the run. | + +### Run Operations + +The run operation specifies the Terraform execution mode. You can reference the following list of possible execution modes and use them as query parameters in the [workspace](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace) and [organization](/terraform/enterprise/api-docs/run#list-runs-in-a-organization) runs lists. + +| Operation | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plan_only` | The run does not have an apply phase. This is also called a [_speculative plan_](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan). | +| `plan_and_apply` | The run includes both plan and apply phases. | +| `save_plan` | The run is a saved plan run. It can include both plan and apply phases, but only becomes the workspace's current run if a user chooses to apply it. | +| `refresh_only` | The run should update Terraform state, but not make changes to resources. | +| `destroy` | The run should destroy all objects, regardless of configuration changes. | +| `empty_apply` | The run should perform an apply with no changes to resources. This is most commonly used to [upgrade terraform state versions](/terraform/enterprise/workspaces/state#upgrading-state). | + +### Run Sources + +You can use the following sources as query parameters in [workspace](/terraform/enterprise/api-docs/run#list-runs-in-a-workspace) and [organization](/terraform/enterprise/api-docs/run#list-runs-in-a-organization) runs lists. + +| Source | Description | +| --------------------------- | --------------------------------------------------------------------------------------- | +| `tfe-ui` | Indicates a run was queued from HCP Terraform UI. | +| `tfe-api` | Indicates a run was queued from HCP Terraform API. | +| `tfe-configuration-version` | Indicates a run was queued from a Configuration Version, triggered from a VCS provider. | + +### Run Status Groups + +The run status group specifies a collection of run states by logical category. + +| Group | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `non_final` | Inclusive of runs that are currently running, require user confirmation, or are queued/pending. | +| `final` | Inclusive of runs that have reached their final and terminal state. | +| `discardable` | Inclusive of runs whose state falls under the following: `planned`, `planned_and_saved`, `cost_estimated`, `policy_checked`, `policy_override`, `post_plan_running`, `post_plan_completed` | + +## Create a Run + +`POST /runs` + +A run performs a plan and apply, using a configuration version and the workspace’s current variables. You can specify a configuration version when creating a run; if you don’t provide one, the run defaults to the workspace’s most recently used version. (A configuration version is “used” when it is created or used for a run in this workspace.) + +Creating a run requires permission to queue plans for the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +When creating a run, you may optionally provide a list of variable objects containing key and value attributes. These values apply to that run specifically and take precedence over variables with the same key applied to the workspace(e.g., variable sets). Refer to [Variable Precedence](/terraform/enterprise/workspaces/variables#precedence) for more information. All values must be expressed as an HCL literal in the same syntax you would use when writing Terraform code. Refer to [Types](/terraform/language/expressions/types#types) in the Terraform documentation for more details. + +Setting `debugging_mode: true` enables debugging mode for the queued run only. This is equivalent to setting the `TF_LOG` environment variable to `TRACE` for this run. See [Debugging Terraform](/terraform/internals/debugging) for more information. + +**Sample Run Variables:** + +```json +"attributes": { + "variables": [ + { "key": "replicas", "value": "2" }, + { "key": "access_key", "value": "\"ABCDE12345\"" } + ] +} +``` + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.allow-empty-apply` | bool | none | Specifies whether Terraform can apply the run even when the plan [contains no changes](/terraform/enterprise/run/modes-and-options#allow-empty-apply). Use this property to [upgrade state](/terraform/enterprise/workspaces/state#upgrading-state) after upgrading a workspace to a new terraform version. | +| `data.attributes.allow-config-generation` | bool | `false` | Specifies whether Terraform can [generate resource configuration](/terraform/language/import/generating-configuration) when planning to import new resources. When set to `false`, Terraform returns an error when `import` blocks do not have a corresponding `resource` block. | +| `data.attributes.auto-apply` | bool | Defaults to the [Auto Apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) workspace setting. | Determines if Terraform automatically applies the configuration on a successful `terraform plan`. | +| `data.attributes.debugging-mode` | bool | `false` | When set to `true`, enables verbose logging for the queued plan. | +| `data.attributes.is-destroy` | bool | `false` | When set to `true`, the plan destroys all provisioned resources. Mutually exclusive with `refresh-only`. | +| `data.attributes.message` | string | `"Queued manually via the Terraform Enterprise API"` | Specifies the message associated with this run. | +| `data.attributes.refresh` | bool | `true` | Specifies whether or not to refresh the state before a plan. | +| `data.attributes.refresh-only` | bool | `false` | When set to `true`, this run refreshes the state without modifying any resources. Mutually exclusive with `is-destroy`. | +| `data.attributes.replace-addrs` | array\[string] | | Specifies an optional list of resource addresses to be passed to the `-replace` flag. | +| `data.attributes.target-addrs` | array\[string] | | Specifies an optional list of resource addresses to be passed to the `-target` flag. | +| `data.attributes.variables` | array\[{key, value}] | (empty array) | Specifies an optional list of run-specific variable values. Refer to [Run-Specific Variables](/terraform/enterprise/workspaces/variables/managing-variables#run-specific-variables) for details. | +| `data.attributes.plan-only` | bool | (from configuration version) | Specifies if this is a [speculative, plan-only](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) run that Terraform cannot apply. Often used in conjunction with terraform-version in order to test whether an upgrade would succeed. | +| `data.attributes.save-plan` | bool | `false` | When set to `true`, the run is executed as a `save plan` run. A `save plan` run plans and checks the configuration without becoming the workspace's current run. These run types only becomes the current run if you confirm that you want to apply them when prompted. When creating new [configuration versions](/terraform/enterprise/api-docs/configuration-versions) for saved plan runs, be sure to make them `provisional`. | +| `data.attributes.terraform-version` | string | none | Specifies the Terraform version to use in this run. Only valid for plan-only runs; must be a valid Terraform version available to the organization. | +| `data.relationships.workspace.data.id` | string | none | Specifies the workspace ID to execute the run in. | +| `data.relationships.configuration-version.data.id` | string | none | Specifies the configuration version to use for this run. If the `configuration-version` object is omitted, Terraform uses the workspace's latest configuration version to create the run . | + +| Status | Response | Reason | +| ------- | -------------------------------------- | --------------------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "runs"`) | Successfully created a run | +| [404][] | [JSON API error object][] | Organization or workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "message": "Custom message" + }, + "type":"runs", + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-LLGHCr4SWy28wyGN" + } + }, + "configuration-version": { + "data": { + "type": "configuration-versions", + "id": "cv-n4XQPBa2QnecZJ4G" + } + } + } + } +} +``` + +### 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/runs +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-CZcmD7eagjhyX0vN" + } + } +} +``` + +## Apply a Run + +`POST /runs/:run_id/actions/apply` + +| Parameter | Description | +| --------- | ------------------- | +| `run_id` | The run ID to apply | + +Applies a run that is paused waiting for confirmation after a plan. This includes runs in the "needs confirmation" and "policy checked" states. This action is only required for runs that can't be auto-applied. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs for the workspace. + +-> **Note:** If the run has a soft failed sentinel policy, you will need to [override the policy check](/terraform/enterprise/api-docs/policy-checks#override-policy) before Terraform can apply the run. You can find policy check details in the `relationships` section of the [run details endpoint](#get-run-details) response. + +Applying a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint queues the request to perform an apply; the apply might not happen immediately. + +Since this endpoint represents an action (not a resource), it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------- | +| [202][] | none | Successfully queued an apply request. | +| [409][] | [JSON API error object][] | Run was not paused for confirmation; apply not allowed. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ---------------------------------- | +| `comment` | string | `null` | An optional comment about the run. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment":"Looks good to me" +} +``` + +### 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/runs/run-DQGdmrWMX8z9yWQB/actions/apply +``` + +## List Runs in a Workspace + +`GET /workspaces/:workspace_id/runs` + +| Parameter | Description | +| -------------- | ---------------------------------- | +| `workspace_id` | The workspace ID to list runs for. | + +By default, `plan_only` runs will be excluded from the results. To see all runs, use `filter[operation]` with all available operations included as a comma-separated list. +This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second. + +| Status | Response | Reason | +| ------- | ------------------------------------------------ | ------------------------ | +| [200][] | Array of [JSON API document][]s (`type: "runs"`) | Successfully listed runs | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | Required | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `page[number]` | If omitted, the endpoint returns the first page. | Optional | +| `page[size]` | If omitted, the endpoint returns 20 runs per page. | Optional | +| `filter[operation]` | A comma-separated list of run operations. The result lists runs that perform one of these operations. For details on options, refer to [Run operations](/terraform/enterprise/api-docs/run#run-operations). | Optional | +| `filter[status]` | A comma-separated list of run statuses. The result lists runs that are in one of the statuses you specify. For details on options, refer to [Run states](/terraform/enterprise/api-docs/run#run-states). | Optional | +| `filter[agent_pool_names]` | A comma-separated list of agent pool names. The result lists runs that use one of the agent pools you specify. | Optional | +| `filter[source]` | A comma-separated list of run sources. The result lists runs that came from one of the sources you specify. Options are listed in [Run Sources](/terraform/enterprise/api-docs/run#run-sources). | Optional | +| `filter[status_group]` | A single status group. The result lists runs whose status falls under this status group. For details on options, refer to [Run status groups](/terraform/enterprise/api-docs/run#run-status-groups). | Optional | +| `filter[timeframe]` | A single year period. The result lists runs that were created within the year you specify. An integer year or the string "year" for the past year are valid values. If omitted, the endpoint returns all runs since the creation of the workspace. | Optional | +| `search[user]` | Searches for runs that match the VCS username you supply. | Optional | +| `search[commit]` | Searches for runs that match the commit sha you specify. | Optional | +| `search[basic]` | Searches for runs that match the VCS username, commit sha, run_id, or run message your specify. HCP Terraform prioritizes `search[commit]` or `search[user]` and ignores `search[basic]` in favor of the higher priority parameters if you include them in your query. | Optional | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7" + } + }, + {...} + ], + "links": { + "first": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=1&page[size]=20", + "last": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=19206&page[size]=20", + "self": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=2&page[size]=20", + "prev": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=1&page[size]=20", + "next": "https://app.terraform.io/api/v2/workspaces/ws-yF7z4gyEQRhaCNG9/runs?page[number]=3&page[size]=20" + }, + "meta": { + "pagination": { + "current-page": 2, + "next-page": 3, + "prev-page": 1, + "page-size": 20, + "total-count": 384105, + "total-pages": 19206 + } + } +} +``` + +## List Runs in an Organization + +`GET /organizations/:organization_name/runs` + +| Parameter | Description | +| ------------------- | --------------------------------------- | +| `organization_name` | The organization name to list runs for. | + +This endpoint has an adjusted rate limit of 30 requests per minute. Note that most endpoints are limited to 30 requests per second. + +Note that this endpoint differs from others in the pagination metadata included in the response, such as the exclusion of the typical `total-count` and `total-pages`. See the Sample Response below for more details. + +| Status | Response | Reason | +| ------- | ------------------------------------------------ | ------------------------ | +| [200][] | Array of [JSON API document][]s (`type: "runs"`) | Successfully listed runs | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | Required | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `page[number]` | If omitted, the endpoint returns the first page. | Optional | +| `page[size]` | If omitted, the endpoint returns 20 runs per page. | Optional | +| `filter[operation]` | A comma-separated list of run operations. The result lists runs that perform one of these operations. For details on options, refer to [Run operations](/terraform/enterprise/api-docs/run#run-operations). | Optional | +| `filter[status]` | A comma-separated list of run statuses. The result lists runs that are in one of the statuses you specify. For details on options, refer to [Run states](/terraform/enterprise/api-docs/run#run-states). | Optional | +| `filter[agent_pool_names]` | A comma-separated list of agent pool names. The result lists runs that use one of the agent pools you specify. | Optional | +| `filter[workspace_names]` | A comma-separated list of workspace names. The result lists runs that belong to one of the workspaces your specify. | Optional | +| `filter[source]` | A comma-separated list of run sources. The result lists runs that came from one of the sources you specify. Options are listed in [Run Sources](/terraform/enterprise/api-docs/run#run-sources). | Optional | +| `filter[status_group]` | A single status group. The result lists runs whose status falls under this status group. For details on options, refer to [Run status groups](/terraform/enterprise/api-docs/run#run-status-groups). | Optional | +| `filter[timeframe]` | A single year period. The result lists runs that were created within the year you specify. An integer year or the string "year" for the past year are valid values. If omitted, the endpoint returns runs created in the last year. | Optional | +| `search[user]` | Searches for runs that match the VCS username you supply. | Optional | +| `search[commit]` | Searches for runs that match the commit sha you specify. | Optional | +| `search[basic]` | Searches for runs that match the VCS username, commit sha, run_id, or run message your specify. HCP Terraform prioritizes `search[commit]` or `search[user]` and ignores `search[basic]` in favor of the higher priority parameters if you include them in your query. | Optional | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/hashicorp/runs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7" + } + }, + {...} + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=2&page[size]=20", + "prev": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=1&page[size]=20", + "next": "https://app.terraform.io/api/v2/organizations/hashicorp/runs?page[number]=3&page[size]=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "next-page": 2, + "prev-page": null, + "page-size": 20 + } + } +} +``` + +## Get run details + +`GET /runs/:run_id` + +| Parameter | Description | +| --------- | ------------------ | +| `:run_id` | The run ID to get. | + +This endpoint is used for showing details of a specific run. + +| Status | Response | Reason | +| ------- | -------------------------------------- | ------------------------------------ | +| [200][] | [JSON API document][] (`type: "runs"`) | Success | +| [404][] | [JSON API error object][] | Run not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/runs/run-bWSq4YeYpfrW4mx7 +``` + +### Sample Response + +```json +{ + "data": { + "id": "run-CZcmD7eagjhyX0vN", + "type": "runs", + "attributes": { + "actions": { + "is-cancelable": true, + "is-confirmable": false, + "is-discardable": false, + "is-force-cancelable": false + }, + "canceled-at": null, + "created-at": "2021-05-24T07:38:04.171Z", + "has-changes": false, + "auto-apply": false, + "allow-empty-apply": false, + "allow-config-generation": false, + "is-destroy": false, + "message": "Custom message", + "plan-only": false, + "source": "tfe-api", + "status-timestamps": { + "plan-queueable-at": "2021-05-24T07:38:04+00:00" + }, + "status": "pending", + "trigger-reason": "manual", + "target-addrs": null, + "permissions": { + "can-apply": true, + "can-cancel": true, + "can-comment": true, + "can-discard": true, + "can-force-execute": true, + "can-force-cancel": true, + "can-override-policy-check": true + }, + "refresh": false, + "refresh-only": false, + "replace-addrs": null, + "save-plan": false, + "variables": [] + }, + "relationships": { + "apply": {...}, + "comments": {...}, + "configuration-version": {...}, + "cost-estimate": {...}, + "created-by": {...}, + "input-state-version": {...}, + "plan": {...}, + "run-events": {...}, + "policy-checks": {...}, + "task-stages": {...}, + "workspace": {...}, + "workspace-run-alerts": {...} + }, + "links": { + "self": "/api/v2/runs/run-bWSq4YeYpfrW4mx7" + } + } +} +``` + +## Discard a Run + +`POST /runs/:run_id/actions/discard` + +| Parameter | Description | +| --------- | --------------------- | +| `run_id` | The run ID to discard | + +The `discard` action can be used to skip any remaining work on runs that are paused waiting for confirmation or priority. This includes runs in the "pending," "needs confirmation," "policy checked," and "policy override" states. + +Discarding a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint queues the request to perform a discard; the discard might not happen immediately. After discarding, the run is completed and later runs can proceed. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [202][] | none | Successfully queued a discard request. | +| [409][] | [JSON API error object][] | Run was not paused for confirmation or priority; discard not allowed. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ------------------------------------------------------ | +| `comment` | string | `null` | An optional explanation for why the run was discarded. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment": "This run was discarded" +} +``` + +### 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/runs/run-DQGdmrWMX8z9yWQB/actions/discard +``` + +## Cancel a Run + +`POST /runs/:run_id/actions/cancel` + +| Parameter | Description | +| --------- | -------------------- | +| `run_id` | The run ID to cancel | + +The `cancel` action can be used to interrupt a run that is currently planning or applying. Performing a cancel is roughly equivalent to hitting ctrl+c during a Terraform plan or apply on the CLI. The running Terraform process is sent an `INT` signal, which instructs Terraform to end its work and wrap up in the safest way possible. + +Canceling a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint queues the request to perform a cancel; the cancel might not happen immediately. After canceling, the run is completed and later runs can proceed. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------- | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Run was not planning or applying; cancel not allowed. | +| [404][] | [JSON API error object][] | Run was not found or user not authorized. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ----------------------------------------------------- | +| `comment` | string | `null` | An optional explanation for why the run was canceled. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment": "This run was stuck and would never finish." +} +``` + +### 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/runs/run-DQGdmrWMX8z9yWQB/actions/cancel +``` + +## Forcefully cancel a run + +`POST /runs/:run_id/actions/force-cancel` + +| Parameter | Description | +| --------- | -------------------- | +| `run_id` | The run ID to cancel | + +The `force-cancel` action is like [cancel](#cancel-a-run), but ends the run immediately. Once invoked, the run is placed into a `canceled` state, and the running Terraform process is terminated. The workspace is immediately unlocked, allowing further runs to be queued. The `force-cancel` operation requires admin access to the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint enforces a prerequisite that a [non-forceful cancel](#cancel-a-run) is performed first, and a cool-off period has elapsed. To determine if this criteria is met, it is useful to check the `data.attributes.is-force-cancelable` value of the [run details endpoint](#get-run-details). The time at which the force-cancel action will become available can be found using the [run details endpoint](#get-run-details), in the key `data.attributes.force_cancel_available_at`. Note that this key is only present in the payload after the initial cancel has been initiated. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +~> **Warning:** This endpoint has potentially dangerous side-effects, including loss of any in-flight state in the running Terraform process. Use this operation with extreme caution. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| [202][] | none | Successfully queued a cancel request. | +| [409][] | [JSON API error object][] | Run was not planning or applying, has not been canceled non-forcefully, or the cool-off period has not yet passed. | +| [404][] | [JSON API error object][] | Run was not found or user not authorized. | + +### Request Body + +This POST endpoint allows an optional JSON object with the following properties as a request payload. + +| Key path | Type | Default | Description | +| --------- | ------ | ------- | ----------------------------------------------------- | +| `comment` | string | `null` | An optional explanation for why the run was canceled. | + +### Sample Payload + +This payload is optional, so the `curl` command will work without the `--data @payload.json` option too. + +```json +{ + "comment": "This run was stuck and would never finish." +} +``` + +### 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/runs/run-DQGdmrWMX8z9yWQB/actions/force-cancel +``` + +## Forcefully execute a run + +`POST /runs/:run_id/actions/force-execute` + +| Parameter | Description | +| --------- | --------------------- | +| `run_id` | The run ID to execute | + +The force-execute action cancels all prior runs that are not already complete, unlocking the run's workspace and allowing the run to be executed. (It initiates the same actions as the "Run this plan now" button at the top of the view of a pending run.) + +Force-executing a run requires permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +This endpoint enforces the following prerequisites: + +- The target run is in the "pending" state. +- The workspace is locked by another run. +- The run locking the workspace can be discarded. + +This endpoint represents an action as opposed to a resource. As such, it does not return any object in the response body. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +~> **Note:** While useful at times, force-executing a run circumvents the typical workflow of applying runs using HCP Terraform. It is not intended for regular use. If you find yourself using it frequently, please reach out to HashiCorp Support for help in developing an alternative approach. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------- | +| [202][] | none | Successfully initiated the force-execution process. | +| [403][] | [JSON API error object][] | Run is not pending, its workspace was not locked, or its workspace association was not found. | +| [409][] | [JSON API error object][] | The run locking the workspace was not in a discardable state. | +| [404][] | [JSON API error object][] | Run was not found or user not authorized. | + +### Request Body + +This POST endpoint does not take a request body. + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/runs/run-DQGdmrWMX8z9yWQB/actions/force-execute +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `plan` - Additional information about plans. +- `apply` - Additional information about applies. +- `created_by` - Full user records of the users responsible for creating the runs. +- `cost_estimate` - Additional information about cost estimates. +- `configuration_version` - The configuration record used in the run. +- `configuration_version.ingress_attributes` - The commit information used in the run. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/ssh-keys.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/ssh-keys.mdx new file mode 100644 index 0000000000..70f2e54828 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/ssh-keys.mdx @@ -0,0 +1,320 @@ +--- +page_title: /ssh-keys API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/ssh-keys` endpoint to read, get, create, + update, and delete an organization's SSH keys. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# SSH keys API reference + +The `ssh-key` object represents an SSH key which includes a name and the SSH private key. An organization can have multiple SSH keys available. + +SSH keys can be used in two places: + +- You can assign them to VCS provider integrations, which are available in the API as `oauth-tokens`. Refer to [OAuth Tokens](/terraform/enterprise/api-docs/oauth-tokens) for additional information. Azure DevOps Server and Bitbucket Data Center require an SSH key. Other providers only require an SSH key when your repositories include submodules that are only accessible using an SSH connection instead of your VCS provider's API. +- They can be [assigned to workspaces](/terraform/enterprise/api-docs/workspaces#assign-an-ssh-key-to-a-workspace) and used when Terraform needs to clone modules from a Git server. This is only necessary when your configurations directly reference modules from a Git server; you do not need to do this if you use HCP Terraform's [private module registry](/terraform/enterprise/registry). + +Listing and viewing SSH keys requires either permission to manage VCS settings for the organization, or admin access to at least one workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +~> **Important:** The list and read methods on this API only provide metadata about SSH keys. The actual private key text is write-only, and HCP Terraform never provides it to users via the API or UI. + +## List SSH Keys + +`GET /organizations/:organization_name/ssh-keys` + +| Parameter | Description | +| -------------------- | -------------------------------------------------- | +| `:organization_name` | The name of the organization to list SSH keys for. | + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ---------------------------------------------------- | --------------------------------------------- | +| [200][] | Array of [JSON API document][]s (`type: "ssh-keys"`) | Success | +| [404][] | [JSON API error object][] | Organization not found or user not authorized | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | ------------------------------------------------------------------------ | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 ssh keys per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/organizations/my-organization/ssh-keys +``` + +### Sample Response + +```json +{ + "data": [ + { + "attributes": { + "name": "SSH Key" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } + ] +} +``` + +## Get an SSH Key + +`GET /ssh-keys/:ssh_key_id` + +| Parameter | Description | +| ------------- | ---------------------- | +| `:ssh_key_id` | The SSH key ID to get. | + +This endpoint is for looking up the name associated with an SSH key ID. It does not retrieve the key text. + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ---------------------------------------- | +| [200][] | [JSON API document][] (`type: "ssh-keys"`) | Success | +| [404][] | [JSON API error object][] | SSH key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM +``` + +### Sample Response + +```json +{ + "data": { + "attributes": { + "name": "SSH Key" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } +} +``` + +## Create an SSH Key + +`POST /organizations/:organization_name/ssh-keys` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create an SSH key in. The organization must already exist, and the token authenticating the API request must have permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "ssh-keys"`) | Success | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [404][] | [JSON API error object][] | User not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------- | ------ | ------- | -------------------------------- | +| `data.type` | string | | Must be `"ssh-keys"`. | +| `data.attributes.name` | string | | A name to identify the SSH key. | +| `data.attributes.value` | string | | The text of the SSH private key. | + +### Sample Payload + +```json +{ + "data": { + "type": "ssh-keys", + "attributes": { + "name": "SSH Key", + "value": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAm6+JVgl..." + } + } +} +``` + +### 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/organizations/my-organization/ssh-keys +``` + +### Sample Response + +```json +{ + "data": { + "attributes": { + "name": "SSH Key" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } +} +``` + +## Update an SSH Key + +`PATCH /ssh-keys/:ssh_key_id` + +| Parameter | Description | +| ------------- | ------------------------- | +| `:ssh_key_id` | The SSH key ID to update. | + +This endpoint replaces the name of an existing SSH key. + +Editing SSH keys requires permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------------------------ | ---------------------------------------- | +| [200][] | [JSON API document][] (`type: "ssh-keys"`) | Success | +| [404][] | [JSON API error object][] | SSH key not found or user not authorized | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------- | ------ | --------- | --------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"ssh-keys"`. | +| `data.attributes.name` | string | (nothing) | A name to identify the SSH key. If omitted, the existing name is preserved. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "SSH Key for GitHub" + } + } +} +``` + +### 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/ssh-keys/sshkey-GxrePWre1Ezug7aM +``` + +### Sample Response + +```json +{ + "data": { + "attributes": { + "name": "SSH Key for GitHub" + }, + "id": "sshkey-GxrePWre1Ezug7aM", + "links": { + "self": "/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM" + }, + "type": "ssh-keys" + } +} +``` + +## Delete an SSH Key + +`DELETE /ssh-keys/:ssh_key_id` + +| Parameter | Description | +| ------------- | ------------------------- | +| `:ssh_key_id` | The SSH key ID to delete. | + +Deleting SSH keys requires permission to manage VCS settings. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **Note:** This endpoint cannot be accessed with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------- | ---------------------------------------- | +| [204][] | No Content | Success | +| [404][] | [JSON API error object][] | SSH key not found or user not authorized | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/ssh-keys/sshkey-GxrePWre1Ezug7aM +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/stability-policy.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/stability-policy.mdx new file mode 100644 index 0000000000..1b59e2d1f2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/stability-policy.mdx @@ -0,0 +1,25 @@ +--- +page_title: API stability policy for Terraform Enterprise +description: >- + Learn how HashiCorp plans for stability, backward compatibility, and + deprecation for the Terraform Enterprise APIs. +source: terraform-docs-common +--- + +# API stability policy + +The HCP Terraform API will continue to evolve, but we consider it stable for general use, and HashiCorp will maintain all stable API endpoints in a backwards compatible manner. (Stable endpoints are any endpoints _not_ marked as beta.) If we need to make a change that we consider backwards incompatible, then we will create a new endpoint that serves the same purpose; the old endpoint will be maintained until declared [deprecated](#deprecation-policy). + +The following changes are considered to be backwards compatible: + +- Adding new API endpoints. +- Adding new attributes, links, or relationships to existing API requests and responses. +- Adding new optional query parameters to existing API requests. + +Security vulnerabilities are an exception to this stability policy; we will make backwards incompatible changes to stable endpoints if it is necessary to protect our security or the security of our users. + +Endpoints that are in beta are subject to change without notice. + +## Deprecation Policy + +The deprecation policy provides users the opportunity to continue to consume API endpoints for a period of time after they have been superseded. Deprecation notices for endpoints should be readily available through various channels of communication, including documentation and HTTP responses. An endpoint should be available for at least three (3) months from the date on which it has been declared deprecated. (This time is cited as a minimum; endpoint availability may be longer based on contracted agreements.) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/state-version-outputs.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/state-version-outputs.mdx new file mode 100644 index 0000000000..cb5ef168b0 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/state-version-outputs.mdx @@ -0,0 +1,244 @@ +--- +page_title: /state-version-outputs API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/state-version-outputs` endpoint to read + the outputs from a specified Terraform state version or a workspace's current + outputs. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# State version outputs API reference + +State version outputs are the [output values](/terraform/language/values/outputs) from a Terraform state file. They include +the name and value of the output, as well as a sensitive boolean if the value should be hidden by default in UIs. + +~> **Important:** The state version outputs for a state version (as well as some other information about it) might be **populated asynchronously** by HCP Terraform. These values might not be immediately available after the state version is uploaded. The `resources-processed` property on the associated [state version object](/terraform/enterprise/api-docs/state-versions) indicates whether or not HCP Terraform has finished any necessary asynchronous processing. If you need to use these values, be sure to wait for `resources-processed` to become `true` before assuming that the values are in fact empty. + +## List State Version Outputs + +`GET /state-versions/:state_version_id/outputs` + +Listing state version outputs requires permission to read state outputs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:state_version_id` | The ID of the desired state version. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully returned a list of outputs for the given state version. | +| [404][] | [JSON API error object][] | State version not found, or user unauthorized to perform action. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 state version outputs per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/state-versions/sv-SDboVZC8TCxXEneJ/outputs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsout-xFAmCR3VkBGepcee", + "type": "state-version-outputs", + "attributes": { + "name": "fruits", + "sensitive": false, + "type": "array", + "value": [ + "apple", + "strawberry", + "blueberry", + "rasberry" + ], + "detailed_type": [ + "tuple", + [ + "string", + "string", + "string", + "string" + ] + ] + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-xFAmCR3VkBGepcee" + } + }, + { + "id": "wsout-vspuB754AUNkfxwo", + "type": "state-version-outputs", + "attributes": { + "name": "vegetables", + "sensitive": false, + "type": "array", + "value": [ + "carrots", + "potato", + "tomato", + "onions" + ], + "detailed_type": [ + "tuple", + [ + "string", + "string", + "string", + "string" + ] + ] + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-vspuB754AUNkfxwo" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/state-versions/sv-SVB5wMrDL1XUgJ4G/outputs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/state-versions/sv-SVB5wMrDL1XUgJ4G/outputs?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/state-versions/sv-SVB5wMrDL1XUgJ4G/outputs?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "page-size": 20, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 2 + } + } +} +``` + +## Show a State Version Output + +`GET /state-version-outputs/:state_version_output_id` + +| Parameter | Description | +| -------------------------- | ------------------------------------------- | +| `:state_version_output_id` | The ID of the desired state version output. | + +State version output IDs must be obtained from a [state version object](/terraform/enterprise/api-docs/state-versions). When requesting a state version, you can optionally add `?include=outputs` to include full details for all of that state version's outputs. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "state-version-outputs"`) | Success. | +| [404][] | [JSON API error object][] | State version output not found or user not authorized. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + https://app.terraform.io/api/v2/state-version-outputs/wsout-J2zM24JPFbfc7bE5 +``` + +### Sample Response + +```json +{ + "data": { + "id": "wsout-J2zM24JPFbfc7bE5", + "type": "state-version-outputs", + "attributes": { + "name": "flavor", + "sensitive": false, + "type": "string", + "value": "Peanut Butter", + "detailed-type": "string" + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-J2zM24JPFbfc7bE5" + } + } +} +``` + +## Show Current State Version Outputs for a Workspace + +This endpoint allows organization users, who do not have permissions to read state versions, to fetch the latest [output values](/terraform/language/values/outputs) for a workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +-> **Note:** Sensitive values are not revealed and will be returned as `null`. To fetch an output including sensitive values see [Show a State Version Output](/terraform/enterprise/api-docs/state-version-outputs#show-a-state-version-output). + +`GET /workspaces/:workspace_id/current-state-version-outputs` + +| Parameter | Description | +| --------------- | --------------------------------------------- | +| `:workspace_id` | The ID of the workspace to read outputs from. | + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "state-version-outputs"`) | Successfully returned a list of outputs for the given workspace. | +| [404][] | [JSON API error object][] | State version outputs not found or user not authorized. | +| [503][] | [JSON API error object][] | State version outputs are being processed and are not ready. Retry the request. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-G4zM299PFbfc10E5/current-state-version-outputs +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsout-J2zM24JPFbfc7bE5", + "type": "state-version-outputs", + "attributes": { + "name": "flavor", + "sensitive": false, + "type": "string", + "value": "Peanut Butter", + "detailed-type": "string" + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-J2zM24JPFbfc7bE5" + } + }, + { + "id": "wsout-FLzM23Gcd5f37bE5", + "type": "state-version-outputs", + "attributes": { + "name": "recipe", + "sensitive": true, + "type": "string", + "value": "Don Douglas' Peanut Butter Frenzy", + "detailed-type": "string" + }, + "links": { + "self": "/api/v2/state-version-outputs/wsout-FLzM23Gcd5f37bE5" + } + } + ] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/state-versions.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/state-versions.mdx new file mode 100644 index 0000000000..9e8873612d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/state-versions.mdx @@ -0,0 +1,1241 @@ +--- +page_title: /state-versions API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/state-versions` endpoint to read, create, + upload, fetch, rollback, delete, and mark state versions for garbage + collection. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# State versions API reference + +## Attributes + +State version API objects represent an instance of Terraform state data, but do not directly contain the stored state. Instead, they contain information about the state, its properties, and its contents, and include one or more URLs from which the state can be downloaded. + +Some of the information returned in a state version API object might be **populated asynchronously** by HCP Terraform. This includes resources, modules, providers, and the [state version outputs](/terraform/enterprise/api-docs/state-version-outputs) associated with the state version. These values might not be immediately available after the state version is uploaded. The `resources-processed` property on the state version object indicates whether or not HCP Terraform has finished any necessary asynchronous processing. If you need to use these values, be sure to wait for `resources-processed` to become `true` before assuming that the values are in fact empty. + +| Attribute | Description | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `billable-rum-count` | Count of billable Resources Under Management (RUM). Only present for organization members on HCP Terraform RUM plans with visibility of billable RUM usage. | +| `hosted-json-state-download-url` | A URL from which you can download the state data in a [stable format](/terraform/internals/json-format) appropriate for external integrations to consume. Only available if the state was created by Terraform 1.3+. | +| `hosted-state-download-url` | A URL from which you can download the raw state data, in the format used internally by Terraform. | +| `hosted-json-state-upload-url` | A URL to which you can upload state data in a [stable format](/terraform/internals/json-format) appropriate for external integrations to consume. You can upload JSON state content once per state version. | +| `hosted-state-upload-url` | A URL to which you can upload state data in the format used Terraform uses internally. You can upload state data once per state version. | +| `modules` | Extracted information about the Terraform modules in this state data. Populated asynchronously. | +| `providers` | Extracted information about the Terraform providers used for resources in this state data. Populated asynchronously. | +| `intermediate` | A boolean flag that indicates the state version is a snapshot and not yet set as the current state version for a workspace. The last intermediate state version becomes the current state version when the workspace is unlocked. Not yet supported in Terraform Enterprise. | +| `resources` | Extracted information about the resources in this state data. Populated asynchronously. | +| `resources-processed` | A Boolean flag indicating whether HCP Terraform has finished asynchronously extracting outputs, resources, and other information about this state data. | +| `serial` | The serial number of this state instance, which increases every time Terraform creates new state in the workspace. | +| `state-version` | The version of the internal state format used for this state. Different Terraform versions read and write different format versions, but it only changes infrequently. | +| `status` | Indicates a state version's content upload [status](/terraform/enterprise/api-docs/state-versions#state-version-status). This status can be `pending`, `finalized` or `discarded`. | +| `terraform-version` | The Terraform version that created this state. Populated asynchronously. | +| `vcs-commit-sha` | The SHA of the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository. | +| `vcs-commit-url` | A link to the configuration commit used in the Terraform run that produced this state. Only present if the workspace is connected to a VCS repository. | + +### State Version Status + +The state version status is found in `data.attributes.status`, and you can reference the following list of possible statuses. +A state version created through the API or CLI will only be listed in the UI if it is has a `finalized` status. + +| State | Description | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `pending` | Indicates that a state version has been created but the state data is not encoded within the request. Pending state versions do not contain state data and do not appear in the UI. You cannot unlock the workspace until the latest state version is finalized. | +| `finalized` | Indicates that the state version has been successfully uploaded to HCP Terraform or that the state version was created with a valid `state` attribute. | +| `discarded` | The state version was discarded because it was superseded by a newer state version before it could be uploaded. | +| `backing_data_soft_deleted` | The backing files associated with this state version are marked for garbage collection. Terraform permanently deletes backing files associated with this state version after a set number of days, but you can restore the backing data associated with it before it is permanently deleted. | +| `backing_data_permanently_deleted` | The backing files associated with this state version have been permanently deleted and can no longer be restored. | + +## Create a State Version + +> **Hands-on:** Try the [Version Remote State with the HCP Terraform API](/terraform/tutorials/cloud/cloud-state-api) tutorial to download a remote state file and use the Terraform API to create a new state version. + +`POST /workspaces/:workspace_id/state-versions` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to create the new state version in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +Creates a state version and sets it as the current state version for the given workspace. The workspace must be locked by the user creating a state version. The workspace may be locked [with the API](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) or [with the UI](/terraform/enterprise/workspaces/settings#locking). This is most useful for migrating existing state from Terraform Community edition into a new HCP Terraform workspace. + +Creating state versions requires permission to read and write state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +!> **Warning:** Use caution when uploading state to workspaces that have already performed Terraform runs. Replacing state improperly can result in orphaned or duplicated infrastructure resources. + +-> **Note:** For Free Tier organizations, HCP Terraform always retains at least the last 100 states (across all workspaces) and at least the most recent state for every workspace. Additional states beyond the last 100 are retained for six months, and are then deleted. + +-> **Note:** You cannot access this endpoint with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------- | ----------------------------------------------------------------- | +| [201][] | [JSON API document][] | Successfully created a state version. | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action. | +| [409][] | [JSON API error object][] | Conflict; check the error object for more information. | +| [412][] | [JSON API error object][] | Precondition failed; check the error object for more information. | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.). | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------ | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"state-versions"`. | +| `data.attributes.serial` | integer | | The serial of the state version. Must match the serial value extracted from the raw state file. | +| `data.attributes.md5` | string | | An MD5 hash of the raw state version. | +| `data.attributes.state` | string | (nothing) | **Optional** Base64 encoded raw state file. If omitted, you must use the upload method below to complete the state version creation. The workspace may not be unlocked normally until the state version is uploaded. | +| `data.attributes.lineage` | string | (nothing) | **Optional** Lineage of the state version. Should match the lineage extracted from the raw state file. Early versions of terraform did not have the concept of lineage, so this is an optional attribute. | +| `data.attributes.json-state` | string | (nothing) | **Optional** Base64 encoded json state, as expressed by `terraform show -json`. See [JSON Output Format](/terraform/internals/json-format) for more details. | +| `data.attributes.json-state-outputs` | string | (nothing) | **Optional** Base64 encoded output values as represented by `terraform show -json` (the contents of the values/outputs key). If provided, the workspace outputs populate immediately. If omitted, HCP Terraform populates the workspace outputs from the given state after a short time. | +| `data.relationships.run.data.id` | string | (nothing) | **Optional** The ID of the run to associate with the state version. | + +### Sample Payload + +```json +{ + "data": { + "type":"state-versions", + "attributes": { + "serial": 1, + "md5": "d41d8cd98f00b204e9800998ecf8427e", + "lineage": "871d1b4a-e579-fb7c-ffdb-f0c858a647a7", + "state": "...", + "json-state": "...", + "json-state-outputs": "..." + }, + "relationships": { + "run": { + "data": { + "type": "runs", + "id": "run-bWSq4YeYpfrW4mx7" + } + } + } + } +} +``` + +### 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/workspaces/ws-6fHMCom98SDXSQUv/state-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-DmoXecHePnNznaA4", + "type": "state-versions", + "attributes": { + "vcs-commit-sha": null, + "vcs-commit-url": null, + "created-at": "2018-07-12T20:32:01.490Z", + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/f55b739b-ff03-4716-b436-726466b96dc4", + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/4fde7951-93c0-4414-9a40-f3abc4bac490", + "hosted-state-upload-url": null, + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": true, + "serial": 1 + }, + "links": { + "self": "/api/v2/state-versions/sv-DmoXecHePnNznaA4" + } + } +} +``` + +## Upload State and JSON State + + You can upload state version content in the same request when creating a state version. However, we _strongly_ recommend that you upload content separately. + +`PUT https://archivist.terraform.io/v1/object/` + +HCP Terraform returns a `hosted-state-upload-url` or `hosted-json-state-upload-url` returned when you create a `state-version`. Once you upload state content, this URL is hidden on the resource and _no longer available_. + +### Sample Request + +In the below example, `@filename` is the name of Terraform state file you wish to upload. + +```shell +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @filename \ + https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da +``` + +## List State Versions for a Workspace + +`GET /state-versions` + +Listing state versions requires permission to read state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------------------- | -------------------------------------------------------------------------------------- | +| `filter[workspace][name]` | **Required** The name of one workspace to list versions for. | +| `filter[organization][name]` | **Required** The name of the organization that owns the desired workspace. | +| `filter[status]` | **Optional.** Filter state versions by status: `pending`, `finalized`, or `discarded`. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 state versions per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + "https://app.terraform.io/api/v2/state-versions?filter%5Bworkspace%5D%5Bname%5D=my-workspace&filter%5Borganization%5D%5Bname%5D=my-organization" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + }, + { + "id": "sv-QYKf6GvNv75ZPTBr", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-01T21:40:25.941Z", + "size": 819, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + } + ], + "resources-processed": true, + "serial": 8, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/12345abcdef", + "vcs-commit-sha": "12345abcdef" + }, + "relationships": { + "run": { + "data": { + "id": "run-cVtxks6R8wsjCZMD", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-MmqMhmht6jFmLRvh", + "type": "state-version-outputs" + }, + { + "id": "wsout-Kuo9TCHg3oDLDQqa", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-QYKf6GvNv75ZPTBr" + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io.io/api/v2/state-versions?filter%5Borganization%5D%5Bname%5D=hashicorp&filter%5Bworkspace%5D%5Bname%5D=my-workspace&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": 10 + } + } +} +``` + +## Fetch the Current State Version for a Workspace + +`GET /workspaces/:workspace_id/current-state-version` + +| Parameter | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID for the workspace whose current state version you want to fetch. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +Fetches the current state version for the given workspace. This state version +will be the input state when running terraform operations. + +Viewing state versions requires permission to read state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully returned current state version for the given workspace. | +| [404][] | [JSON API error object][] | Workspace not found, workspace does not have a current state version, or user unauthorized to perform action. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-6fHMCom98SDXSQUv/current-state-version +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "billable-rum-count": 0, + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Show a State Version + +`GET /state-versions/:state_version_id` + +Viewing state versions requires permission to read state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | ------------------------------------ | +| `:state_version_id` | The ID of the desired state version. | + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully returned current state version for the given workspace. | +| [404][] | [JSON API error object][] | Workspace not found, workspace does not have a current state version, or user unauthorized to perform action. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/state-versions/sv-SDboVZC8TCxXEneJ +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "finalized", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Rollback to a Previous State Version + +`PATCH /workspaces/:workspace_id/state-versions` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to create the new state version in. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +Creates a state version by duplicating the specified state version and sets it as the current state version for the given workspace. The workspace must be locked by the user creating a state version. The workspace may be locked [with the API](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) or [with the UI](/terraform/enterprise/workspaces/settings#locking). This is most useful for rolling back to a known-good state after an operation such as a Terraform upgrade didn't go as planned. + +Creating state versions requires permission to read and write state versions for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +!> **Warning:** Use caution when rolling back to a previous state. Replacing state improperly can result in orphaned or duplicated infrastructure resources. + +-> **Note:** You cannot access this endpoint with [organization tokens](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------- | +| [201][] | [JSON API document][] | Successfully rolled back. | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action. | +| [409][] | [JSON API error object][] | Conflict; check the error object for more information. | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.). | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| --------------------------------------------------- | ------ | ------- | -------------------------------------------------------------- | +| `data.type` | string | | Must be `"state-versions"`. | +| `data.relationships.rollback-state-version.data.id` | string | | The ID of the state version to use for the rollback operation. | + +### Sample Payload + +```json +{ + "data": { + "type":"state-versions", + "relationships": { + "rollback-state-version": { + "data": { + "type": "state-versions", + "id": "sv-bWfq4Y1YpRKW4mx7" + } + } + } + } +} +``` + +### 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/workspaces/ws-6fHMCom98SDXSQUv/state-versions +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-DmoXecHePnNznaA4", + "type": "state-versions", + "attributes": { + "created-at": "2022-11-22T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "1.3.5" + }, + "relationships": { + "rollback-state-version": { + "data": { + "id": "sv-YfmFLgTv31VZsP", + "type": "state-versions" + } + } + }, + "links": { + "self": "/api/v2/state-versions/sv-DmoXecHePnNznaA4" + } + } +} +``` + +## Mark a State Version for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/state-versions/:state_version_id/actions/soft_delete_backing_data` + +This endpoint directs Terraform Enterprise to _soft delete_ the backing files associated with this state version. Soft deletion marks the state version for garbage collection. Terraform permanently deletes state versions after a set number of days unless the state version is restored. Once a state version is soft deleted, any attempts to read the state version will fail. Refer to [State Version Status](#state-version-status) for information about all data states. + +This endpoint can only soft delete state versions that are in an [`finalized` state](#state-version-status) and are not the current state version. Otherwise, calling this endpoint results in an error. + +You must have organization owner permissions to soft delete state versions. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | ----------------------------------------------------------- | +| `:state_version_id` | The ID of the state version to mark for garbage collection. | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Terraform successfully marked the data for garbage collection. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_soft_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the state version or the user is not authorized to modify the state version. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/soft_delete_backing_data + --data {"data": {"attributes": {"delete-older-than-n-days": 23}}} +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "backing_data_soft_deleted", + "intermediate": false, + "delete-older-than-n-days": 23, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Restore a State Version Marked for Garbage Collection + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/state-versions/:state_version_id/actions/restore_backing_data` + +This endpoint directs Terraform Enterprise to restore backing files associated with this state version. This endpoint can only restore state versions that are not in a [`backing_data_permanently_deleted` state](#state-version-status). Terraform restores applicable state versions back to their `finalized` state. Otherwise, calling this endpoint results in an error. + +You must have organization owner permissions to restore state versions. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | --------------------------------------- | +| `:state_version_id` | The ID of the state version to restore. | + +| Status | Response | Reason | +| ------- | ------------------------- | --------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Terraform successfully initiated the restore process. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `finalized`. | +| [404][] | [JSON API error object][] | Terraform did not find the state version or the user is not authorized to modify the state version. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/restore_backing_data +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "uploaded", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## Permanently Delete a State Version + + +This endpoint is exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +`POST /api/v2/state-versions/:state_version_id/actions/permanently_delete_backing_data` + +This endpoint directs Terraform Enterprise to permanently delete backing files associated with this state version. This endpoint can only permanently delete state versions that are in an [`backing_data_soft_deleted` state](#state-version-status) and are not the current state version. Otherwise, calling this endpoint results in an error. + +You must have organization owner permissions to permanently delete state versions. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information about permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Parameter | Description | +| ------------------- | -------------------------------------------------- | +| `:state_version_id` | The ID of the state version to permanently delete. | + +| Status | Response | Reason | +| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Terraform deleted the data permanently. | +| [400][] | [JSON API error object][] | Terraform failed to transition the state to `backing_data_permanently_deleted`. | +| [404][] | [JSON API error object][] | Terraform did not find the state version or the user is not authorized to modify the state version data. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/state-versions/sv-ntv3HbhJqvFzamy7/actions/permanently_delete_backing_data +``` + +### Sample Response + +```json +{ + "data": { + "id": "sv-g4rqST72reoHMM5a", + "type": "state-versions", + "attributes": { + "created-at": "2021-06-08T01:22:03.794Z", + "size": 940, + "hosted-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-state-upload-url": null, + "hosted-json-state-download-url": "https://archivist.terraform.io/v1/object/...", + "hosted-json-state-upload-url": null, + "status": "backing_data_permanently_deleted", + "intermediate": false, + "modules": { + "root": { + "null-resource": 1, + "data.terraform-remote-state": 1 + } + }, + "providers": { + "provider[\"terraform.io/builtin/terraform\"]": { + "data.terraform-remote-state": 1 + }, + "provider[\"registry.terraform.io/hashicorp/null\"]": { + "null-resource": 1 + } + }, + "resources": [ + { + "name": "other_username", + "type": "data.terraform_remote_state", + "count": 1, + "module": "root", + "provider": "provider[\"terraform.io/builtin/terraform\"]" + }, + { + "name": "random", + "type": "null_resource", + "count": 1, + "module": "root", + "provider": "provider[\"registry.terraform.io/hashicorp/null\"]" + } + ], + "resources-processed": true, + "serial": 9, + "state-version": 4, + "terraform-version": "0.15.4", + "vcs-commit-url": "https://gitlab.com/my-organization/terraform-test/-/commit/abcdef12345", + "vcs-commit-sha": "abcdef12345" + }, + "relationships": { + "run": { + "data": { + "id": "run-YfmFLWpgTv31VZsP", + "type": "runs" + } + }, + "created-by": { + "data": { + "id": "user-onZs69ThPZjBK2wo", + "type": "users" + }, + "links": { + "self": "/api/v2/users/user-onZs69ThPZjBK2wo", + "related": "/api/v2/runs/run-YfmFLWpgTv31VZsP/created-by" + } + }, + "workspace": { + "data": { + "id": "ws-noZcaGXsac6aZSJR", + "type": "workspaces" + } + }, + "outputs": { + "data": [ + { + "id": "wsout-V22qbeM92xb5mw9n", + "type": "state-version-outputs" + }, + { + "id": "wsout-ymkuRnrNFeU5wGpV", + "type": "state-version-outputs" + }, + { + "id": "wsout-v82BjkZnFEcscipg", + "type": "state-version-outputs" + } + ] + } + }, + "links": { + "self": "/api/v2/state-versions/sv-g4rqST72reoHMM5a" + } + } +} +``` + +## List State Version Outputs + +The output values from a state version are also available via the API. For details, see the [state version outputs documentation.](/terraform/enterprise/api-docs/state-version-outputs#list-state-version-outputs) + +### Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `created_by` - The user that created the state version. For state versions created via a run executed by HCP Terraform, this is an internal user account. +- `run` - The run that created the state version, if applicable. +- `run.created_by` - The user that manually triggered the run, if applicable. +- `run.configuration_version` - The configuration version used in the run. +- `outputs` - The parsed outputs for this state version. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-access.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-access.mdx new file mode 100644 index 0000000000..54ed8a467c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-access.mdx @@ -0,0 +1,433 @@ +--- +page_title: /team-workspaces API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/team-workspaces` endpoint to manage team + access to a workspace. Read, add, update, and remove a team's access to + workspaces. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Team access API reference + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +The team access APIs are used to associate a team to permissions on a workspace. A single `team-workspace` resource contains the relationship between the Team and Workspace, including the privileges the team has on the workspace. + +## Resource permissions + +A `team-workspace` resource represents a team's local permissions on a specific workspace. Teams can also have organization-level permissions that grant access to workspaces. HCP Terraform uses the more restrictive access level. For example, a team with the **Manage workspaces** permission enabled has admin access on all workspaces, even if their `team-workspace` on a particular workspace only grants read access. For more information, refer to [Managing Workspace Access](/terraform/enterprise/users-teams-organizations/teams/manage#managing-workspace-access). + +Any member of an organization can view team access relative to their own team memberships, including secret teams of which they are a member. Organization owners and workspace admins can modify team access or view the full set of secret team accesses. The organization token and the owners team token can act as an owner on these endpoints. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +## List Team Access to a Workspace + +`GET /team-workspaces` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ---------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action | + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters); remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter[workspace][id]` | **Required.** The workspace ID to list team access for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | +| `page[number]` | **Optional.** | +| `page[size]` | **Optional.** | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + "https://app.terraform.io/api/v2/team-workspaces?filter%5Bworkspace%5D%5Bid%5D=ws-XGA52YVykdTgryTN" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "tws-19iugLwoNgtWZbKP", + "type": "team-workspaces", + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "none", + "state-versions": "none", + "sentinel-mocks": "none", + "workspace-locking": false, + "run-tasks": false + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-19iugLwoNgtWZbKP" + } + } + ] +} +``` + +## Show a Team Access relationship + +`GET /team-workspaces/:id` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Team access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/workspace relationship. Obtain this from the [list team access action](#list-team-access-to-a-workspace) described above. | + +-> **Note:** As mentioned in [Add Team Access to a Workspace](#add-team-access-to-a-workspace) and [Update Team Access +to a Workspace](#update-team-access-to-a-workspace), 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. + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8 +``` + +### Sample Response + +```json +{ + "data": { + "id": "tws-s68jV4FWCDwWvQq8", + "type": "team-workspaces", + "attributes": { + "access": "write", + "runs": "apply", + "variables": "write", + "state-versions": "write", + "sentinel-mocks": "read", + "workspace-locking": true, + "run-tasks": false + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8" + } + } +} +``` + +## Add Team Access to a Workspace + +`POST /team-workspaces` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | ------------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Workspace or Team not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"team-workspaces"`. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `plan`, `write`, `admin`, or `custom`. | +| `data.attributes.runs` | string | "read" | If `access` is `custom`, the permission to grant for the workspace's runs. Can only be used when `access` is `custom`. Valid values include `read`, `plan`, or `apply`. | +| `data.attributes.variables` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's variables. Can only be used when `access` is `custom`. Valid values include `none`, `read`, or `write`. | +| `data.attributes.state-versions` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's state versions. Can only be used when `access` is `custom`. Valid values include `none`, `read-outputs`, `read`, or `write`. | +| `data.attributes.sentinel-mocks` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's Sentinel mocks. Can only be used when `access` is `custom`. Valid values include `none`, or `read`. | +| `data.attributes.workspace-locking` | boolean | false | If `access` is `custom`, the permission granting the ability to manually lock or unlock the workspace. Can only be used when `access` is `custom`. | +| `data.attributes.run-tasks` | boolean | false | If `access` is `custom`, this permission allows the team to manage run tasks within the workspace. | +| `data.relationships.workspace.data.type` | string | | Must be `workspaces`. | +| `data.relationships.workspace.data.id` | string | | The workspace ID to which the team is to be added. | +| `data.relationships.team.data.type` | string | | Must be `teams`. | +| `data.relationships.team.data.id` | string | | The ID of the team to add to the workspace. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "none", + "state-versions": "read-outputs", + "plan-outputs": "none", + "sentinel-mocks": "read", + "workspace-locking": false, + "run-tasks": false + }, + "relationships": { + "workspace": { + "data": { + "type": "workspaces", + "id": "ws-XGA52YVykdTgryTN" + } + }, + "team": { + "data": { + "type": "teams", + "id": "team-DBycxkdQrGFf5zEM" + } + } + }, + "type": "team-workspaces" + } +} +``` + +### 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/team-workspaces +``` + +### Sample Response + +```json +{ + "data": { + "id": "tws-sezDAcCYWLnd3xz2", + "type": "team-workspaces", + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "none", + "state-versions": "read-outputs", + "sentinel-mocks": "read", + "workspace-locking": false, + "run-tasks": false + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-sezDAcCYWLnd3xz2" + } + } +} +``` + +## Update Team Access to a Workspace + +`PATCH /team-workspaces/:id` + +| Status | Response | Reason | +| ------- | ------------------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-workspaces"`) | The request was successful | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | + +| Parameter | | | Description | +| ----------------------------------- | ------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | | | The ID of the team/workspace relationship. Obtain this from the [list team access action](#list-team-access-to-a-workspace) described above. | +| `data.attributes.access` | string | | The type of access to grant. Valid values are `read`, `plan`, `write`, `admin`, or `custom`. | +| `data.attributes.runs` | string | "read" | If `access` is `custom`, the permission to grant for the workspace's runs. Can only be used when `access` is `custom`. | +| `data.attributes.variables` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's variables. Can only be used when `access` is `custom`. | +| `data.attributes.state-versions` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's state versions. Can only be used when `access` is `custom`. | +| `data.attributes.sentinel-mocks` | string | "none" | If `access` is `custom`, the permission to grant for the workspace's Sentinel mocks. Can only be used when `access` is `custom`. | +| `data.attributes.workspace-locking` | boolean | false | If `access` is `custom`, the permission granting the ability to manually lock or unlock the workspace. Can only be used when `access` is `custom`. | +| `data.attributes.run-tasks` | boolean | false | If `access` is `custom`, this permission allows the team to manage run tasks within the workspace. | + +### 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/team-workspaces/tws-s68jV4FWCDwWvQq8 +``` + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "access": "custom", + "state-versions": "none" + } + } +} +``` + +### Sample Response + +```json +{ + "data": { + "id": "tws-s68jV4FWCDwWvQq8", + "type": "team-workspaces", + "attributes": { + "access": "custom", + "runs": "apply", + "variables": "write", + "state-versions": "none", + "sentinel-mocks": "read", + "workspace-locking": true, + "run-tasks": true + }, + "relationships": { + "team": { + "data": { + "id": "team-DBycxkdQrGFf5zEM", + "type": "teams" + }, + "links": { + "related": "/api/v2/teams/team-DBycxkdQrGFf5zEM" + } + }, + "workspace": { + "data": { + "id": "ws-XGA52YVykdTgryTN", + "type": "workspaces" + }, + "links": { + "related": "/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self": "/api/v2/team-workspaces/tws-s68jV4FWCDwWvQq8" + } + } +} +``` + +## Remove Team Access to a Workspace + +`DELETE /team-workspaces/:id` + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | | The Team Access was successfully destroyed | +| [404][] | [JSON API error object][] | Team Access not found or user unauthorized to perform action | + +| Parameter | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `:id` | The ID of the team/workspace relationship. Obtain this from the [list team access action](#list-team-access-to-a-workspace) described above. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/team-workspaces/tws-sezDAcCYWLnd3xz2 +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-members.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-members.mdx new file mode 100644 index 0000000000..310dfa6121 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-members.mdx @@ -0,0 +1,249 @@ +--- +page_title: /relationships API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/relationships` endpoints to add and + remove users from teams using an account or organization membership ID. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Team membership API reference + + + +-> **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). + + + +The Team Membership API is used to add or remove users from teams. The [Team API](/terraform/enterprise/api-docs/teams) is used to create or destroy teams. + +## Organization Membership + +-> **Note:** To add users to a team, they must first receive and accept the invitation to join the organization by email. This process ensures that you do not accidentally add the wrong person by mistyping a username. Refer to [the Organization Memberships API documentation](/terraform/enterprise/api-docs/organization-memberships) for more information. + +## Add a User to Team (With user ID) + +This method adds multiple users to a team using the user ID. Both users and teams must already exist. + +`POST /teams/:team_id/relationships/users` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------------------------ | +| `data[].type` | string | | Must be `"users"`. | +| `data[].id` | string | | The ID of the user you want to add to this team. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "users", + "id": "myuser1" + }, + { + "type": "users", + "id": "myuser2" + } + ] +} +``` + +### 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/257525/relationships/users +``` + +## Add a User to Team (With organization membership ID) + +This method adds multiple users to a team using the organization membership ID. Unlike the user ID method, the user only needs an invitation to the organization. + +`POST /teams/:team_id/relationships/organization-memberships` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------------------------------- | +| `data[].type` | string | | Must be `"organization-memberships"`. | +| `data[].id` | string | | The organization membership ID of the user to add. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "organization-memberships", + "id": "ou-nX7inDHhmC3quYgy" + }, + { + "type": "organization-memberships", + "id": "ou-tTJph1AQVK5ZmdND" + } + ] +} +``` + +### 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/257525/relationships/organization-memberships +``` + +## Delete a User from Team (With user ID) + +This method removes multiple users from a team using the user ID. Both users and teams must already exist. This method only removes a user from this team. It does not delete that user overall. + +`DELETE /teams/:team_id/relationships/users` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------------------------- | +| `data[].type` | string | | Must be `"users"`. | +| `data[].id` | string | | The ID of the user to remove from this team. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "users", + "id": "myuser1" + }, + { + "type": "users", + "id": "myuser2" + } + ] +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/257525/relationships/users +``` + +## Delete a User from Team (With organization membership ID) + +This method removes multiple users from a team using the organization membership ID. This method only removes a user from this team. It does not delete that user overall. + +`DELETE /teams/:team_id/relationships/organization-memberships` + +| Parameter | Description | +| ---------- | ------------------- | +| `:team_id` | The ID of the team. | + +### Request Body + +This DELETE endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------- | +| `data[].type` | string | | Must be `"organization-memberships"`. | +| `data[].id` | string | | The organization membership ID of the user to remove. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "organization-memberships", + "id": "ou-nX7inDHhmC3quYgy" + }, + { + "type": "organization-memberships", + "id": "ou-tTJph1AQVK5ZmdND" + } + ] +} +``` + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/teams/257525/relationships/organization-memberships +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-tokens.mdx new file mode 100644 index 0000000000..9db2a1196a --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/team-tokens.mdx @@ -0,0 +1,558 @@ +--- +page_title: '/teams/:team_id/authentication-tokens API reference for Terraform Enterprise' +description: >- + 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 +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Team tokens API reference + +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 + +Generates a new team token and overrides existing token if one exists. + +| Method | Path | +| :----- | :----------------------------------- | +| POST | /teams/:team_id/authentication-token | + +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 + +- `: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-token"`. | +| `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-token", + "attributes": { + "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-token +``` + +### Sample response + +```json +{ + "data": { + "id": "4111797", + "type": "authentication-tokens", + "attributes": { + "created-at": "2017-11-29T19:18:09.976Z", + "last-used-at": null, + "description": null, + "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 the team token + +| Method | Path | +| :----- | :----------------------------------- | +| DELETE | /teams/:team_id/authentication-token | + +### Parameters + +- `:team_id` (`string: `) - specifies the team_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/teams/team-BUHBEM97xboT8TVz/authentication-token +``` + +## List team tokens + +Lists the [team tokens](/terraform/enterprise/users-teams-organizations/teams#api-tokens) in an organization. + +`GET organizations/:organization_name/team-tokens` + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------- | +| `:organization_name` | The name 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. + +By default, this endpoint returns tokens by ascending expiration date. + +| Status | Response | Reason | +| ------- | --------------------------------------------- | ---------------------------------------------- | +| [200][] | [JSON API document][] (`type: "team-tokens"`) | The request was successful. | +| [200][] | Empty [JSON API document][] | The specified organization has no team tokens. | +| [404][] | [JSON API error object][] | Organization 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 `"team-name"`, `"created-by"`, `"expired-at"`, and `"last-used-at"`. Prepending a hyphen to the sort parameter reverses the order. For example, `"-team-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order ascending. | + +### Sample response + +```json +{ + "data": [ + { + "id": "at-TLhN8cc6ro6qYDvp", + "type": "authentication-tokens", + "attributes": { + "created-at": "2024-06-19T18:28:25.267Z", + "last-used-at": null, + "description": null, + "token": null, + "expired-at": "2024-07-19T18:28:25.030Z" + }, + "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": null, + "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 [team token](/terraform/enterprise/users-teams-organizations/teams#api-tokens) for a particular team. + +`GET /teams/:team_id/authentication-token` + +| Parameter | Description | +| ---------- | ------------------- | +| `: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` + +| 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 text 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/teams/team-6yEmxNAhaoQLH1Da/authentication-token +``` + +### Sample response + +```json +{ + "data": { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2023-11-25T22:31:30.624Z", + "last-used-at": "2023-11-26T20:34:59.487Z", + "description": null, + "token": null, + "expired-at": "2024-04-06T12:00:00.000Z" + }, + "relationships": { + "team": { + "data": { + "id": "team-LnREdjodkvZFGdXL", + "type": "teams" + } + }, + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/teams.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/teams.mdx new file mode 100644 index 0000000000..1f96792b02 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/teams.mdx @@ -0,0 +1,466 @@ +--- +page_title: /teams API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/teams` endpoint to read, create, update, + and delete teams. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Teams API reference + +The Teams API is used to create, edit, and destroy teams as well as manage a team's organization-level permissions. The [Team Membership API](/terraform/enterprise/api-docs/team-members) is used to add or remove users from a team. Use the [Team Access API](/terraform/enterprise/api-docs/team-access) to associate a team with privileges on an individual workspace. + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +Any member of an organization can view visible teams and any secret teams they are a member of. Only organization owners can modify teams or view the full set of secret teams. The organization token and the owners team token can act as an owner on these endpoints. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Organization Membership + +-> **Note:** Users must be invited to join organizations before they can be added to teams. See [the Organization Memberships API documentation](/terraform/enterprise/api-docs/organization-memberships) for more information. Invited users who have not yet accepted will not appear in Teams API responses. + +## List teams + +`GET organizations/:organization_name/teams` + +| Parameter | Description | +| -------------------- | ------------------------------------------------ | +| `:organization_name` | The name of the organization to list teams from. | + +The response may identify HashiCorp API service accounts, for example `api-team_XXXXXX`, as a members of a team. However, API service accounts do not appear in the UI. As a result, there may be differences between the number of team members reported by the UI and the API. For example, the UI may report `0` members on a team when and the API reports `1`. + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `q` | **Optional.** Allows querying a list of teams by name. This search is case-insensitive. | +| `filter[names]` | **Optional.** If specified, restricts results to a team with a matching name. If multiple comma separated values are specified, teams matching any of the names are returned. | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 teams per page. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/organizations/my-organization/teams +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. +The `allow-member-token-management` attribute is set to `false` for Terraform Enterprise versions older than 202408-1. + +```json +{ + "data": [ + { + "id": "team-6p5jTwJQXwqZBncC", + "type": "teams", + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "users-count": 0, + "visibility": "organization", + "allow-member-token-management": true, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "organization-access": { + "manage-policies": true, + "manage-policy-overrides": false, + "manage-run-tasks": true, + "manage-workspaces": false, + "manage-vcs-settings": false, + "manage-agent-pools": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": false + } + }, + "relationships": { + "users": { + "data": [] + }, + "authentication-token": { + "meta": {} + } + }, + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + } + } + ] +} +``` + +## Create a Team + +`POST /organizations/:organization_name/teams` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization to create the team in. The organization must already exist in the system, and the user must have permissions to create new teams. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "teams"`) | Successfully created a team | +| [400][] | [JSON API error object][] | Invalid `include` parameter | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during team creation | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +-> **Note:** You cannot set `manage-workspaces` to `false` when setting `manage-projects` to `true`, since project permissions cascade down to workspaces. This is also the case for `read-workspaces` and `read-projects`. If `read-projects` is `true`, `read-workspaces` must be `true` as well. + +| Key path | Type | Default | Description | +| ------------------------------------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"teams"`. | +| `data.attributes.name` | string | | The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.sso-team-id` | string | (nothing) | The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or in HCP Terraform. | +| `data.attributes.organization-access` | object | (nothing) | Settings for the team's organization access. This object can include the `manage-policies`, `manage-policy-overrides`, `manage-run-tasks`, `manage-workspaces`, `manage-vcs-settings`, `manage-agent-pools`, `manage-providers`, `manage-modules`, `manage-projects`, `read-projects`, `read-workspaces`, `manage-membership`, `manage-teams`, and `manage-organization-access` properties with boolean values. All properties default to `false`. | +| `data.attributes.visibility` | string | `"secret"` | The team's visibility. Must be `"secret"` or `"organization"` (visible). | + +### Sample Payload + +```json +{ + "data": { + "type": "teams", + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "organization-access": { + "manage-workspaces": true + } + } + } +} +``` + +### 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/organizations/my-organization/teams +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. + +```json +{ + "data": { + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "organization-access": { + "manage-policies": false, + "manage-policy-overrides": false, + "manage-run-tasks": false, + "manage-vcs-settings": false, + "manage-agent-pools": false, + "manage-workspaces": true, + "manage-providers": false, + "manage-modules": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": true, + "manage-membership": false, + "manage-teams": false, + "manage-organization-access": false + }, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "users-count": 0, + "visibility": "secret", + "allow-member-token-management": true + }, + "id": "team-6p5jTwJQXwqZBncC", + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + }, + "relationships": { + "authentication-token": { + "meta": {} + }, + "users": { + "data": [] + } + }, + "type": "teams" + } +} +``` + +## Show Team Information + +`GET /teams/:team_id` + +| Parameter | Description | +| ---------- | ------------------------ | +| `:team_id` | The team ID to be shown. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. + +```json +{ + "data": { + "id": "team-6p5jTwJQXwqZBncC", + "type": "teams", + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "users-count": 0, + "visibility": "organization", + "allow-member-token-management": true, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "organization-access": { + "manage-policies": true, + "manage-policy-overrides": false, + "manage-run-tasks": true, + "manage-workspaces": false, + "manage-vcs-settings": false, + "manage-agent-pools": false, + "manage-providers": false, + "manage-modules": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": false, + "manage-membership": false, + "manage-teams": false, + "manage-organization-access": false + } + }, + "relationships": { + "users": { + "data": [] + }, + "authentication-token": { + "meta": {} + } + }, + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + } + } +} +``` + +## Update a Team + +`PATCH /teams/:team_id` + +| Parameter | Description | +| ---------- | -------------------------- | +| `:team_id` | The team ID to be updated. | + +| Status | Response | Reason | +| ------- | --------------------------------------- | -------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "teams"`) | Successfully created a team | +| [400][] | [JSON API error object][] | Invalid `include` parameter | +| [404][] | [JSON API error object][] | Team not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during team creation | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +-> **Note:** You cannot set `manage-workspaces` to `false` when setting `manage-projects` to `true`, since project permissions cascade down to workspaces. This is also the case for `read-workspaces` and `read-projects`. If `read-projects` is `true`, `read-workspaces` must be `true` as well. + +| Key path | Type | Default | Description | +| --------------------------------------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"teams"`. | +| `data.attributes.name` | string | (previous value) | The name of the team, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. | +| `data.attributes.sso-team-id` | string | (previous value) | The unique identifier of the team from the SAML `MemberOf` attribute. Only available in Terraform Enterprise 202204-1 and later, or in HCP Terraform. | +| `data.attributes.organization-access` | object | (previous value) | Settings for the team's organization access. This object can include the `manage-policies`, `manage-policy-overrides`, `manage-run-tasks`, `manage-workspaces`, `manage-vcs-settings`, `manage-agent-pools`, `manage-providers`, `manage-modules`, `manage-projects`, `read-projects`, `read-workspaces`, `manage-membership`, `manage-teams`, and `manage-organization-access` properties with boolean values. All properties default to `false`. | +| `data.attributes.visibility` | string | (previous value) | The team's visibility. Must be `"secret"` or `"organization"` (visible). | +| `data.attributes.allow-team-token-management` | boolean | (previous value) | The ability to enable and disable team token management for a team. Defaults to true. | + +### Sample Payload + +```json +{ + "data": { + "type": "teams", + "attributes": { + "visibility": "organization", + "allow-member-token-management": true, + "organization-access": { + "manage-vcs-settings": true + } + } + } +} +``` + +### 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/teams/team-6p5jTwJQXwqZBncC +``` + +### Sample Response + +The `sso-team-id` attribute is only returned in Terraform Enterprise 202204-1 and later, or in HCP Terraform. + +```json +{ + "data": { + "attributes": { + "name": "team-creation-test", + "sso-team-id": "cb265c8e41bddf3f9926b2cf3d190f0e1627daa4", + "organization-access": { + "manage-policies": false, + "manage-policy-overrides": false, + "manage-run-tasks": true, + "manage-vcs-settings": true, + "manage-agent-pools": false, + "manage-workspaces": true, + "manage-providers": false, + "manage-modules": false, + "manage-projects": false, + "read-projects": false, + "read-workspaces": true, + "manage-membership": false, + "manage-teams": false, + "manage-organization-access": false + }, + "visibility": "organization", + "allow-member-token-management": true, + "permissions": { + "can-update-membership": true, + "can-destroy": true, + "can-update-organization-access": true, + "can-update-api-token": true, + "can-update-visibility": true + }, + "users-count": 0 + }, + "id": "team-6p5jTwJQXwqZBncC", + "links": { + "self": "/api/v2/teams/team-6p5jTwJQXwqZBncC" + }, + "relationships": { + "authentication-token": { + "meta": {} + }, + "users": { + "data": [] + } + }, + "type": "teams" + } +} +``` + +## Delete a Team + +`DELETE /teams/:team_id` + +| Parameter | Description | +| ---------- | -------------------------- | +| `:team_id` | The team ID to be deleted. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC +``` + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `users` (`string`) - Returns the full user record for every member of a team. +- `organization-memberships` (`string`) - Returns the full organization membership record for every member of a team. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/user-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/user-tokens.mdx new file mode 100644 index 0000000000..a26352ea06 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/user-tokens.mdx @@ -0,0 +1,286 @@ +--- +page_title: /users/authentication-tokens API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/users/authentication-tokens` endpoint to + read, create, and destroy user-specific API tokens. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# User tokens API reference + +## List User Tokens + +`GET /users/:user_id/authentication-tokens` + +| Parameter | Description | +| ---------- | ------------------- | +| `:user_id` | The ID of the User. | + +Use the [Account API](/terraform/enterprise/api-docs/account) to find your own user ID. + +The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later. + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only return useful data for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [200][] | Empty [JSON API document][] (no type) | User has no authentication tokens, or request was made by someone other than the user | +| [404][] | [JSON API error object][] | User not found | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. + +| Parameter | Description | +| -------------- | --------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 user tokens per page. | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/users/user-MA4GL63FmYRpSFxa/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "at-QmATJea6aWj1xR2t", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-06T22:56:10.203Z", + "last-used-at": null, + "description": null, + "token": null, + "expired-at": null + }, + "relationships": { + "created-by": { + "data": null + } + } + }, + { + "id": "at-6yEmxNAhaoQLH1Da", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-25T22:31:30.624Z", + "last-used-at": "2018-11-26T20:27:54.931Z", + "description": "api", + "token": null, + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } + ] +} +``` + +## Show a User Token + +`GET /authentication-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------- | +| `:id` | The ID of the User Token. | + +The objects returned by this endpoint only contain metadata, and do not include the secret text of any authentication tokens. A token is only shown upon creation, and cannot be recovered later. + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only return useful data for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | ------------------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | User Token not found, or unauthorized to view the User 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": "2018-11-25T22:31:30.624Z", + "last-used-at": "2018-11-26T20:34:59.487Z", + "description": "api", + "token": null, + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +## Create a User Token + +`POST /users/:user_id/authentication-tokens` + +| Parameter | Description | +| ---------- | ------------------- | +| `:user_id` | The ID of the User. | + +Use the [Account API](/terraform/enterprise/api-docs/account) to find your own user ID. + +This endpoint returns the secret text of the created authentication token. A token is only shown upon creation, and cannot be recovered later. + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only create new tokens for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------------------------------------- | -------------------------------------------------------------- | +| [201][] | [JSON API document][] (`type: "authentication-tokens"`) | The request was successful | +| [404][] | [JSON API error object][] | User not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Malformed request body (missing attributes, wrong types, etc.) | +| [500][] | [JSON API error object][] | Failure during User Token creation | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"authentication-tokens"`. | +| `data.attributes.description` | string | | The description for the User Token. | +| `data.attributes.expired-at` | string | `null` | The UTC date and time that the User 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":"api", + "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/users/user-MA4GL63FmYRpSFxa/authentication-tokens +``` + +### Sample Response + +```json +{ + "data": { + "id": "at-MKD1X3i4HS3AuD41", + "type": "authentication-tokens", + "attributes": { + "created-at": "2018-11-26T20:48:35.054Z", + "last-used-at": null, + "description": "api", + "token": "6tL24nM38M7XWQ.atlasv1.KmWckRfzeNmUVFNvpvwUEChKaLGznCSD6fPf3VPzqMMVzmSxFU0p2Ibzpo2h5eTGwPU", + "expired-at": "2023-04-06T12:00:00.000Z" + }, + "relationships": { + "created-by": { + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users" + } + } + } + } +} +``` + +## Destroy a User Token + +`DELETE /authentication-tokens/:id` + +| Parameter | Description | +| --------- | ------------------------------------ | +| `:id` | The ID of the User Token to destroy. | + +-> **Note:** You must access this endpoint with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens), and it will only delete tokens for that token's user account. + +| Status | Response | Reason | +| ------- | ------------------------- | ------------------------------------------------------------ | +| [204][] | Empty response | The User Token was successfully destroyed | +| [404][] | [JSON API error object][] | User Token not found, or user unauthorized to perform action | + +### 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 +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/users.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/users.mdx new file mode 100644 index 0000000000..4c8625e8c7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/users.mdx @@ -0,0 +1,102 @@ +--- +page_title: /users API reference for Terraform Enterprise +description: Use the Terraform Enterprise API's `/users` endpoint to read a user's details. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Users API reference + +HCP Terraform's user objects do not contain any identifying information about a user, other than their HCP Terraform username and avatar image; they are intended for displaying names and avatars in contexts that refer to a user by ID, like lists of team members or the details of a run. Most of these contexts can already include user objects via an `?include` parameter, so you shouldn't usually need to make a separate call to this endpoint. + +## Show a User + +Shows details for a given user. + +`GET /users/:user_id` + +| Parameter | Description | +| ---------- | --------------------------- | +| `:user_id` | The ID of the desired user. | + +To find the ID that corresponds to a given username, you can request a [team object](/terraform/enterprise/api-docs/teams) for a team that user belongs to, specify `?include=users` in the request, and look for the user's name in the included list of user objects. + +| Status | Response | Reason | +| ------- | --------------------------------------- | ------------------------------------------------ | +| [200][] | [JSON API document][] (`type: "users"`) | The request was successful | +| [401][] | [JSON API error object][] | Unauthorized | +| [404][] | [JSON API error object][] | User not found, or unauthorized to view the user | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/users/user-MA4GL63FmYRpSFxa +``` + +### Sample Response + +```json +{ + "data": { + "id": "user-MA4GL63FmYRpSFxa", + "type": "users", + "attributes": { + "username": "admin", + "is-service-account": false, + "auth-method": "hcp_sso", + "avatar-url": "https://www.gravatar.com/avatar/fa1f0c9364253d351bf1c7f5c534cd40?s=100&d=mm", + "v2-only": true, + "permissions": { + "can-create-organizations": false, + "can-change-email": true, + "can-change-username": true + } + }, + "relationships": { + "authentication-tokens": { + "links": { + "related": "/api/v2/users/user-MA4GL63FmYRpSFxa/authentication-tokens" + } + } + }, + "links": { + "self": "/api/v2/users/user-MA4GL63FmYRpSFxa" + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/variable-sets.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/variable-sets.mdx new file mode 100644 index 0000000000..8bca544f1a --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/variable-sets.mdx @@ -0,0 +1,1018 @@ +--- +page_title: /varsets API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/varsets` endpoint to read, create, + update, and delete variable sets, and apply or remove variable sets from + workspaces and projects. +source: terraform-docs-common +--- + +# Variable sets API reference + +A [variable set](/terraform/enterprise/workspaces/variables#scope) is a resource that allows you to reuse the same variables across multiple workspaces and projects. For example, you could define a variable set of provider credentials and automatically apply it to a selection of workspaces, all workspaces in a project, or all workspaces in an organization. + +Projects and organizations can both own variable sets. The owner of a variable set can determine the precedence of that set. Refer to [**Manage variable sets**](/terraform/enterprise/workspaces/variables/managing-variables#permissions) for more details on variable set permissions. + +To view the variables applied from a variable set on a particular workspace, you must have [**Read** variables permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) on that workspace. + +## Create a Variable Set + +`POST organizations/:organization_name/varsets` + +| Parameter | Description | +| -------------------- | --------------------------------------------------------- | +| `:organization_name` | The name of the organization the variable set belongs to. | + +### Request Body + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------- | ------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.name` | string | | The name of the variable set. | +| `data.attributes.description` | string | `""` | Text displayed in the UI to contextualize the variable set and its purpose. | +| `data.attributes.global` | boolean | `false` | When true, HCP Terraform automatically applies the variable set to all current and future workspaces in the organization. | +| `data.attributes.priority` | boolean | `false` | When true, the variables in the set override any other variable values with a more specific scope, including values set on the command line. | +| `data.relationships.workspaces` | array | `[]` | Array of references to workspaces that the variable set should be assigned to. | +| `data.relationships.projects` | array | `[]` | Array of references to projects that the variable set should be assigned to. | +| `data.relationships.vars` | array | `[]` | Array of complete variable definitions that comprise the variable set. | +| `data.relationships.parent` | object | Organization that the variable set belongs to | The parent that owns this variable set. If the parent is a project, `data.attributes.global` must be `false`. | +| `data.relationships.parent.data.type` | string | `"organizations"` | The resource type of the parent that owns this variable set. Valid values are `organizations` or `projects`. | +| `data.relationships.parent.data.id` | string | Name of organization that the variable set belongs to. | The ID of the parent that owns the variable set. For organizations, use name instead of ID. | + +HCP Terraform does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to create a global variable set that contains conflicting variables. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully added variable set | +| [404][] | [JSON API error object][] | Organization not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + }, + "relationships": { + "workspaces": { + "data": [ + { + "id": "ws-z6YvbWEYoE168kpq", + "type": "workspaces" + } + ] + }, + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + }, + "parent": { + "data": { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + } + } + } +} +``` + +### 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/organizations/my-organization/varsets +``` + +### Sample Response + +```json +{ + "data": { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + }, + "relationships": { + "workspaces": { + "data": [ + { + "id": "ws-z6YvbWEYoE168kpq", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + ] + }, + "vars": { + "data": [ + { + "id": "var-Nh0doz0hzj9hrm34qq", + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + }, + "parent": { + "data": { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + } + } + } +} +``` + +## Update a Variable Set + +`PUT/PATCH varsets/:varset_id` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +HCP Terraform does not allow global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to create a global variable set that contains conflicting variables. + +HCP Terraform does not allow you to change the parent organization or project of a variable set. Instead, you must delete the variable set and recreate it in the desired organization or project. + +### Request Body + +| Key path | Type | Default | Description | +| ------------------------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.attributes.name` | string | | The name of the variable set. | +| `data.attributes.description` | string | | Text displayed in the UI to contextualize the variable set and its purpose. | +| `data.attributes.global` | boolean | | When true, HCP Terraform automatically applies the variable set to all current and future workspaces in the organization. | +| `data.attributes.priority` | boolean | `false` | When true, the variables in the set override any other variable values set with a more specific scope, including values set on the command line. | +| `data.relationships.workspaces` | array | | **Optional** Array of references to workspaces that the variable set should be assigned to. Sending an empty array clears all workspace assignments. | +| `data.relationships.projects` | array | | **Optional** Array of references to projects that the variable set should be assigned to. Sending an empty array clears all project assignments. | +| `data.relationships.vars` | array | | **Optional** Array of complete variable definitions to add to the variable set. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ------------------------------------------------------------------------------ | +| [200][] | [JSON API document][] | Successfully updated variable set | +| [404][] | [JSON API error object][] | Organization or variable set not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse. Now global!", + "global": true, + "priority": true, + }, + "relationships": { + "workspaces": { + "data": [ + { + "id": "ws-FRFwkYoUoGn1e34b", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + ] + }, + "vars": { + "data": [ + { + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + } + } + } +} +``` + +### 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/varsets/varset-kjkN545LH2Sfercv +``` + +### Sample Response + +```json +{ + "data": { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse. Now global!", + "global": true, + "priority": true + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "workspaces": { + "data": [ + { + "id": "ws-FRFwkYoUoGn1e34b", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-kFjgSzcZSr5c3imE", + "type": "projects" + } + ] + }, + "vars": { + "data": [ + { + "id": "var-Nh0doz0hzj9hrm34qq", + "type": "vars", + "attributes": { + "key": "c2e4612d993c18e42ef30405ea7d0e9ae", + "value": "8676328808c5bf56ac5c8c0def3b7071", + "category": "terraform" + } + } + ] + }, + "parent": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## Delete a Variable Set + +`DELETE varsets/:varset_id` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv +``` + +On success, this endpoint responds with no content. + +## Show Variable Set + +Fetch details about the specified variable set. + +`GET varsets/:varset_id` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request GET \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv +``` + +### Sample Response + +```json +{ + "data": { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + "updated-at": "2023-03-06T21:48:33.588Z", + "var-count": 5, + "workspace-count": 2, + "project-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "vars": { + "data": [ + { + "id": "var-mMqadSCxZtrQJAv8", + "type": "vars" + }, + { + "id": "var-hFxUUKSk35QMsRVH", + "type": "vars" + }, + { + "id": "var-fkd6N48tXRmoaPxH", + "type": "vars" + }, + { + "id": "var-abcbBMBMWcZw3WiV", + "type": "vars" + }, + { + "id": "var-vqvRKK1ZoqQCiMwN", + "type": "vars" + } + ] + }, + "workspaces": { + "data": [ + { + "id": "ws-UohFdKAHUGsQ8Dtf", + "type": "workspaces" + }, + { + "id": "ws-XhGhaaCrsx9ATson", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-1JMwvPHFsdpsPhnt", + "type": "projects" + }, + { + "id": "prj-SLDGqbYqELXE1obp", + "type": "projects" + } + ] + }, + "parent": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } +} +``` + +## List Variable Sets + +List all variable sets for an organization. + +`GET organizations/:organization_name/varsets` + +| Parameter | Description | +| -------------------- | -------------------------------------------------------- | +| `:organization_name` | The name of the organization the variable sets belong to | + +List all variable sets for a project. This includes global variable sets from the project's organization. + +`GET projects/:project_id/varsets` + +| Parameter | Description | +| ------------- | -------------- | +| `:project_id` | The project ID | + +List all variable sets for a workspace. This includes global variable sets from the workspace's organization and variable sets +attached to the project this workspace is contained within. + +`GET workspaces/:workspace_id/varsets` + +| Parameter | Description | +| --------------- | ---------------- | +| `:workspace_id` | The workspace ID | + +### Query Parameters + +All list endpoints support 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 varsets per page. | +| `q` | **Optional.** A search query string. You can search for a variable set using its name. | + +### Sample Response + +```json +{ + "data": [ + { + "id": "varset-kjkN545LH2Sfercv", + "type": "varsets", + "attributes": { + "name": "MyVarset", + "description": "Full of vars and such for mass reuse", + "global": false, + "priority": false, + "updated-at": "2023-03-06T21:48:33.588Z", + "var-count": 5, + "workspace-count": 2, + "project-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + }, + "vars": { + "data": [ + { + "id": "var-mMqadSCxZtrQJAv8", + "type": "vars" + }, + { + "id": "var-hFxUUKSk35QMsRVH", + "type": "vars" + }, + { + "id": "var-fkd6N48tXRmoaPxH", + "type": "vars" + }, + { + "id": "var-abcbBMBMWcZw3WiV", + "type": "vars" + }, + { + "id": "var-vqvRKK1ZoqQCiMwN", + "type": "vars" + } + ] + }, + "workspaces": { + "data": [ + { + "id": "ws-UohFdKAHUGsQ8Dtf", + "type": "workspaces" + }, + { + "id": "ws-XhGhaaCrsx9ATson", + "type": "workspaces" + } + ] + }, + "projects": { + "data": [ + { + "id": "prj-1JMwvPHFsdpsPhnt", + "type": "projects" + }, + { + "id": "prj-SLDGqbYqELXE1obp", + "type": "projects" + } + ] + }, + "parent": { + "data": { + "id": "hashicorp", + "type": "organizations" + } + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/hashicorp/varsets?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/hashicorp/varsets?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/hashicorp/varsets?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 + } + } +} +``` + +### Variable Relationships + +## Add Variable + +`POST varsets/:varset_external_id/relationships/vars` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | | The description of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true, variable is not visible in the UI. | + +HCP Terraform does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to add a conflicting variable to a global variable set. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully added variable to variable set | +| [404][] | [JSON API error object][] | Variable set not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +### 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/varsets/varset-4q8f7H0NHG733bBH/relationships/vars +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +## Update a Variable in a Variable Set + +`PATCH varsets/:varset_id/relationships/vars/:var_id` + +| Parameter | Description | +| ------------ | -------------------------------- | +| `:varset_id` | The variable set ID | +| `:var_id` | The ID of the variable to delete | + +HCP Terraform does not allow different global variable sets to contain conflicting variables with the same name and type. You will receive a 422 response if you try to add a conflicting variable to a global variable set. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [200][] | [JSON API document][] | Successfully updated variable for variable set | +| [404][] | [JSON API error object][] | Variable set not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": { + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "new cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +### 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/varsets/varset-4q8f7H0NHG733bBH/relationships/vars/var-EavQ1LztoRTQHSNT +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type": "vars", + "attributes": { + "key": "g6e45ae7564a17e81ef62fd1c7fa86138", + "value": "61e400d5ccffb3782f215344481e6c82", + "description": "new cheeeese", + "sensitive": false, + "category": "terraform", + "hcl": false + } + } +} +``` + +## Delete a Variable in a Variable Set + +`DELETE varsets/:varset_id/relationships/vars/:var_id` + +| Parameter | Description | +| ------------ | -------------------------------- | +| `:varset_id` | The variable set ID | +| `:var_id` | The ID of the variable to delete | + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/varsets/varset-4q8f7H0NHG733bBH/relationships/vars/var-EavQ1LztoRTQHSNT +``` + +On success, this endpoint responds with no content. + +## List Variables in a Variable Set + +`GET varsets/:varset_id/relationships/vars` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +### Sample Response + +```json +{ + "data": [ + { + "id": "var-134r1k34nj5kjn", + "type": "vars", + "attributes": { + "key": "F115037558b045dd82da40b089e5db745", + "value": "1754288480dfd3060e2c37890422905f", + "sensitive": false, + "category": "terraform", + "hcl": false, + "created-at": "2021-10-29T18:54:29.379Z", + "description": "" + }, + "relationships": { + "varset": { + "data": { + "id": "varset-992UMULdeDuebi1x", + "type": "varsets" + }, + "links": { "related": "/api/v2/varsets/1" } + } + }, + "links": { "self": "/api/v2/vars/var-BEPU9NjPVCiCfrXj" } + } + ], + "links": { + "self": "app.terraform.io/app/varsets/varset-992UMULdeDuebi1x/vars", + "first": "app.terraform.io/app/varsets/varset-992UMULdeDuebi1x/vars?page=1", + "prev": null, + "next": null, + "last": "app.terraform.io/app/varsets/varset-992UMULdeDuebi1x/vars?page=1" + } +} +``` + +## Apply Variable Set to Workspaces + +Accepts a list of workspaces to add the variable set to. + +`POST varsets/:varset_id/relationships/workspaces` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | -------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"` | +| `data[].id` | string | | The id of the workspace to add the variable set to | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully added variable set to the requested workspaces | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-YwfuBJZkdai4xj9w" + } + ] +} +``` + +### 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/varsets/varset-kjkN545LH2Sfercv/relationships/workspaces +``` + +## Remove a Variable Set from Workspaces + +Accepts a list of workspaces to remove the variable set from. + +`DELETE varsets/:varset_id/relationships/workspaces` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"` | +| `data[].id` | string | | The id of the workspace to delete the variable set from | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully removed variable set from the requested workspaces | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "workspaces", + "id": "ws-YwfuBJZkdai4xj9w" + }, + { + "type": "workspaces", + "id": "ws-YwfuBJZkdai4xj9w" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv/relationships/workspaces +``` + +## Apply Variable Set to Projects + +Accepts a list of projects to add the variable set to. When you apply a variable set to a project, all the workspaces in that project will have the variable set applied to them. + +`POST varsets/:varset_id/relationships/projects` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ------------------------------------------------ | +| `data[].type` | string | | Must be `"projects"` | +| `data[].id` | string | | The id of the project to add the variable set to | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully added variable set to the requested projects | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "projects", + "id": "prj-YwfuBJZkdai4xj9w" + } + ] +} +``` + +### 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/varsets/varset-kjkN545LH2Sfercv/relationships/projects +``` + +## Remove a Variable Set from Projects + +Accepts a list of projects to remove the variable set from. + +`DELETE varsets/:varset_id/relationships/projects` + +| Parameter | Description | +| ------------ | ------------------- | +| `:varset_id` | The variable set ID | + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------- | +| `data[].type` | string | | Must be `"projects"` | +| `data[].id` | string | | The id of the project to delete the variable set from | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | | Successfully removed variable set from the requested projects | +| [404][] | [JSON API error object][] | Variable set not found or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "projects", + "id": "prj-YwfuBJZkdai4xj9w" + }, + { + "type": "projects", + "id": "prj-lkjasdfiojwerlkj" + } + ] +} +``` + +### Sample Request + +```shell +curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/varsets/varset-kjkN545LH2Sfercv/relationships/projects +``` + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[json api document]: /terraform/enterprise/api-docs#json-api-documents + +[json api error object]: https://jsonapi.org/format/#error-objects + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +| Resource Name | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `vars` | Show each variable in a variable set and all of their attributes including `id`, `key`, `value`, `sensitive`, `category`, `hcl`, `created_at`, and `description`. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/variables.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/variables.mdx new file mode 100644 index 0000000000..987dca3556 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/variables.mdx @@ -0,0 +1,307 @@ +--- +page_title: /vars API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/vars` endpoint to manage + organization-level variables. Learn how to read, create, update, and delete + variables using the API. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Variables API reference + +~> **Important**: The Variables API is **deprecated** and will be removed in a future release. All existing integrations with this API should transition to the [Workspace Variables API](/terraform/enterprise/api-docs/workspace-variables). + +This set of APIs covers create, update, list and delete operations on variables. + +## Create a Variable + +`POST /vars` + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ---------------------------------------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | | The description of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. | +| `data.relationships.workspace.data.type` | string | | Must be `"workspaces"`. | +| `data.relationships.workspace.data.id` | string | | The ID of the workspace that owns the variable. Obtain workspace IDs from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +**Deprecation warning**: The custom `filter` properties are replaced by JSON API `relationships` and will be removed from future versions of the API! + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | ----------------------------------------------------- | +| `filter.workspace.name` | string | | The name of the workspace that owns the variable. | +| `filter.organization.name` | string | | The name of the organization that owns the workspace. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "category":"terraform", + "hcl":false, + "sensitive":false + }, + "relationships": { + "workspace": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + } + } + } + } +} +``` + +### 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/vars +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/vars/var-EavQ1LztoRTQHSNT" + } + } +} +``` + +## List Variables + +`GET /vars` + +### Query Parameters + +[These are standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. + +| Parameter | Description | +| ---------------------------- | -------------------------------------------------------------------------- | +| `filter[workspace][name]` | **Required** The name of one workspace to list variables for. | +| `filter[organization][name]` | **Required** The name of the organization that owns the desired workspace. | + +These two parameters are optional but linked; if you include one, you must include both. Without a filter, this method lists variables for all workspaces where you have permission to read variables. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ +"https://app.terraform.io/api/v2/vars?filter%5Borganization%5D%5Bname%5D=my-organization&filter%5Bworkspace%5D%5Bname%5D=my-workspace" +# ?filter[organization][name]=my-organization&filter[workspace][name]=demo01 +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"var-AD4pibb9nxo1468E", + "type":"vars","attributes": { + "key":"name", + "value":"hello", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-cZE9LERN3rGPRAmH", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/vars/var-AD4pibb9nxo1468E" + } + } + ] +} +``` + +## Update Variables + +`PATCH /vars/:variable_id` + +| Parameter | Description | +| -------------- | ------------------------------------- | +| `:variable_id` | The ID of the variable to be updated. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.id` | string | | The ID of the variable to update. | +| `data.attributes` | object | | New attributes for the variable. This object can include `key`, `value`, `description`, `category`, `hcl`, and `sensitive` properties, which are described above under [create a variable](#create-a-variable). All of these properties are optional; if omitted, a property will be left unchanged. | + +### Sample Payload + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "attributes": { + "key":"name", + "value":"mars", + "description": "new description", + "category":"terraform", + "hcl": false, + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/vars/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "description":"new description", + "sensitive":false, + "category":"terraform", + "hcl":false + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/workspace-v2-06/workspaces/workspace-v2-06" + } + } + }, + "links": { + "self":"/api/v2/vars/var-yRmifb4PJj7cLkMG" + } + } +} +``` + +## Delete Variables + +`DELETE /vars/:variable_id` + +| Parameter | Description | +| -------------- | ------------------------------------- | +| `:variable_id` | The ID of the variable to be deleted. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/vars/var-yRmifb4PJj7cLkMG +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/vcs-events.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/vcs-events.mdx new file mode 100644 index 0000000000..7c97d1181d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/vcs-events.mdx @@ -0,0 +1,132 @@ +--- +page_title: /vcs-events API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/vcs-events` endpoint to list VCS-related + events within your organization. +source: terraform-docs-common +--- + +# VCS events API reference + +-> **Note**: The VCS Events API 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 (version control system) events describe changes within your organization for VCS-related actions. Events are only stored for 10 days. If information about the [OAuth Client](/terraform/enterprise/api-docs/oauth-clients) or [OAuth Token](/terraform/enterprise/api-docs/oauth-tokens) are available at the time of the event, it will be logged with the event. + +## List VCS events + +This endpoint lists VCS events for an organization + +`GET /organizations/:organization_name/vcs-events` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to list VCS events from. The organization must already exist in the system and the user must have permissions to manage VCS settings. | + +-> **Note:** Viewing VCS events is restricted to the owners team, teams with the "Manage VCS Settings", and the [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens). ([More about permissions](/terraform/enterprise/users-teams-organizations/permissions).) + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | +| `filter[from]` | **Optional.** Must be RFC3339 formatted and in UTC. If omitted, the endpoint will default to 10 days ago. | +| `filter[to]` | **Optional.** Must be RFC3339 formatted and in UTC. If omitted, the endpoint will default to now. | +| `filter[oauth_client_external_ids]` | **Optional.** Format as a comma-separated string. If omitted, the endpoint will return all events. | +| `filter[levels]` | **Optional.** `info` and `error` are the only accepted values. If omitted, the endpoint will return both info and error events. | +| `include` | **Optional.** Allows including related resource data. This endpoint only supports `oauth_client` as a value. Only the `name`, `service-provider`, and `id` will be returned on the OAuth Client object in the `included` block. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z&filter%5Bto%5D=2021-02-12T14%3A09%3A59Z&filter%5Boauth_client_external_ids%5D=oc-hhTM7WNUUgbXJpkW&filter%5Blevels%5D=info&include=oauth_client +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "ve-DJpbEwZc98ZedHZG", + "type": "vcs-events", + "attributes": { + "created-at": "2021-02-09 20:07:49.686182 +0000 UTC", + "level": "info", + "message": "Loaded 11 repositories", + "organization-id": "org-SBVreZxVessAmCZG" + }, + "relationships": { + "oauth-client": { + "data": { + "id": "oc-LePsVhHXhCM6jWf3", + "type": "oauth-clients" + }, + "links": { + "related": "/api/v2/oauth-clients/oc-LePsVhHXhCM6jWf3" + } + }, + "oauth-token": { + "data": { + "id": "ot-Ma2cs8tzjv3LYZHw", + "type": "oauth-tokens" + }, + "links": { + "related": "/api/v2/oauth-tokens/ot-Ma2cs8tzjv3LYZHw" + } + } + } + } + ], + "included": [ + { + "id": "oc-LePsVhHXhCM6jWf3", + "type": "oauth-clients", + "attributes": { + "name": "working", + "service-provider": "gitlab_hosted" + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + }, + "links": { + "related": "/api/v2/organizations/my-organization" + } + }, + "oauth-tokens": { + "data": [ + { + "id": "ot-Ma2cs8tzjv3LYZHw", + "type": "oauth-tokens" + } + ] + } + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/organizations/my-organization/vcs-events?filter%5Bfrom%5D=2021-02-02T14%3A09%3A00Z\u0026filter%5Blevels%5D=info\u0026filter%5Boauth_client_external_ids%5D=oc-LePsVhHXhCM6jWf3\u0026filter%5Bto%5D=2021-02-12T14%3A09%3A59Z\u0026include=oauth_client\u0026organization_name=my-organization\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20" + }, + "meta": { + "pagination": { + "current-page": 1, + "prev-page": null, + "next-page": null, + "total-pages": 1, + "total-count": 8 + } + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspace-resources.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspace-resources.mdx new file mode 100644 index 0000000000..9f53485fc2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspace-resources.mdx @@ -0,0 +1,126 @@ +--- +page_title: /workspaces/resources API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/workspaces/resources` endpoint to list + all of a workspace's resources. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Workspace resources API reference + +## List Workspace Resources + +`GET /workspaces/:workspace_id/resources` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The ID of the workspace to retrieve resources from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [show workspace](/terraform/enterprise/api-docs/workspaces#show-workspace) endpoint. | + +| Status | Response | Reason | +| ------- | ------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "resources"`) | Request was successful. | +| [404][] | [JSON API error object][] | Workspace not found or user unauthorized to perform action. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspace resources per page. | + +### Permissions + +To list resources the user must have permission to read resources for the specified workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Sample Request + +```shell +curl \ + --request GET \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources +``` + +### Sample Response + +```json +{ + "data": [ + { + "id": "wsr-KNYb3Jj3JTBgoBFs", + "type": "resources", + "attributes": { + "address": "random_pet.animal", + "name": "animal", + "created-at": "2021-10-27", + "updated-at": "2021-10-27", + "module": "root", + "provider": "hashicorp/random", + "provider-type": "random_pet", + "modified-by-state-version-id": "sv-y4pjfGHkGUBAa9AX", + "name-index": null + } + }, + { + "id": "wsr-kYsf5A3hQ1y9zFWq", + "type": "resources", + "attributes": { + "address": "random_pet.animal2", + "name": "animal2", + "created-at": "2021-10-27", + "updated-at": "2021-10-27", + "module": "root", + "provider": "hashicorp/random", + "provider-type": "random_pet", + "modified-by-state-version-id": "sv-y4pjfGHkGUBAa9AX", + "name-index": null + } + } + ], + "links": { + "self": "https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "first": "https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources?page%5Bnumber%5D=1&page%5Bsize%5D=20", + "prev": null, + "next": null, + "last": "https://app.terraform.io/api/v2/workspaces/ws-DiTzUDRpjrArAfSS/resources?page%5Bnumber%5D=1&page%5Bsize%5D=20" + }, + ... +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspace-variables.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspace-variables.mdx new file mode 100644 index 0000000000..d3a92c657e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspace-variables.mdx @@ -0,0 +1,298 @@ +--- +page_title: /workspaces/vars API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's workspace `/workspaces/vars` endpoint to + manage workspace-specific variables. Read, create, update, and delete + workspace variables. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +# Workspace variables API reference + +This set of APIs covers create, update, list and delete operations on workspace variables. + +Viewing variables requires permission to read variables for their workspace. Creating, updating, and deleting variables requires permission to read and write variables for their workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a Variable + +`POST /workspaces/:workspace_id/vars` + +| Parameter | Description | +| --------------- | -------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to create the variable in. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.attributes.key` | string | | The name of the variable. | +| `data.attributes.value` | string | `""` | The value of the variable. | +| `data.attributes.description` | string | | The description of the variable. | +| `data.attributes.category` | string | | Whether this is a Terraform or environment variable. Valid values are `"terraform"` or `"env"`. | +| `data.attributes.hcl` | bool | `false` | Whether to evaluate the value of the variable as a string of HCL code. Has no effect for environment variables. | +| `data.attributes.sensitive` | bool | `false` | Whether the value is sensitive. If true then the variable is written once and not visible thereafter. | + +**Deprecation warning**: The custom `filter` properties are replaced by JSON API `relationships` and will be removed from future versions of the API! + +| Key path | Type | Default | Description | +| -------------------------- | ------ | ------- | ----------------------------------------------------- | +| `filter.workspace.name` | string | | The name of the workspace that owns the variable. | +| `filter.organization.name` | string | | The name of the organization that owns the workspace. | + +### Sample Payload + +```json +{ + "data": { + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "category":"terraform", + "hcl":false, + "sensitive":false + } + } +} +``` + +### 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/workspaces/ws-4j8p6jX1w33MiDC7/vars +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-EavQ1LztoRTQHSNT", + "type":"vars", + "attributes": { + "key":"some_key", + "value":"some_value", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false, + "version-id":"1aa07d63ea8ff4df941c94ca9ddfd5d2bd04" + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-EavQ1LztoRTQHSNT" + } + } +} +``` + +## List Variables + +`GET /workspaces/:workspace_id/vars` + +| Parameter | Description | +| --------------- | ---------------------------------------------- | +| `:workspace_id` | The ID of the workspace to list variables for. | + +### Sample Request + +```shell +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ +"https://app.terraform.io/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars" +``` + +### Sample Response + +```json +{ + "data": [ + { + "id":"var-AD4pibb9nxo1468E", + "type":"vars","attributes": { + "key":"name", + "value":"hello", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false, + "version-id":"1aa07d63ea8ff4df941c94ca9ddfd5d2bd04" + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-cZE9LERN3rGPRAmH", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/my-organization/workspaces/my-workspace" + } + } + }, + "links": { + "self":"/api/v2/workspaces/ws-cZE9LERN3rGPRAmH/vars/var-AD4pibb9nxo1468E" + } + } + ] +} +``` + +## Update Variables + +`PATCH /workspaces/:workspace_id/vars/:variable_id` + +| Parameter | Description | +| --------------- | ----------------------------------------------- | +| `:workspace_id` | The ID of the workspace that owns the variable. | +| `:variable_id` | The ID of the variable to be updated. | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ----------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"vars"`. | +| `data.id` | string | | The ID of the variable to update. | +| `data.attributes` | object | | New attributes for the variable. This object can include `key`, `value`, `description`, `category`, `hcl`, and `sensitive` properties, which are described above under [create a variable](#create-a-variable). All of these properties are optional; if omitted, a property will be left unchanged. | + +### Sample Payload + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "attributes": { + "key":"name", + "value":"mars", + "description":"some description", + "category":"terraform", + "hcl": false, + "sensitive": false + }, + "type":"vars" + } +} +``` + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request PATCH \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG +``` + +### Sample Response + +```json +{ + "data": { + "id":"var-yRmifb4PJj7cLkMG", + "type":"vars", + "attributes": { + "key":"name", + "value":"mars", + "description":"some description", + "sensitive":false, + "category":"terraform", + "hcl":false, + "version-id":"1aa07d63ea8ff4df941c94ca9ddfd5d2bd04" + }, + "relationships": { + "configurable": { + "data": { + "id":"ws-4j8p6jX1w33MiDC7", + "type":"workspaces" + }, + "links": { + "related":"/api/v2/organizations/workspace-v2-06/workspaces/workspace-v2-06" + } + } + }, + "links": { + "self":"/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG" + } + } +} +``` + +## Delete Variables + +`DELETE /workspaces/:workspace_id/vars/:variable_id` + +| Parameter | Description | +| --------------- | ----------------------------------------------- | +| `:workspace_id` | The ID of the workspace that owns the variable. | +| `:variable_id` | The ID of the variable to be deleted. | + +### Sample Request + +```bash +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/workspaces/ws-4j8p6jX1w33MiDC7/vars/var-yRmifb4PJj7cLkMG +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspaces.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspaces.mdx new file mode 100644 index 0000000000..b29e7c83d8 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/api-docs/workspaces.mdx @@ -0,0 +1,1689 @@ +--- +page_title: /workspaces API reference for Terraform Enterprise +description: >- + Use the Terraform Enterprise API's `/workspaces` endpoint to read, create, + update, lock, unlock, and delete workspaces and manage SSH keys, tags, and + remote state consumers. +source: terraform-docs-common +--- + +[200]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200 + +[201]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201 + +[202]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 + +[204]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204 + +[400]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400 + +[401]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 + +[403]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403 + +[404]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404 + +[409]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409 + +[412]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412 + +[422]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422 + +[429]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429 + +[500]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500 + +[504]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504 + +[JSON API document]: /terraform/enterprise/api-docs#json-api-documents + +[JSON API error object]: https://jsonapi.org/format/#error-objects + +[speculative plans]: /terraform/enterprise/run/remote-operations#speculative-plans + +# Workspaces API reference + +This topic provides reference information about the workspaces AP. Workspaces represent running infrastructure managed by Terraform. + +## Overview + +The scope of the API includes the following endpoints: + +| Method | Path | Action | +| -------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POST` | `/organizations/:organization_name/workspaces` | Call this endpoint to [create a workspace](#create-a-workspace). You can apply tags stored as key-value pairs when creating the workspace. | +| `POST` | `/organizations/:organization_name/workspaces/:name/actions/safe-delete` | Call this endpoint to [safely delete a workspace](#safe-delete-a-workspace) by querying the organization and workspace names. | +| `POST` | `/workspaces/:workspace_id/actions/safe-delete` | Call this endpoint [safely delete a workspace](#safe-delete-a-workspace) by querying the workspace ID. | +| `POST` | `/workspaces/:workspace_id/actions/lock` | Call this endpoint to [lock a workspace](#lock-a-workspace). | +| `POST` | `/workspaces/:workspace_id/actions/unlock` | Call this endpoint to [unlock a workspace](#unlock-a-workspace). | +| `POST` | `/workspaces/:workspace_id/actions/force-unlock` | Call this endpoint to [force a workspace to unlock](#force-unlock-a-workspace). | +| `POST` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [add remote state consumers](#get-remote-state-consumers). | +| `POST` | `/workspaces/:workspace_id/relationships/tags` | Call this endpoint to [bind flat string tags to an existing workspace](#add-tags-to-a-workspace). | +| `POST` | `/workspaces/:workspace_id/relationships/data-retention-policy` | Call this endpoint to [show the workspace data retention policy](#show-data-retention-policy). | +| `GET` | `/organizations/:organization_name/workspaces` | Call this endpoint to [list existing workspaces](#list-workspaces). Each project in the response contains a link to `effective-tag-bindings` and `tag-bindings` collections. You can filter the response by tag keys and values using a query string parameter. | +| `GET` | `/organizations/:organization_name/workspaces/:name` | Call this endpoint to [show workspace details](#show-workspace) by querying the organization and workspace names. | +| `GET` | `/workspaces/:workspace_id` | Call this endpoint to [show workspace details](#show-workspace). | +| `GET` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [list remote state consumers](#get-remote-state-consumers). | +| `GET` | `/workspaces/:workspace_id/relationships/tags` | Call this endpoint to [list flat string workspace tags](#get-tags). | +| `GET` | `/workspaces/:workspace_id/tag-bindings` | Call this endpoint to [list workspace key-value tags](#get-tags) bound directly to this workspace. | +| `GET` | `/workspaces/:workspace_id/effective-tag-bindings` | Call this endpoint to [list all workspace key-value tags](#get-tags), including both those bound directly to the workspace as well as those inherited from the parent project. | +| `GET` | `/workspaces/:workspace_id/relationships/data-retention-policy` | Call this endpoint to [show the workspace data retention policy](#show-data-retention-policy). | +| `PATCH` | `/workspaces/:workspace_id/relationships/ssh-key` | Call this endpoint to manage SSH key assignments for workspaces. Refer to [Assign an SSH key to a workspace](#assign-an-ssh-key-to-a-workspace) and [Unassign an SSH key from a workspace](#unassign-an-ssh-key-from-a-workspace) for instructions. | +| `PATCH` | `/workspaces/:workspace_id` | Call this endpoint to [update a workspace](#update-a-workspace). You can apply tags stored as key-value pairs when updating the workspace. | +| `PATCH` | `/organizations/:organization_name/workspaces/:name` | Call this endpoint to [update a workspace](#update-a-workspace) by querying the organization and workspace names. | +| `PATCH` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [replace remote state consumers](#replace-remote-state-consumers). | +| `DELETE` | `/workspaces/:workspace_id/relationships/remote-state-consumers` | Call this endpoint to [delete remote state consumers](#delete-remote-state-consumers). | +| `DELETE` | `/workspaces/:workspace_id/relationships/tags` | Call this endpoint to [delete flat string workspace tags](#remove-tags-from-workspace) from the workspace. | +| `DELETE` | `/workspaces/:workspace_id/relationships/data-retention-policy` | Call this endpoint to [remove a workspace data retention policy](#remove-data-retention-policy). | +| `DELETE` | `/workspaces/:workspace_id` | Call this endpoint to [force delete a workspace](#force-delete-a-workspace), which deletes the workspace without first checking for managed resources. | +| `DELETE` | `/organizations/:organization_name/workspaces/:name` | Call this endpoint to [force delete a workspace](#force-delete-a-workspace), which deletes the workspace without first checking for managed resources, by querying the organization and workspace names. | + +## Requirements + +- You must be a member of a team with the **Read** permission enabled for Terraform runs to view workspaces. +- You must be a member of a team with the **Admin** permissions enabled on the workspace to change settings and force-unlock it. +- You must be a member of a team with the **Lock/unlock** permission enabled to lock and unlock the workspace. +- You must meet one of the following requirements to create a workspace: + - Be the team owner + - Be on a team with the **Manage all workspaces** permission enabled + - Present an [organization API token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) when calling the API. + +Refer to [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) for additional information. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Create a Workspace + +Use the following endpoint to create a new workspace: + +`POST /organizations/:organization_name/workspaces` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:organization_name` | The name of the organization to create the workspace in. The organization must already exist in the system, and the user must have permissions to create new workspaces. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +By supplying the necessary attributes under a `vcs-repository` object, you can create a workspace that is configured against a VCS Repository. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | none | Must be `"workspaces"`. | +| `data.attributes.name` | string | none | The name of the workspace. Workspace names can only include letters, numbers, `-`, and `_`. The name a unique identifier n the organization. | +| `data.attributes.agent-pool-id` | string | none | Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote` or `local` or if `operations` is set to `true`. | +| `data.attributes.allow-destroy-plan` | boolean | `true` | Whether destroy plans can be queued on the workspace. | +| `data.attributes.assessments-enabled` | boolean | `false` | (previously `drift-detection`) Whether or not HCP Terraform performs health assessments for the workspace. May be overridden by the organization setting `assessments-enforced`. Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in [Remote execution mode](/terraform/enterprise/workspaces/settings#execution-mode). | +| `data.attributes.auto-apply` | boolean | `false` | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, [with some exceptions](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply). | +| `data.attributes.auto-apply-run-trigger` | boolean | `false` | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers. | +| `data.attributes.auto-destroy-at` | string | (nothing) | Timestamp when the next scheduled destroy run will occur, refer to [Scheduled Destroy](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). | +| `data.attributes.auto-destroy-activity-duration` | string | (nothing) | Value and units for [automatically scheduled destroy runs based on workspace activity](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). Valid values are greater than 0 and four digits or less. Valid units are `d` and `h`. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. | +| `data.attributes.description` | string | (nothing) | A description for the workspace. | +| `data.attributes.execution-mode` | string | (nothing) | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use. Valid values are `remote`, `local`, and `agent`. When set to `local`, the workspace will be used for state storage only. This value _must not_ be specified if `operations` is specified, and _must_ be specified if `setting-overwrites.execution-mode` is set to `true`. | +| `data.attributes.file-triggers-enabled` | boolean | `true` | Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either `trigger-prefixes` in conjunction with `working_directory` or `trigger-patterns` to describe the set of changed files that will start a run. If disabled, any push triggers a run. | +| `data.attributes.global-remote-state` | boolean | `false` | Whether the workspace should allow all workspaces in the organization to [access its state data](/terraform/enterprise/workspaces/state) during runs. If `false`, then only specifically approved workspaces can access its state. Manage allowed workspaces using the [Remote State Consumers](/terraform/enterprise/api-docs/workspaces#get-remote-state-consumers) endpoints, documented later on this page. Terraform Enterprise admins can choose the default value for new workspaces if this attribute is omitted. | +| `data.attributes.operations` | boolean | `true` | **DEPRECATED** Use `execution-mode` instead. Whether to use remote execution mode. When set to `false`, the workspace will be used for state storage only. This value must not be specified if `execution-mode` is specified. | +| `data.attributes.queue-all-runs` | boolean | `false` | Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued. | +| `data.attributes.source-name` | string | none | A friendly name for the application or client creating this workspace. If set, this will be displayed on the workspace as "Created via ``". | +| `data.attributes.source-url` | string | none | A URL for the application or client creating this workspace. This can be the URL of a related resource in another app, or a link to documentation or other info about the client. | +| `data.attributes.speculative-enabled` | boolean | `true` | Whether this workspace allows automatic [speculative plans][]. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API. | +| `data.attributes.terraform-version` | string | latest release | Specifies the version of Terraform to use for this workspace. You can specify an exact version or a [version constraint](/terraform/language/expressions/version-constraints) such as `~> 1.0.0`. If you specify a constraint, the workspace always uses the newest release that meets that constraint. If omitted when creating a workspace, this defaults to the latest released version. | +| `data.attributes.trigger-patterns` | array | `[]` | List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository. | +| `data.attributes.trigger-prefixes` | array | `[]` | List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform starts a run when files are changed in any directory path matching the provided set of prefixes. | +| `data.attributes.vcs-repo.branch` | string | repository's default branch | The repository branch that Terraform executes from. If omitted or submitted as an empty string, this defaults to the repository's default branch. | +| `data.attributes.vcs-repo.identifier` | string | none | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | `false` | Whether submodules should be fetched when cloning the VCS repository. | +| `data.attributes.vcs-repo.oauth-token-id` | string | none | Specifies the VCS OAuth connection and token. Call the [`oauth-tokens`](/terraform/enterprise/api-docs/oauth-tokens) endpoint to retrieve the OAuth ID. | +| `data.attributes.vcs-repo.tags-regex` | string | none | A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. | +| `data.attributes.vcs-repo` | object | none | Settings for the workspace's VCS repository. If omitted, the workspace is created without a VCS repo. If included, you must specify at least the `oauth-token-id` and `identifier` keys. | +| `data.attributes.working-directory` | string | (nothing) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. | +| `data.attributes.setting-overwrites` | object | none | The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is `true` by default. To overwrite the default inherited value, set an attribute's value to `false`. For example, to set `execution-mode` as the organization default, set `setting-overwrites.execution-mode` to `false`. | +| `data.relationships` | object | none | Specifies a group of workspace associations. | +| `data.relationships.project.data.id` | string | default project | The ID of the project to create the workspace in. If left blank, Terraform creates the workspace in the organization's default project. You must have permission to create workspaces in the project, either by organization-level permissions or team admin access to a specific project. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to attach to the workspace. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +_Without a VCS repository_ + +```json +{ + "data": { + "attributes": { + "name": "workspace-1" + }, + "type": "workspaces" + } +} +``` + +_With Key/Value Tags_ + +```json +{ + "data": { + "attributes": { + "name": "workspace-1" + }, + "type": "workspaces", + "relationships": { + "tag-bindings": { + { + "data": [{ + "type": "tag-bindings", + "attributes": { "key": "env", "value": "test"} + }] + } + } + } + } +} +``` + +_With a VCS repository_ + +```json +{ + "data": { + "attributes": { + "name": "workspace-2", + "terraform_version": "0.11.1", + "working-directory": "", + "vcs-repo": { + "identifier": "example/terraform-test-proj", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "", + "tags-regex": null + } + }, + "type": "workspaces" + } +} +``` + +_Using Git Tags_ + +HCP Terraform triggers a run when you push a Git tag that matches the regular expression (SemVer): `1.2.3`, `22.33.44`, etc. + +```json +{ + "data": { + "attributes": { + "name": "workspace-3", + "terraform_version": "0.12.1", + "file-triggers-enabled": false, + "working-directory": "/networking", + "vcs-repo": { + "identifier": "example/terraform-test-proj-monorepo", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "", + "tags-regex": "\d+.\d+.\d+" + } + }, + "type": "workspaces" + } +} +``` + +_For a monorepo using trigger prefixes_ + +A run will be triggered in this workspace when changes are detected in any of the specified directories: `/networking`, `/modules`, or `/vendor`. + +```json +{ + "data": { + "attributes": { + "name": "workspace-3", + "terraform_version": "0.12.1", + "file-triggers-enabled": true, + "trigger-prefixes": ["/modules", "/vendor"], + "working-directory": "/networking", + "vcs-repo": { + "identifier": "example/terraform-test-proj-monorepo", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "" + }, + "updated-at": "2017-11-29T19:18:09.976Z" + }, + "type": "workspaces" + } +} +``` + +_For a monorepo using trigger patterns_ + +A run will be triggered in this workspace when HCP Terraform detects any of the following changes: + +- A file with the extension `tf` in any directory structure in which the last folder is named `networking` (e.g., `root/networking` and `root/module/networking`) +- Any file changed in the folder `/base`, no subfolders are included +- Any file changed in the folder `/submodule` and all of its subfolders + +```json +{ + "data": { + "attributes": { + "name": "workspace-4", + "terraform_version": "1.2.2", + "file-triggers-enabled": true, + "trigger-patterns": ["/**/networking/*.tf", "/base/*", "/submodule/**/*"], + "vcs-repo": { + "identifier": "example/terraform-test-proj-monorepo", + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ", + "branch": "" + }, + "updated-at": "2022-06-09T19:18:09.976Z" + }, + "type": "workspaces" + } +} +``` + +_Using HCP Terraform agents_ + +[HCP Terraform agents](/terraform/enterprise/api-docs/agents) allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. + +```json +{ + "data": { + "attributes": { + "name":"workspace-1", + "execution-mode": "agent", + "agent-pool-id": "apool-ZjT6A7mVFm5WHT5a" + } + }, + "type": "workspaces" +} +``` + +_Using an organization default execution mode_ + +```json +{ + "data": { + "attributes": { + "name":"workspace-with-default", + "setting-overwrites": { + "execution-mode": false + } + } + }, + "type": "workspaces" +} + +``` + +_With a project_ + +```json +{ + "data": { + "type": "workspaces", + "attributes": { + "name": "workspace-in-project" + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-jT92VLSFpv8FwKtc" + } + } + } + } +} +``` + +_With key-value tags_ + +```json +{ + "data": { + "type": "workspaces", + "attributes": { + "name": "workspace-in-project" + } + } +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces +``` + +### Sample Response + +_Without a VCS repository_ + +**Note:** The `assessments-enabled` property is only accepted by or returned from HCP Terraform. + +@include 'api-code-blocks/workspace.mdx' + +_With a VCS repository_ + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +_With a project_ + +```json +{ + "data": { + "id": "ws-HRkJLSYWF97jucqQ", + "type": "workspaces", + "attributes": { + "allow-destroy-plan": true, + "auto-apply": false, + "auto-apply-run-trigger": false, + "auto-destroy-at": null, + "auto-destroy-activity-duration": null, + "created-at": "2022-12-05T20:57:13.829Z", + "environment": "default", + "locked": false, + "locked-reason": "", + "name": "workspace-in-project", + "queue-all-runs": false, + "speculative-enabled": true, + "structured-run-output-enabled": true, + "terraform-version": "1.3.5", + "working-directory": null, + "global-remote-state": true, + "updated-at": "2022-12-05T20:57:13.829Z", + "resource-count": 0, + "apply-duration-average": null, + "plan-duration-average": null, + "policy-check-failures": null, + "run-failures": null, + "workspace-kpis-runs-count": null, + "latest-change-at": "2022-12-05T20:57:13.829Z", + "operations": true, + "execution-mode": "remote", + "vcs-repo": null, + "vcs-repo-identifier": null, + "permissions": { + "can-update": true, + "can-destroy": true, + "can-queue-run": true, + "can-read-variable": true, + "can-update-variable": true, + "can-read-state-versions": true, + "can-read-state-outputs": true, + "can-create-state-versions": true, + "can-queue-apply": true, + "can-lock": true, + "can-unlock": true, + "can-force-unlock": true, + "can-read-settings": true, + "can-manage-tags": true, + "can-manage-run-tasks": false, + "can-force-delete": true, + "can-manage-assessments": true, + "can-read-assessment-results": true, + "can-queue-destroy": true + }, + "actions": { + "is-destroyable": true + }, + "description": null, + "file-triggers-enabled": true, + "trigger-prefixes": [], + "trigger-patterns": [], + "assessments-enabled": false, + "last-assessment-result-at": null, + "source": "tfe-api", + "source-name": null, + "source-url": null, + "tag-names": [], + "setting-overwrites": { + "execution-mode": false, + "agent-pool": false + } + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + }, + "current-run": { + "data": null + }, + "effective-tag-bindings": { + "links": { + "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/effective-tag-bindings" + } + }, + "latest-run": { + "data": null + }, + "outputs": { + "data": [] + }, + "remote-state-consumers": { + "links": { + "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/relationships/remote-state-consumers" + } + }, + "current-state-version": { + "data": null + }, + "current-configuration-version": { + "data": null + }, + "agent-pool": { + "data": null + }, + "readme": { + "data": null + }, + "project": { + "data": { + "id": "prj-jT92VLSFpv8FwKtc", + "type": "projects" + } + }, + "current-assessment-result": { + "data": null + }, + "tag-bindings": { + "links": { + "related": "/api/v2/workspaces/ws-HRkJLSYWF97jucqQ/tag-bindings" + } + }, + "vars": { + "data": [] + }, + }, + "links": { + "self": "/api/v2/organizations/my-organization/workspaces/workspace-in-project" + } + } +} +``` + +## Update a Workspace + +Use one of the following endpoint to update a workspace: + +- `PATCH /organizations/:organization_name/workspaces/:name` +- `PATCH /workspaces/:workspace_id` + +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to update | +| `:organization_name` | The name of the organization the workspace belongs to. | +| `:name` | The name of the workspace to update. Workspace names are unique identifiers in the organization and can only include letters, numbers, `-`, and `_`. | + +### Request Body + +These PATCH endpoints require a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------------------------------------------------- | --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.attributes.name` | string | (previous value) | A new name for the workspace, which can only include letters, numbers, `-`, and `_`. This will be used as an identifier and must be unique in the organization. **Warning:** Changing a workspace's name changes its URL in the API and UI. | +| `data.attributes.agent-pool-id` | string | (previous value) | Required when `execution-mode` is set to `agent`. The ID of the agent pool belonging to the workspace's organization. This value must not be specified if `execution-mode` is set to `remote` or `local` or if `operations` is set to `true`. | +| `data.attributes.allow-destroy-plan` | boolean | (previous value) | Whether destroy plans can be queued on the workspace. | +| `data.attributes.assessments-enabled` | boolean | `false` | (previously `drift-detection`) Whether or not HCP Terraform performs health assessments for the workspace. May be overridden by the organization setting `assessments-enforced`. Only available for Plus tier organizations, in workspaces running Terraform version 0.15.4+ and operating in [Remote execution mode](/terraform/enterprise/workspaces/settings#execution-mode). | +| `data.attributes.auto-apply` | boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by VCS, UI or CLI, [with some exceptions](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply). | +| `data.attributes.auto-apply-run-trigger` | boolean | (previous value) | Whether to automatically apply changes when a Terraform plan is successful in runs initiated by run triggers. | +| `data.attributes.auto-destroy-at` | string | (previous value) | Timestamp when the next scheduled destroy run will occur, refer to [Scheduled Destroy](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). | +| `data.attributes.auto-destroy-activity-duration` | string | (previous value) | Value and units for [automatically scheduled destroy runs based on workspace activity](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy). Valid values are greater than 0 and four digits or less. Valid units are `d` and `h`. For example, to queue destroy runs after fourteen days of inactivity set `auto-destroy-activity-duration: "14d"`. | +| `data.attributes.description` | string | (previous value) | A description for the workspace. | +| `data.attributes.execution-mode` | string | (previous value) | Which [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) to use. Valid values are `remote`, `local`, and `agent`. When set to `local`, the workspace will be used for state storage only. This value _must not_ be specified if `operations` is specified, and _must_ be specified if `setting-overwrites.execution-mode` is set to `true`. | +| `data.attributes.file-triggers-enabled` | boolean | (previous value) | Whether to filter runs based on the changed files in a VCS push. If enabled, it uses either `trigger-prefixes` in conjunction with `working_directory` or `trigger-patterns` to describe the set of changed files that will start a run. If disabled, any push will trigger a run. | +| `data.attributes.global-remote-state` | boolean | (previous value) | Whether the workspace should allow all workspaces in the organization to [access its state data](/terraform/enterprise/workspaces/state) during runs. If `false`, then only specifically approved workspaces can access its state. Manage allowed workspaces using the [Remote State Consumers](/terraform/enterprise/api-docs/workspaces#get-remote-state-consumers) endpoints, documented later on this page. | +| `data.attributes.operations` | boolean | (previous value) | **DEPRECATED** Use `execution-mode` instead. Whether to use remote execution mode. When set to `false`, the workspace will be used for state storage only. This value must not be specified if `execution-mode` is specified. | +| `data.attributes.queue-all-runs` | boolean | (previous value) | Whether runs should be queued immediately after workspace creation. When set to false, runs triggered by a VCS change will not be queued until at least one run is manually queued. | +| `data.attributes.speculative-enabled` | boolean | (previous value) | Whether this workspace allows automatic [speculative plans][]. Setting this to `false` prevents HCP Terraform from running plans on pull requests, which can improve security if the VCS repository is public or includes untrusted contributors. It doesn't prevent manual speculative plans via the CLI or the runs API. | +| `data.attributes.terraform-version` | string | (previous value) | The version of Terraform to use for this workspace. This can be either an exact version or a [version constraint](/terraform/language/expressions/version-constraints) (like `~> 1.0.0`); if you specify a constraint, the workspace will always use the newest release that meets that constraint. | +| `data.attributes.trigger-patterns` | array | (previous value) | List of glob patterns that describe the files HCP Terraform monitors for changes. Trigger patterns are always appended to the root directory of the repository. | +| `data.attributes.trigger-prefixes` | array | (previous value) | List of trigger prefixes that describe the paths HCP Terraform monitors for changes, in addition to the working directory. Trigger prefixes are always appended to the root directory of the repository. HCP Terraform will start a run when files are changed in any directory path matching the provided set of prefixes. | +| `data.attributes.vcs-repo.branch` | string | (previous value) | The repository branch that Terraform will execute from. | +| `data.attributes.vcs-repo.identifier` | string | (previous value) | A reference to your VCS repository in the format :org/:repo where :org and :repo refer to the organization and repository in your VCS provider. The format for Azure DevOps is `:org/:project/_git/:repo`. | +| `data.attributes.vcs-repo.ingress-submodules` | boolean | (previous value) | Whether submodules should be fetched when cloning the VCS repository. | +| `data.attributes.vcs-repo.oauth-token-id` | string | | The VCS Connection (OAuth Connection + Token) to use as identified. Get this ID from the [oauth-tokens](/terraform/enterprise/api-docs/oauth-tokens) endpoint. You can not specify this value if `github-app-installation-id` is specified. | +| `data.attributes.vcs-repo.github-app-installation-id` | string | | The VCS Connection GitHub App Installation to use. Find this ID on the account settings page. Requires previously authorizing the GitHub App and generating a user-to-server token. Manage the token from **Account Settings** within HCP Terraform. You can not specify this value if `oauth-token-id` is specified. | +| `data.attributes.vcs-repo.tags-regex` | string | (previous value) | A regular expression used to match Git tags. HCP Terraform triggers a run when this value is present and a VCS event occurs that contains a matching Git tag for the regular expression. | +| `data.attributes.vcs-repo` | object or null | (previous value) | To delete a workspace's existing VCS repo, specify `null` instead of an object. To modify a workspace's existing VCS repo, include whichever of the keys below you wish to modify. To add a new VCS repo to a workspace that didn't previously have one, include at least the `oauth-token-id` and `identifier` keys. | +| `data.attributes.working-directory` | string | (previous value) | A relative path that Terraform will execute within. This defaults to the root of your repository and is typically set to a subdirectory matching the environment when multiple environments exist within the same repository. | +| `data.attributes.setting-overwrites` | object | | The keys in this object are attributes that have organization-level defaults. Each attribute key stores a boolean value which is `true` by default. To overwrite the default inherited value, set an attribute's value to `false`. For example, to set `execution-mode` as the organization default, you set `setting-overwrites.execution-mode = false`. | +| `data.relationships` | object | none | Specifies a group of workspace relationships. | +| `data.relationships.project.data.id` | string | existing value | The ID of the project to move the workspace to. If left blank or unchanged, the workspace will not be moved. You must have admin permissions on both the source project and destination project in order to move a workspace between projects. | +| `data.relationships.tag-bindings.data` | list of objects | none | Specifies a list of tags to attach to the workspace. | +| `data.relationships.tag-bindings.data.type` | string | none | Must be `tag-bindings` for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.key` | string | none | Specifies the tag key for each object in the list. | +| `data.relationships.tag-bindings.data.attributes.value` | string | none | Specifies the tag value for each object in the list. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "name": "workspace-2", + "resource-count": 0, + "terraform_version": "0.11.1", + "working-directory": "", + "vcs-repo": { + "identifier": "example/terraform-test-proj", + "branch": "", + "ingress-submodules": false, + "oauth-token-id": "ot-hmAyP66qk2AMVdbJ" + }, + "updated-at": "2017-11-29T19:18:09.976Z" + }, + "relationships": { + "project": { + "data": { + "type": "projects", + "id": "prj-7HWWPGY3fYxztELU" + } + }, + "tag-bindings": { + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "environment", + "value": "development" + } + }, + ] + } + }, + "type": "workspaces" + } +} +``` + +### 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/my-organization/workspaces/workspace-2 +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## List workspaces + +This endpoint lists workspaces in the organization. + +`GET /organizations/:organization_name/workspaces` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------- | +| `:organization_name` | The name of the organization to list the workspaces of. | + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | +| `search[name]` | **Optional.** If specified, restricts results to workspaces with a name that matches the search string using a fuzzy search. | +| `search[tags]` | **Optional.** If specified, restricts results to workspaces with that tag. If multiple comma separated values are specified, results matching all of the tags are returned. | +| `search[exclude-tags]` | **Optional.** If specified, results exclude workspaces with that tag. If multiple comma separated values are specified, workspaces with tags matching any of the tags are excluded. | +| `search[wildcard-name]` | **Optional.** If specified, restricts results to workspaces with partial matching, using `*` on prefix, suffix, or both. For example, `search[wildcard-name]=*-prod` returns all workspaces ending in `-prod`, `search[wildcard-name]=prod-*` returns all workspaces beginning with `prod-`, and `search[wildcard-name]=*-prod-*` returns all workspaces with substring `-prod-` regardless of prefix and/or suffix. | +| `sort` | **Optional.** Allows sorting the organization's workspaces by a provided value. You can sort by `"name"`, `"current-run.created-at"` (the time of the current run), and `"latest-change-at"` (the creation time of the latest state version or the workspace itself if no state version exists). Prepending a hyphen to the sort parameter reverses the order. For example, `"-name"` sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. | +| `filter[project][id]` | **Optional.** If specified, restricts results to workspaces in the specific project. | +| `filter[current-run][status]` | **Optional.** If specified, restricts results to workspaces that match the status of a current run. | +| `filter[tagged][i][key]` | **Optional.** If specified, restricts results to workspaces that are tagged with the provided key. Use a value of "0" for `i` if you are only using a single filter. For multiple tag filters, use an incrementing integer value for each filter. Multiple tag filters will be combined together with a logical AND when filtering results. | +| `filter[tagged][i][value]` | **Optional.** If specified, restricts results to workspaces that are tagged with the provided value. This is useful when combined with a `key` filter for more specificity. Use a value of "0" for `i` if you are only using a single filter. For multiple tag filters, use an incrementing integer value for each filter. Multiple tag filters will be combined together with a logical AND when filtering results. | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces +``` + +_With multiple tag filters_ + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces?filter%5B%tagged5D%5B0%5D%5Bkey%5D=environment&filter%5B%tagged5D%5B0%5D%5Bvalue%5D=development&filter%5B%tagged5D%5B1%5D%5Bkey%5D=meets-compliance +``` + +### Sample Response + +@include 'api-code-blocks/workspaces-list.mdx' + +## Show workspace + +Details on a workspace can be retrieved from two endpoints, which behave identically. + +One refers to a workspace by its ID: + +`GET /workspaces/:workspace_id` + +| Parameter | Description | +| --------------- | ---------------- | +| `:workspace_id` | The workspace ID | + +The other refers to a workspace by its name and organization: + +`GET /organizations/:organization_name/workspaces/:name` + +| Parameter | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the workspace belongs to. | +| `:name` | The name of the workspace to show details for, which can only include letters, numbers, `-`, and `_`. | + +### Workspace performance attributes + +The following attributes are helpful in determining the overall health and performance of your workspace configuration. These metrics refer to the **past 30 runs that have either resulted in an error or successfully applied**. + +| Parameter | Type | Description | +| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------- | +| `data.attributes.apply-duration-average` | number | This is the average time runs spend in the **apply** phase, represented in milliseconds | +| `data.attributes.plan-duration-average` | number | This is the average time runs spend in the **plan** phase, represented in milliseconds | +| `data.attributes.policy-check-failures` | number | Reports the number of run failures resulting from a policy check failure | +| `data.attributes.run-failures` | number | Reports the number of failed runs | +| `data.attributes.workspace-kpis-run-count` | number | Total number of runs taken into account by these metrics | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1 +``` + +### Sample Response + +@include 'api-code-blocks/workspace.mdx' + +## Safe Delete a workspace + +When you delete an HCP Terraform workspace with resources, Terraform can no longer track or manage that infrastructure. During a safe delete, HCP Terraform only deletes the workspace if it is not managing resources. + +You can safe delete a workspace using two endpoints that behave identically. The first endpoint identifies a workspace with the workspace ID, and the other identifies the workspace by its name and organization. + +`POST /workspaces/:workspace_id/actions/safe-delete` + +| Parameter | Description | +| --------------- | ---------------------------------- | +| `:workspace_id` | The ID of the workspace to delete. | + +`POST /organizations/:organization_name/workspaces/:name/actions/safe-delete` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the workspace's organization. | +| `:name` | The name of the workspace to delete, which can only include letters, numbers, `-`, and `_`. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform workspace delete | +| [409][] | [JSON API error object][] | Workspace is not safe to delete because it is managing resources | + +## Force Delete a workspace + +During a force delete, HCP Terraform removes the specified workspace without checking whether it is managing resources. We recommend using the [safe delete endpoint](#safe-delete-a-workspace) instead, when possible. + +!> **Warning:** Terraform cannot track or manage the workspace's infrastructure after deletion. We recommend [destroying the workspace's infrastructure](/terraform/enterprise/run/modes-and-options#destroy-mode) before you delete it. + +By default, only organization owners can force delete workspaces. Organization owners can also update [organization's settings]\(/terraform/cloud-docs/users-teams organizations/organizations#general) to let workspace admins force delete their own workspaces. + +You can use two endpoints to force delete a workspace, which behave identically. One endpoint identifies the workspace with its workspace ID and the other endpoint identifies the workspace with its name and organization. + +`DELETE /workspaces/:workspace_id` + +| Parameter | Description | +| --------------- | --------------------------------- | +| `:workspace_id` | The ID of the workspace to delete | + +`DELETE /organizations/:organization_name/workspaces/:name` + +| Parameter | Description | +| -------------------- | ------------------------------------------------------------------------------------------- | +| `:organization_name` | The name of the organization the workspace belongs to. | +| `:name` | The name of the workspace to delete, which can only include letters, numbers, `-`, and `_`. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully deleted the workspace | +| [403][] | [JSON API error object][] | Not authorized to perform a force delete on the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform workspace delete | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + https://app.terraform.io/api/v2/organizations/my-organization/workspaces/workspace-1 +``` + +## Lock a workspace + +This endpoint locks a workspace. + +`POST /workspaces/:workspace_id/actions/lock` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to lock. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | -------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully locked the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [409][] | [JSON API error object][] | Workspace already locked | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------- | ------ | ------- | ------------------------------------- | +| `reason` | string | `""` | The reason for locking the workspace. | + +### Sample Payload + +```json +{ + "reason": "Locking workspace-1" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/lock +``` + +### Sample Response + +@include 'api-code-blocks/workspace.mdx' + +## Unlock a workspace + +This endpoint unlocks a workspace. Unlocking a workspace sets the current state version to the latest finalized intermediate state version. If intermediate state versions are available, but HCP Terraform has not yet finalized the latest intermediate state version, the unlock will fail with a 503 response. For this particular error, it's recommended to retry the unlock operation for a short period of time until the platform finalizes the state version. If you must force-unlock a workspace under these conditions, ensure that state was saved successfully by inspecting the latest state version using the [State Version List API](/terraform/enterprise/api-docs/state-versions#list-state-versions-for-a-workspace) + +`POST /workspaces/:workspace_id/actions/unlock` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to unlock. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | -------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully unlocked the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [409][] | [JSON API error object][] | Workspace already unlocked, or locked by a different user | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/unlock +``` + +### Sample Response + +@include 'api-code-blocks/workspace.mdx' + +## Force Unlock a workspace + +This endpoint force unlocks a workspace. Only users with admin access are authorized to force unlock a workspace. + +`POST /workspaces/:workspace_id/actions/force-unlock` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to force unlock. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | -------------------------------------------- | ----------------------------------------------------------- | +| [200][] | [JSON API document][] (`type: "workspaces"`) | Successfully force unlocked the workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [409][] | [JSON API error object][] | Workspace already unlocked | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/actions/force-unlock +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## Assign an SSH key to a workspace + +This endpoint assigns an SSH key to a workspace. + +`PATCH /workspaces/:workspace_id/relationships/ssh-key` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to assign the SSH key to. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------ | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.attributes.id` | string | | The SSH key ID to assign. Obtain this from the [ssh-keys](/terraform/enterprise/api-docs/ssh-keys) endpoint. | + +#### Sample Payload + +```json +{ + "data": { + "attributes": { + "id": "sshkey-GxrePWre1Ezug7aM" + }, + "type": "workspaces" + } +} +``` + +### 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/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## Unassign an SSH key from a workspace + +This endpoint unassigns the currently assigned SSH key from a workspace. + +`PATCH /workspaces/:workspace_id/relationships/ssh-key` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to assign the SSH key to. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| -------------------- | ------ | ------- | ----------------------- | +| `data.type` | string | | Must be `"workspaces"`. | +| `data.attributes.id` | string | | Must be `null`. | + +### Sample Payload + +```json +{ + "data": { + "attributes": { + "id": null + }, + "type": "workspaces" + } +} +``` + +### 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/workspaces/ws-SihZTyXKfNXUWuUa/relationships/ssh-key +``` + +### Sample Response + +@include 'api-code-blocks/workspace-with-vcs.mdx' + +## Get Remote State Consumers + +`GET /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to get remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint retrieves the list of other workspaces that are allowed to access the given workspace's state during runs. + +- If `global-remote-state` is set to false for the workspace, this will return the list of other workspaces that are specifically authorized to access the workspace's state. +- If `global-remote-state` is set to true, this will return a list of every workspace in the organization except for the subject workspace. + +The list returned by this endpoint is subject to the caller's normal workspace permissions; it will not include workspaces that the provided API token is unable to read. + +### Query Parameters + +This endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). 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 will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-SihZTyXKfNXUWuUa/relationships/remote-state-consumers +``` + +### Sample Response + +@include 'api-code-blocks/workspaces-list.mdx' + +## Replace Remote State Consumers + +`PATCH /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to replace remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint updates the workspace's remote state consumers to be _exactly_ the list of workspaces specified in the payload. It can only be used for workspaces where `global-remote-state` is false. + +This endpoint can only be used by teams with permission to manage workspaces for the entire organization — only those who can _view_ the entire list of consumers can _replace_ the entire list. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) Teams with admin permissions on specific workspaces can still modify remote state consumers for those workspaces, but must use the add (POST) and remove (DELETE) endpoints listed below instead of this PATCH endpoint. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully updated remote state consumers | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The ID of a workspace to be set as a remote state consumer. | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + ] +} +``` + +### 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/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers +``` + +### Response + +No response body. + +Status code `204`. + +## Add Remote State Consumers + +`POST /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to add remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint adds one or more remote state consumers to the workspace. It can only be used for workspaces where `global-remote-state` is false. + +- The workspaces specified as consumers must be readable to the API token that makes the request. +- A workspace cannot be added as a consumer of itself. (A workspace can always read its own state, regardless of access settings.) +- You can safely add a consumer workspace that is already present; it will be ignored, and the rest of the consumers in the request will be processed normally. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully updated remote state consumers | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ----------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The ID of a workspace to be set as a remote state consumer. | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers +``` + +### Response + +No response body. + +Status code `204`. + +## Delete Remote State Consumers + +`DELETE /workspaces/:workspace_id/relationships/remote-state-consumers` + +| Parameter | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to remove remote state consumers for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +This endpoint removes one or more remote state consumers from a workspace, according to the contents of the payload. It can only be used for workspaces where `global-remote-state` is false. + +- The workspaces specified as consumers must be readable to the API token that makes the request. +- You can safely remove a consumer workspace that is already absent; it will be ignored, and the rest of the consumers in the request will be processed normally. + +| Status | Response | Reason(s) | +| ------- | ------------------------- | --------------------------------------------------------------------- | +| [204][] | No Content | Successfully updated remote state consumers | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | +| [422][] | [JSON API error object][] | Problem with payload or request; details provided in the error object | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +Properties without a default value are required. + +| Key path | Type | Default | Description | +| ------------- | ------ | ------- | ---------------------------------------------------------------- | +| `data[].type` | string | | Must be `"workspaces"`. | +| `data[].id` | string | | The ID of a workspace to remove from the remote state consumers. | + +### Sample Payload + +```json +{ + "data": [ + { + "id": "ws-7aiqKYf6ejMFdtWS", + "type": "workspaces" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/ws-UYv6RYM8fVhzeGG5/relationships/remote-state-consumers +``` + +### Response + +No response body. + +Status code `204`. + +## List workspace tags + +Workspace tags are [organization tags](/terraform/enterprise/api-docs/organization-tags) added to a workspace. They are a flat list of keys that can only be applied to workspaces when using the `tags` attribute in the Terraform `cloud` block in Terraform v1.9 and older. To list key-value tags supported in Terraform v1.10 and newer, refer to [List workspace tag bindings](#list-workspace-tag-bindings). + +`GET /workspaces/:workspace_id/relationships/tags`: Paginated list of flat string tags attached to the workspace. + +### Path parameters + +| Parameter | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to fetch tags for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Query Parameters + +Only the flat string tags endpoint supports pagination [with standard URL query parameters](/terraform/enterprise/api-docs#query-parameters). Remember to percent-encode `[` as `%5B` and `]` as `%5D` if your tooling doesn't automatically encode URLs. Conversely, all tags are returned when using fetching tag-bindings or effective-tag-bindings endpoints. + +| Parameter | Description | +| -------------- | -------------------------------------------------------------------------- | +| `page[number]` | **Optional.** If omitted, the endpoint will return the first page. | +| `page[size]` | **Optional.** If omitted, the endpoint will return 20 workspaces per page. | + +### Sample Requests + + + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/relationships/tags +``` + + + +### Sample Responses + + + +```json +{ + "data": [ + { + "id": "tag-1", + "type": "tags", + "attributes": { + "name": "tag1", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 1 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + }, + { + "id": "tag-2", + "type": "tags", + "attributes": { + "name": "tag2", + "created-at": "2022-03-09T06:04:39.585Z", + "instance-count": 2 + }, + "relationships": { + "organization": { + "data": { + "id": "my-organization", + "type": "organizations" + } + } + } + } + ] +} +``` + + + +## List workspace tag bindings + +Call the following endpoints to list the tags attached to a workspace: + +- `GET /workspaces/:workspace_id/tag-bindings`: Lists key-value tags directly bound to the workspace. +- `GET /workspaces/:workspace_id/effective-tag-bindings`: Lists all key-value tags bound to the workspace, including those inherited from the parent project. + +### Path parameters + +| Parameter | Description | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to fetch tags for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +### Sample Requests + + + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/tag-bindings +``` + + + + + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/workspaces/ws-db61c9eb5cab5ae2/effective-tag-bindings +``` + + + +### Sample Responses + + + +```json +{ + "data": [ + { + "id": "tb-232e23631380f79e", + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123", + "created-at": "2024-11-19T23:59:24.648Z" + } + } + ], + "links": { + "target": "/api/v2/workspaces/ws-db61c9eb5cab5ae2" + } +} +``` + + +
+ + +```json +{ + "data": [ + { + "id": "07cc44202a430fc2", + "type": "effective-tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "id": "f8b11951f98e11f8", + "type": "effective-tag-bindings", + "attributes": { + "key": "dept", + "value": "r+d" + }, + "relationships": { + "inherited-from": { + "links": { + "related": "/api/v2/projects/prj-af7d174fa1ea7423" + } + } + } + } + ] +} +``` + + + +## Add flat string tags to a workspace + +`POST /workspaces/:workspace_id/relationships/tags` + +To add key-value tags to an existing workspace, call the `PATCH /workspaces/:workspace_id` and provide workspace tag bindings in the JSON payload. Refer to [Update a workspace](#update-a-workspace) for additional information. + +You can also bind key-value tags when creating a workspace. Refer to [Create a workspace](#create-a-workspace) for additional information. + +Refer to [Define project tags](/terraform/enterprise/projects/manage#define-project-tags) for information about supported tag values. + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The workspace ID to add tags to. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Successfully added tags to workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that `type`, as well as one of `id` _or_ `attributes.name` is required. + +| Key path | Type | Default | Description | +| ------------------------ | ------ | ------- | --------------------------- | +| `data[].type` | string | | Must be `"tags"`. | +| `data[].id` | string | | The ID of the tag to add. | +| `data[].attributes.name` | string | | The name of the tag to add. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tags", + "attributes": { + "name": "foo" + } + }, + { + "type": "tags", + "attributes": { + "name": "bar" + } + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/workspace-2/relationships/tags +``` + +### Sample Response + +No response body. + +Status code `204`. + +## Remove tags from workspace + +This endpoint removes one or more tags from a workspace. The workspace must already exist, and tag +element that supplies an `id` attribute must exist. If the `name` attribute is used, and no matching +organization tag is found, no action will occur for that entry. Tags removed from all workspaces will be +removed from the organization-wide list. + +To remove key-value tags to an existing workspace, call the `PATCH /workspaces/:workspace_id` and provide workspace tag bindings in the JSON payload. Refer to [Update a workspace](#update-a-workspace) for additional information. + +`DELETE /workspaces/:workspace_id/relationships/tags` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to remove tags from. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or the [Show Workspace](#show-workspace) endpoint. | + +| Status | Response | Reason(s) | +| ------- | ------------------------- | ----------------------------------------------------------- | +| [204][] | No Content | Successfully removed tags to workspace | +| [404][] | [JSON API error object][] | Workspace not found, or user unauthorized to perform action | + +### Request Body + +This POST endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that `type`, as well as one of `id` _or_ `attributes.name` is required. + +| Key path | Type | Default | Description | +| ------------------------ | ------ | ------- | ------------------------------ | +| `data[].type` | string | | Must be `"tags"`. | +| `data[].id` | string | | The ID of the tag to remove. | +| `data[].attributes.name` | string | | The name of the tag to remove. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tags", + "id": "tag-Yfha4YpPievQ8wJw" + } + ] +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request DELETE \ + --data @payload.json \ + https://app.terraform.io/api/v2/workspaces/workspace-2/relationships/tags +``` + +### Sample Response + +No response body. + +Status code `204`. + +## Add/update tag-bindings on a workspace + +This endpoint adds keys and values or updates values of tag-bindings on an existing resource by key. +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 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` + +| Parameter | Description | +| --------------- | --------------------------------- | +| `:workspace_id` | The ID of the workspace to update | + +### Request Body + +This PATCH endpoint requires a JSON object with the following properties as a request payload. + +It is important to note that for each data item, `type`, as well as `attributes.key` is required. + +| Key path | Type | Default | Description | +| ------------------------- | ------ | ------- | ---------------------------------- | +| `data[].type` | string | | Must be `"tag-bindings"`. | +| `data[].attributes.key` | string | | The key of the tag to add/update. | +| `data[].attributes.value` | string | | The name of the tag to add/update. | + +### Sample Payload + +```json +{ + "data": [ + { + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + +### 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/workspaces/ws-82d2281aa259ba09/tag-bindings +``` + +### Sample Response + +Status Code 200 + + + +```json +{ + "data": [ + { + "id": "tb-e4a5847b2cf06559", + "type": "tag-bindings", + "attributes": { + "key": "costcenter", + "value": "123" + } + }, + { + "id": "tb-97ce954636f93a6c", + "type": "tag-bindings", + "attributes": { + "key": "bar", + "value": "baz" + } + } + ] +} +``` + + + +## Show data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`GET /workspaces/:workspace_id/relationships/data-retention-policy` + +| Parameter | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The ID of the workspace to show the data retention policy for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or by sending a `GET` request to the [`/workspaces`](#show-workspace) endpoint. | + +This endpoint shows the data retention policy set explicitly on the workspace. +When no data retention policy is set for the workspace, the endpoint returns the default policy configured for the organization. Refer to [Data Retention Policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) for instructions on configuring data retention policies for workspaces. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#show-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Create or update data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`POST /workspaces/:workspace_id/relationships/data-retention-policy` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `:workspace_id` | The workspace ID to update the data retention policy for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or by sending a `GET` request to the [`/workspaces`](#show-workspace) endpoint. | + +This endpoint creates a data retention policy for a workspace or updates the existing policy. +Refer to [Data Retention Policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies) for additional information. + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#create-or-update-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Remove data retention policy + + +This endpoint is exclusive to Terraform Enterprise and is not available in HCP Terraform. + + +`DELETE /workspaces/:workspace_id/relationships/data-retention-policy` + +| Parameter | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `:workspace_id` | The workspace ID to remove the data retenetion policy for. Obtain this from the [workspace settings](/terraform/enterprise/workspaces/settings) or by sending a `GET` request to the [`/workspaces`](#show-workspace) endpoint. | + +This endpoint removes the data retention policy explicitly set on a workspace. +When no data retention policy is set for the workspace, the endpoint returns the default policy configured for the organization. Refer to [Data Retention Policies](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) for instructions on configuring data retention policies for organizations. + +Read more about [workspace data retention policies](/terraform/enterprise/workspaces/settings/deletion#data-retention-policies). + +Refer to [Data Retention Policy API](/terraform/enterprise/api-docs/data-retention-policies#remove-data-retention-policy) in the Terraform Enterprise documentation for details. + +## Available Related Resources + +The GET endpoints above can optionally return related resources, if requested with [the `include` query parameter](/terraform/enterprise/api-docs#inclusion-of-related-resources). The following resource types are available: + +- `current_configuration_version` - The last configuration this workspace received, excluding plan-only configurations. Terraform uses this configuration for new runs, unless you provide a different one. +- `current_configuration_version.ingress_attributes` - The commit information for the current configuration version. +- `current_run` - Additional information about the current run. +- `current_run.configuration_version` - The configuration used in the current run. +- `current_run.configuration_version.ingress_attributes` - The commit information used in the current run. +- `current_run.plan` - The plan used in the current run. +- `locked_by` - The user, team, or run responsible for locking the workspace, if the workspace is currently locked. +- `organization` - The full organization record. +- `outputs` - The outputs for the most recently applied run. +- `project` - The full project record. +- `readme` - The most recent workspace README.md. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/architectural-details/data-security.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/architectural-details/data-security.mdx new file mode 100644 index 0000000000..ccdd823720 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/architectural-details/data-security.mdx @@ -0,0 +1,75 @@ +--- +page_title: Data security for Terraform Enterprise +description: >- + Learn about the parts of the Terraform Enterprise application that contain + sensitive data and the storage and encryption methods that HCP Terraform uses + to secure them. +source: terraform-docs-common +--- + +# Data security + +HCP Terraform takes the security of the data it manages +seriously. This table lists which parts of the HCP Terraform and Terraform Enterprise app can contain sensitive data, what storage is used, and what encryption is used. + +### HCP Terraform and Terraform Enterprise + +| Object | Storage | Encrypted | +| :----------------------------------- | :----------- | :----------------------- | +| Terraform Configuration (VCS data) | Blob Storage | Vault Transit Encryption | +| Private Registry Modules | Blob Storage | Vault Transit Encryption | +| Sentinel Policies | PostgreSQL | Vault Transit Encryption | +| Terraform/Environment Variables | PostgreSQL | Vault Transit Encryption | +| Terraform/Provider Credentials | PostgreSQL | Vault Transit Encryption | +| Terraform State File | Blob Storage | Vault Transit Encryption | +| Terraform Plan Result | Blob Storage | Vault Transit Encryption | +| Terraform Audit Trails | PostgreSQL | No | +| Organization/Workspace/Team Settings | PostgreSQL | No | + +### HCP Terraform and Terraform Enterprise Secrets + +| Object | Storage | Encrypted | +| :---------------------------- | :--------- | :----------------------- | +| Account Password | PostgreSQL | bcrypt | +| 2FA Recovery Codes | PostgreSQL | Vault Transit Encryption | +| SSH Keys | PostgreSQL | Vault Transit Encryption | +| User/Team/Organization Tokens | PostgreSQL | HMAC SHA512 | +| OAuth Client ID + Secret | PostgreSQL | Vault Transit Encryption | +| OAuth User Tokens | PostgreSQL | Vault Transit Encryption | + +### HCP Terraform Specific + +| Object | Storage | Encrypted | +| :--------------------------- | :-------- | :-------- | +| Cloud Data Backups | Amazon S3 | SSE-S3 | +| Cloud Copy of Backups for DR | Amazon S3 | SSE-S3 | + +Please see HashiCorp Cloud [subprocessors](https://www.hashicorp.com/trust/privacy/subprocessors) for third-parties engaged by HashiCorp to deliver cloud services. + +### Terraform Enterprise Specific + +| Object | Storage | Encrypted | +| :--------------------------- | :--------- | :----------------------- | +| Twilio Account Configuration | PostgreSQL | Vault Transit Encryption | +| SMTP Configuration | PostgreSQL | Vault Transit Encryption | +| SAML Configuration | PostgreSQL | Vault Transit Encryption | +| Vault Unseal Key | PostgreSQL | ChaCha20+Poly1305 | + +## Vault Transit Encryption + +The [Vault Transit Secret Engine](/vault/docs/secrets/transit) +handles encryption for data in-transit and is used when encrypting data from the +application to persistent storage. + +## Blob Storage Encryption + +All objects persisted to blob storage are symmetrically encrypted prior to being +written. Each object is encrypted with a unique encryption key. Objects are +encrypted using 128 bit AES in CTR mode. The key material is processed +through the [Vault transit secret engine](/vault/docs/secrets/transit), +which uses the default transit encryption cipher (AES-GCM with a 256-bit AES key +and a 96-bit nonce), and stored alongside the object. This pattern is called envelope encryption. + +The Vault transit secret engine's +[datakey generation](/vault/api-docs/secret/transit#generate-data-key) creates the encryption key material using bit material from the kernel's cryptographically secure pseudo-random +number generator (CSPRNG) as the `context` value. Blob storage encryption generates a unique key for each object and relies on envelope encryption, so Vault does not rotate the encryption key material for individual objects. The root encryption keys within the envelope encryption scheme are rotated automatically by HCP Terraform every 365 days. These keys are not automatically rotated within TFE. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/aws.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/aws.mdx new file mode 100644 index 0000000000..f777c0c65e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/aws.mdx @@ -0,0 +1,158 @@ +--- +page_title: AWS resources included in cost estimation in Terraform Enterprise +description: Learn which AWS resources Terraform Enterprise includes in cost estimation. +source: terraform-docs-common +--- + +# AWS resources included in cost estimation + +HCP Terraform can estimate monthly costs for many AWS Terraform resources. + +-> **Note:** Terraform Enterprise requires AWS credentials to support cost estimation. These credentials are configured at the instance level, not the organization level. See the [Application Administration docs](/terraform/enterprise/admin/application/integration) for more details. + +## Supported Resources + +Cost estimation supports the following resources. Not all possible values for attributes of each resource are supported, ex. newer instance types or EBS volume types. + +| Resource | Incurs Cost | +| ------------------------------------------- | ----------- | +| `aws_alb` | X | +| `aws_autoscaling_group` | X | +| `aws_cloudhsm_v2_hsm` | X | +| `aws_cloudwatch_dashboard` | X | +| `aws_cloudwatch_metric_alarm` | X | +| `aws_db_instance` | X | +| `aws_dynamodb_table` | X | +| `aws_ebs_volume` | X | +| `aws_elasticache_cluster` | X | +| `aws_elasticsearch_domain` | X | +| `aws_elb` | X | +| `aws_instance` | X | +| `aws_kms_key` | X | +| `aws_lb` | X | +| `aws_rds_cluster_instance` | X | +| `aws_acm_certificate_validation` | | +| `aws_alb_listener` | | +| `aws_alb_listener_rule` | | +| `aws_alb_target_group` | | +| `aws_alb_target_group_attachment` | | +| `aws_api_gateway_api_key` | | +| `aws_api_gateway_deployment` | | +| `aws_api_gateway_integration` | | +| `aws_api_gateway_integration_response` | | +| `aws_api_gateway_method` | | +| `aws_api_gateway_method_response` | | +| `aws_api_gateway_resource` | | +| `aws_api_gateway_usage_plan_key` | | +| `aws_appautoscaling_policy` | | +| `aws_appautoscaling_target` | | +| `aws_autoscaling_lifecycle_hook` | | +| `aws_autoscaling_policy` | | +| `aws_cloudformation_stack` | | +| `aws_cloudfront_distribution` | | +| `aws_cloudfront_origin_access_identity` | | +| `aws_cloudwatch_event_rule` | | +| `aws_cloudwatch_event_target` | | +| `aws_cloudwatch_log_group` | | +| `aws_cloudwatch_log_metric_filter` | | +| `aws_cloudwatch_log_stream` | | +| `aws_cloudwatch_log_subscription_filter` | | +| `aws_codebuild_webhook` | | +| `aws_codedeploy_deployment_group` | | +| `aws_cognito_identity_provider` | | +| `aws_cognito_user_pool` | | +| `aws_cognito_user_pool_client` | | +| `aws_cognito_user_pool_domain` | | +| `aws_config_config_rule` | | +| `aws_customer_gateway` | | +| `aws_db_parameter_group` | | +| `aws_db_subnet_group` | | +| `aws_dynamodb_table_item` | | +| `aws_ecr_lifecycle_policy` | | +| `aws_ecr_repository_policy` | | +| `aws_ecs_cluster` | | +| `aws_ecs_task_definition` | | +| `aws_efs_mount_target` | | +| `aws_eip_association` | | +| `aws_elastic_beanstalk_application` | | +| `aws_elastic_beanstalk_application_version` | | +| `aws_elastic_beanstalk_environment` | | +| `aws_elasticache_parameter_group` | | +| `aws_elasticache_subnet_group` | | +| `aws_flow_log` | | +| `aws_iam_access_key` | | +| `aws_iam_account_alias` | | +| `aws_iam_account_password_policy` | | +| `aws_iam_group` | | +| `aws_iam_group_membership` | | +| `aws_iam_group_policy` | | +| `aws_iam_group_policy_attachment` | | +| `aws_iam_instance_profile` | | +| `aws_iam_policy` | | +| `aws_iam_policy_attachment` | | +| `aws_iam_role` | | +| `aws_iam_role_policy` | | +| `aws_iam_role_policy_attachment` | | +| `aws_iam_saml_provider` | | +| `aws_iam_service_linked_role` | | +| `aws_iam_user` | | +| `aws_iam_user_group_membership` | | +| `aws_iam_user_login_profile` | | +| `aws_iam_user_policy` | | +| `aws_iam_user_policy_attachment` | | +| `aws_iam_user_ssh_key` | | +| `aws_internet_gateway` | | +| `aws_key_pair` | | +| `aws_kms_alias` | | +| `aws_lambda_alias` | | +| `aws_lambda_event_source_mapping` | | +| `aws_lambda_function` | | +| `aws_lambda_layer_version` | | +| `aws_lambda_permission` | | +| `aws_launch_configuration` | | +| `aws_lb_listener` | | +| `aws_lb_listener_rule` | | +| `aws_lb_target_group` | | +| `aws_lb_target_group_attachment` | | +| `aws_network_acl` | | +| `aws_network_acl_rule` | | +| `aws_network_interface` | | +| `aws_placement_group` | | +| `aws_rds_cluster_parameter_group` | | +| `aws_route` | | +| `aws_route53_record` | | +| `aws_route53_zone_association` | | +| `aws_route_table` | | +| `aws_route_table_association` | | +| `aws_s3_bucket` | | +| `aws_s3_bucket_notification` | | +| `aws_s3_bucket_object` | | +| `aws_s3_bucket_policy` | | +| `aws_s3_bucket_public_access_block` | | +| `aws_security_group` | | +| `aws_security_group_rule` | | +| `aws_service_discovery_service` | | +| `aws_sfn_state_machine` | | +| `aws_sns_topic` | | +| `aws_sns_topic_subscription` | | +| `aws_sqs_queue` | | +| `aws_sqs_queue_policy` | | +| `aws_ssm_maintenance_window` | | +| `aws_ssm_maintenance_window_target` | | +| `aws_ssm_maintenance_window_task` | | +| `aws_ssm_parameter` | | +| `aws_subnet` | | +| `aws_volume_attachment` | | +| `aws_vpc` | | +| `aws_vpc_dhcp_options` | | +| `aws_vpc_dhcp_options_association` | | +| `aws_vpc_endpoint` | | +| `aws_vpc_endpoint_route_table_association` | | +| `aws_vpc_endpoint_service` | | +| `aws_vpc_ipv4_cidr_block_association` | | +| `aws_vpc_peering_connection_accepter` | | +| `aws_vpc_peering_connection_options` | | +| `aws_vpn_connection_route` | | +| `aws_waf_ipset` | | +| `aws_waf_rule` | | +| `aws_waf_web_acl` | | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/azure.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/azure.mdx new file mode 100644 index 0000000000..5647698512 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/azure.mdx @@ -0,0 +1,56 @@ +--- +page_title: Azure resources included in cost estimation in Terraform Enterprise +description: Learn which Azure resources Terraform Enterprise includes in cost estimation. +source: terraform-docs-common +--- + +# Azure resources included in cost estimation + +HCP Terraform can estimate monthly costs for many Azure Terraform resources. + +-> **Note:** Terraform Enterprise requires Azure credentials to support cost estimation. These credentials are configured at the instance level, not the organization level. See the [Application Administration docs](/terraform/enterprise/admin/application/integration) for more details. + +## Supported Resources + +Cost estimation supports the following resources. Not all possible values for attributes of each resource are supported, ex. newer VM sizes or managed disk types. + +| Resource | Incurs Cost | +| ------------------------------------------------------ | ----------- | +| `azurerm_app_service_custom_hostname_binding` | X | +| `azurerm_app_service_environment` | X | +| `azurerm_app_service_plan` | X | +| `azurerm_app_service_virtual_network_swift_connection` | X | +| `azurerm_cosmosdb_sql_database` | X | +| `azurerm_databricks_workspace` | X | +| `azurerm_firewall` | X | +| `azurerm_hdinsight_hadoop_cluster` | X | +| `azurerm_hdinsight_hbase_cluster` | X | +| `azurerm_hdinsight_interactive_query_cluster` | X | +| `azurerm_hdinsight_kafka_cluster` | X | +| `azurerm_hdinsight_spark_cluster` | X | +| `azurerm_integration_service_environment` | X | +| `azurerm_linux_virtual_machine` | X | +| `azurerm_linux_virtual_machine_scale_set` | X | +| `azurerm_managed_disk` | X | +| `azurerm_mariadb_server` | X | +| `azurerm_mssql_elasticpool` | X | +| `azurerm_mysql_server` | X | +| `azurerm_postgresql_server` | X | +| `azurerm_sql_database` | X | +| `azurerm_virtual_machine` | X | +| `azurerm_virtual_machine_scale_set` | X | +| `azurerm_windows_virtual_machine` | X | +| `azurerm_windows_virtual_machine_scale_set` | X | +| `azurerm_app_service` | | +| `azurerm_cosmosdb_account` | | +| `azurerm_cosmosdb_sql_container` | | +| `azurerm_cosmosdb_table` | | +| `azurerm_mysql_database` | | +| `azurerm_network_security_group` | | +| `azurerm_postgresql_database` | | +| `azurerm_resource_group` | | +| `azurerm_sql_server` | | +| `azurerm_sql_virtual_network_rule` | | +| `azurerm_subnet` | | +| `azurerm_subnet_route_table_association` | | +| `azurerm_virtual_network` | | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/gcp.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/gcp.mdx new file mode 100644 index 0000000000..e1660de815 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/gcp.mdx @@ -0,0 +1,42 @@ +--- +page_title: GCP resources included in cost estimation in Terraform Enterprise +description: Learn which GCP resources Terraform Enterprise includes in cost estimation. +source: terraform-docs-common +--- + +# GCP resources included in cost estimation + +HCP Terraform can estimate monthly costs for many GCP Terraform resources. + +-> **Note:** Terraform Enterprise requires GCP credentials to support cost estimation. These credentials are configured at the instance level, not the organization level. See the [Application Administration docs](/terraform/enterprise/admin/application/integration) for more details. + +## Supported Resources + +Cost estimation supports the following resources. Not all possible values for attributes of each resource are supported, ex. new or custom machine types. + +| Resource | Incurs Cost | +| --------------------------------------- | ----------- | +| `google_compute_disk` | X | +| `google_compute_instance` | X | +| `google_sql_database_instance` | X | +| `google_billing_account_iam_member` | | +| `google_compute_address` | | +| `google_compute_subnetwork_iam_member` | | +| `google_folder_iam_member` | | +| `google_folder_iam_policy` | | +| `google_kms_crypto_key_iam_member` | | +| `google_kms_key_ring_iam_member` | | +| `google_kms_key_ring_iam_policy` | | +| `google_organization_iam_member` | | +| `google_project` | | +| `google_project_iam_member` | | +| `google_project_iam_policy` | | +| `google_project_service` | | +| `google_pubsub_subscription_iam_member` | | +| `google_pubsub_subscription_iam_policy` | | +| `google_pubsub_topic_iam_member` | | +| `google_service_account` | | +| `google_service_account_iam_member` | | +| `google_service_account_key` | | +| `google_storage_bucket_iam_member` | | +| `google_storage_bucket_iam_policy` | | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/index.mdx new file mode 100644 index 0000000000..d81c7e6c17 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/cost-estimation/index.mdx @@ -0,0 +1,58 @@ +--- +page_title: Cost estimation overview for Terraform Enterprise +description: >- + Terraform Enterprise can estimate the total cost and delta of resources from + your Terraform configuration. Use cost estimation to get hourly and monthly + cost estimates for each resource. +source: terraform-docs-common +--- + +# Cost estimation overview + +> **Hands-on:** Try the [Control Costs with Policies](/terraform/tutorials/cloud-get-started/cost-estimation) tutorial to practice enabling cost estimation and define a policy to check the total monthly delta. + +HCP Terraform provides cost estimates for many resources found in your Terraform configuration. For each resource an hourly and monthly cost is shown, along with the monthly delta. The total cost and delta of all estimable resources is also shown. + +## Enabling Cost Estimation + +HCP Terraform disables cost estimation by default. To enable cost estimation: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, then navigate to the organization where you want to enable cost estimation. +2. Choose **Settings** from the sidebar, then **Cost Estimation**. +3. Toggle the **Enable cost estimation for all workspaces** setting. +4. Click **Update settings**. + +## Viewing a Cost Estimate + +When enabled, HCP Terraform performs a cost estimate for every run. Estimated costs appear in the run UI as an extra run phase, between the plan and apply. + +The estimate displays a total monthly cost by default; you can expand the estimate to see an itemized list of resource costs, as well as the list of unestimated resources. + +Note that this is just an estimate; some resources don't have cost information available or have unpredictable usage-based pricing. Supported resources are listed in this document's sub-pages. + +## Verifying Costs in Policies + +You can use a Sentinel policy to validate your configuration's cost estimates using the [`tfrun`](/terraform/enterprise/policy-enforcement/import-reference/tfrun) import. The example policy below checks that the new cost delta is no more than $100. A new `t3.nano` instance should be well below that. A `decimal` import is available for more accurate math when working with currency numbers. + +```python +import "tfrun" +import "decimal" + +delta_monthly_cost = decimal.new(tfrun.cost_estimate.delta_monthly_cost) + +if delta_monthly_cost.greater_than(100) { + print("This policy prevents a user from increasing their spending by more than $100 per month in a single run without a warning.") +} + +main = rule { + delta_monthly_cost.less_than(100) +} +``` + +## Supported Resources + +Cost estimation in HCP Terraform supports Terraform resources within three major cloud providers. + +- [AWS](/terraform/enterprise/cost-estimation/aws) +- [GCP](/terraform/enterprise/cost-estimation/gcp) +- [Azure](/terraform/enterprise/cost-estimation/azure) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/aws-service-catalog/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/aws-service-catalog/index.mdx new file mode 100644 index 0000000000..e06a14e929 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/aws-service-catalog/index.mdx @@ -0,0 +1,27 @@ +--- +page_title: Terraform Enterprise for AWS Service Catalog overview +description: >- + Terraform Enterprise for AWS Service Catalog lets you provision infrastructure + with HCP Terraform inside AWS Service Catalog. +source: terraform-docs-common +--- + +# HCP Terraform for AWS Service Catalog overview + +This integration allows administrators to curate a portfolio of pre-approved Terraform configurations on AWS Service Catalog. This enables end users like engineers, database administrators, and data scientists to deploy these Terraform configurations with a single action from the AWS interface. By combining HCP Terraform with AWS Service Catalog, we’re combining a self-service interface that many customers are familiar with, AWS Service Catalog, with the existing workflows and policy guardrails of HCP Terraform. + + + +@include 'tfc-package-callouts/aws-service-catalog.mdx' + + + +## Installation & Configuration + +To start using this integration, you'll need to install the [AWS Service Catalog Engine for Terraform Cloud](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc) provided by HashiCorp on GitHub by following the [setup instructions](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc#getting-started) provided in the README. If you run into any setup troubles along the way, the README also includes [troubleshooting steps](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc#troubleshooting) that should help resolve common issues that you may encounter. + +With the engine installed, the necessary code and infrastructure to integrate the HCP Terraform engine with AWS Service Catalog will automatically be configured. The setup can be completed in just a few minutes, and it only needs to be done once. Once the setup is complete, you can immediately start using AWS Service Catalog to develop and manage AWS Service Catalog products, and make them accessible to your end users across all your accounts. + +## Usage + +You can access this new feature through the AWS Service Catalog console in any AWS regions where AWS Service Catalog is supported and follow the AWS Service Catalog Administrator Guide to [create your first Terraform product](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/getstarted-product-Terraform.html). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/index.mdx new file mode 100644 index 0000000000..dc8851bfba --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/index.mdx @@ -0,0 +1,26 @@ +--- +page_title: Integrations overview for Terraform Enterprise +description: >- + Use Terraform Enterprise integrations to connect HCP Terraform with + third-party platforms and systems. +source: terraform-docs-common +--- + +# Overview + +The HCP Terraform ecosystem features a variety of integrations to let HCP +Terraform connect with third-party systems and platforms. The following list +contains HashiCorp's official HCP Terraform integrations, which use HCP +Terraform's native APIs: + +- The [HCP Terraform Operator for Kubernetes](/terraform/enterprise/integrations/kubernetes) integration can manage HCP Terraform resources with Kubernetes custom resources. +- The [ServiceNow Service Catalog for Terraform](/terraform/enterprise/integrations/service-now/service-catalog-terraform) lets you provision self-serve infrastructure using ServiceNow. +- The [ServiceNow Service Graph Connector for Terraform](/terraform/enterprise/integrations/service-now/service-graph) integration lets you securely import HCP Terraform resources into your ServiceNow instance. +- The [HCP Terraform for Splunk](/terraform/enterprise/integrations/splunk) integration lets you pull HCP Terraform logs into Splunk. +- The [HCP Terraform for AWS Service Catalog](/terraform/enterprise/integrations/aws-service-catalog) integration lets you create pre-approved Terraform configurations on the AWS Service Catalog. + +If the platform you want to integrate HCP Terraform with does not have an +official integration, you can build a custom run task to integrate with a tool +of your choice. Run tasks can access plan details, display custom messages in +the run pipeline, and prevent runs from applying. Learn more about [Run +tasks](/terraform/enterprise/integrations/run-tasks). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/annotations-and-labels.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/annotations-and-labels.mdx new file mode 100644 index 0000000000..e38bdb08c1 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/annotations-and-labels.mdx @@ -0,0 +1,26 @@ +--- +page_title: Terraform Enterprise Operator for Kubernetes annotations and labels +description: >- + Use annotations and labels with the Terraform Enterprise Operator for + Kubernetes to manage Terraform runs. +source: terraform-docs-common +--- + +# HCP Terraform Operator for Kubernetes annotations and labels + +This topic contains reference information about the annotations and labels the HCP Terraform and Terraform Enterprise operators use for Kubernetes. + +## Annotations + +| Annotation key | Target resources | Possible values | Description | +| -------------------------------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `workspace.app.terraform.io/run-new` | Workspace | `"true"` | Set this annotation to `"true"` to trigger a new run. Example: `kubectl annotate workspace workspace.app.terraform.io/run-new="true"`. | +| `workspace.app.terraform.io/run-type` | Workspace | `plan`, `apply`, `refresh` | Specifies the run type. Changing this annotation does not start a new run. Refer to [Run Modes and Options](/terraform/enterprise/run/modes-and-options) for more information. Defaults to `"plan"`. | +| `workspace.app.terraform.io/run-terraform-version` | Workspace | Any valid Terraform version | Specifies the Terraform version to use. Changing this annotation does not start a new run. Only valid when the annotation `workspace.app.terraform.io/run-type` is set to `plan`. Defaults to the Workspace version. | + +## Labels + +| Label key | Target resources | Possible values | Description | +| -------------------------------------- | ---------------- | ------------------------ | ------------------------------------------------------------------------------------------- | +| `agentpool.app.terraform.io/pool-name` | Pod[Agent] | Any valid AgentPool name | Associate the resource with a specific agent pool by specifying the name of the agent pool. | +| `agentpool.app.terraform.io/pool-id` | Pod[Agent] | Any valid AgentPool ID | Associate the resource with a specific agent pool by specifying the ID of the agent pool. | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/api-reference.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/api-reference.mdx new file mode 100644 index 0000000000..1c1be52818 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/api-reference.mdx @@ -0,0 +1,796 @@ +--- +page_title: Terraform Enterprise Operator for Kubernetes API reference +description: >- + Use the Terraform Enterprise Operator for Kubernetes API to manage HCP + Terraform workspaces, modules, and agent pools. +source: terraform-docs-common +--- + +# HCP Terraform Operator for Kubernetes API reference + +## Packages + +- [app.terraform.io/v1alpha2](#appterraformiov1alpha2) + +## app.terraform.io/v1alpha2 + +Package v1alpha2 contains API Schema definitions for the app v1alpha2 API group. + +### Resource Types + +- [AgentPool](#agentpool) +- [Module](#module) +- [Project](#project) +- [Workspace](#workspace) + +#### AgentDeployment + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) + +| Field | Description | +| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| `replicas` _integer_ | | +| `spec` _[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#podspec-v1-core)_ | | +| `annotations` _object (keys:string, values:string)_ | The annotations that the operator will apply to the pod template in the deployment. | +| `labels` _object (keys:string, values:string)_ | The labels that the operator will apply to the pod template in the deployment. | + +#### AgentDeploymentAutoscaling + +AgentDeploymentAutoscaling allows you to configure the operator to scale the deployment for an AgentPool up and down to meet demand. + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) + +| Field | Description | +| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `maxReplicas` _integer_ | MaxReplicas is the maximum number of replicas for the Agent deployment. | +| `minReplicas` _integer_ | MinReplicas is the minimum number of replicas for the Agent deployment. | +| `targetWorkspaces` _[TargetWorkspace](#targetworkspace)_ | TargetWorkspaces is a list of HCP Terraform Workspaces which the agent pool should scale up to meet demand. When this field is omitted the autoscaler will target all workspaces that are associated with the AgentPool. | +| `cooldownPeriodSeconds` _integer_ | CooldownPeriodSeconds is the time to wait between scaling events. Defaults to 300. | +| `cooldownPeriod` _[AgentDeploymentAutoscalingCooldownPeriod](#agentdeploymentautoscalingcooldownperiod)_ | CoolDownPeriod configures the period to wait between scaling up and scaling down | + +#### AgentDeploymentAutoscalingCooldownPeriod + +AgentDeploymentAutoscalingCooldownPeriod configures the period to wait between scaling up and scaling down, + +_Appears in:_ + +- [AgentDeploymentAutoscaling](#agentdeploymentautoscaling) + +| Field | Description | +| ---------------------------- | --------------------------------------------------------- | +| `scaleUpSeconds` _integer_ | ScaleUpSeconds is the time to wait before scaling up. | +| `scaleDownSeconds` _integer_ | ScaleDownSeconds is the time to wait before scaling down. | + +#### AgentDeploymentAutoscalingStatus + +AgentDeploymentAutoscalingStatus + +_Appears in:_ + +- [AgentPoolStatus](#agentpoolstatus) + +| Field | Description | +| -------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| `desiredReplicas` _integer_ | Desired number of agent replicas | +| `lastScalingEvent` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#time-v1-meta)_ | Last time the agent pool was scaled | + +#### AgentPool + +AgentPool manages HCP Terraform Agent Pools, HCP Terraform Agent Tokens and can perform HCP Terraform Agent scaling. + +More information: + +- [Manage agent pools](/terraform/cloud-docs/agents/agent-pools) +- [Agent API tokens](/terraform/enterprise/users-teams-organizations/api-tokens#agent-api-tokens) +- [HCP Terraform agents](/terraform/cloud-docs/agents) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `AgentPool` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[AgentPoolSpec](#agentpoolspec)_ | | + +#### AgentPoolSpec + +AgentPoolSpec defines the desired state of AgentPool. + +_Appears in:_ + +- [AgentPool](#agentpool) + +| Field | Description | +| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Agent Pool name. [More information](/terraform/cloud-docs/agents/agent-pools). | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `agentTokens` _[AgentToken](#agenttoken) array_ | List of the agent tokens to generate. | +| `agentDeployment` _[AgentDeployment](#agentdeployment)_ | Agent deployment settings | +| `autoscaling` _[AgentDeploymentAutoscaling](#agentdeploymentautoscaling)_ | Agent deployment settings | + +#### AgentToken + +Agent Token is a secret token that a HCP Terraform Agent is used to connect to the HCP Terraform Agent Pool. In `spec` only the field `Name` is allowed, the rest are used in `status`. + +More information: + +- [HCP Terraform agents](/terraform/cloud-docs/agents) + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) +- [AgentPoolStatus](#agentpoolstatus) + +| Field | Description | +| ---------------------- | ------------------------------------------------ | +| `name` _string_ | Agent Token name. | +| `id` _string_ | Agent Token ID. | +| `createdAt` _integer_ | Timestamp of when the agent token was created. | +| `lastUsedAt` _integer_ | Timestamp of when the agent token was last used. | + +#### ConfigurationVersionStatus + +A configuration version is a resource used to reference the uploaded configuration files. + +More information: + +- [Configuration versions API reference](/terraform/enterprise/api-docs/configuration-versions) +- [The API-driven run workflow](/terraform/enterprise/run/api) + +_Appears in:_ + +- [ModuleStatus](#modulestatus) + +| Field | Description | +| ------------- | ------------------------- | +| `id` _string_ | Configuration Version ID. | + +#### ConsumerWorkspace + +ConsumerWorkspace allows access to the state for specific workspaces within the same organization. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Remote state access controls](/terraform/enterprise/workspaces/state#remote-state-access-controls) + +_Appears in:_ + +- [RemoteStateSharing](#remotestatesharing) + +| Field | Description | +| --------------- | -------------------------------------------------------------- | +| `id` _string_ | Consumer Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` | +| `name` _string_ | Consumer Workspace name. | + +#### CustomPermissions + +Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. + +More information: + +- [Custom workspace permissions](/terraform/enterprise/users-teams-organizations/permissions#custom-workspace-permissions) + +_Appears in:_ + +- [TeamAccess](#teamaccess) + +| Field | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `runs` _string_ | Run access. Must be one of the following values: `apply`, `plan`, `read`. Default: `read`. | +| `runTasks` _boolean_ | Manage Workspace Run Tasks. Default: `false`. | +| `sentinel` _string_ | Download Sentinel mocks. Must be one of the following values: `none`, `read`. Default: `none`. | +| `stateVersions` _string_ | State access. Must be one of the following values: `none`, `read`, `read-outputs`, `write`. Default: `none`. | +| `variables` _string_ | Variable access. Must be one of the following values: `none`, `read`, `write`. Default: `none`. | +| `workspaceLocking` _boolean_ | Lock/unlock workspace. Default: `false`. | + +#### CustomProjectPermissions + +Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. + +More information: + +- [Custom project permissions](/terraform/enterprise/users-teams-organizations/permissions#custom-project-permissions) +- [General workspace permissions](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) + +_Appears in:_ + +- [ProjectTeamAccess](#projectteamaccess) + +| Field | Description | +| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `projectAccess` _[ProjectSettingsPermissionType](#projectsettingspermissiontype)_ | Project access. Must be one of the following values: `delete`, `read`, `update`. Default: `read`. | +| `teamManagement` _[ProjectTeamsPermissionType](#projectteamspermissiontype)_ | Team management. Must be one of the following values: `manage`, `none`, `read`. Default: `none`. | +| `createWorkspace` _boolean_ | Allow users to create workspaces in the project. This grants read access to all workspaces in the project. Default: `false`. | +| `deleteWorkspace` _boolean_ | Allows users to delete workspaces in the project. Default: `false`. | +| `moveWorkspace` _boolean_ | Allows users to move workspaces out of the project. A user must have this permission on both the source and destination project to successfully move a workspace from one project to another. Default: `false`. | +| `lockWorkspace` _boolean_ | Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", users must have this permission to perform local CLI runs using the workspace's state. Default: `false`. | +| `runs` _[WorkspaceRunsPermissionType](#workspacerunspermissiontype)_ | Run access. Must be one of the following values: `apply`, `plan`, `read`. Default: `read`. | +| `runTasks` _boolean_ | Manage Workspace Run Tasks. Default: `false`. | +| `sentinelMocks` _[WorkspaceSentinelMocksPermissionType](#workspacesentinelmockspermissiontype)_ | Download Sentinel mocks. Must be one of the following values: `none`, `read`. Default: `none`. | +| `stateVersions` _[WorkspaceStateVersionsPermissionType](#workspacestateversionspermissiontype)_ | State access. Must be one of the following values: `none`, `read`, `read-outputs`, `write`. Default: `none`. | +| `variables` _[WorkspaceVariablesPermissionType](#workspacevariablespermissiontype)_ | Variable access. Must be one of the following values: `none`, `read`, `write`. Default: `none`. | + +#### DeletionPolicy + +_Underlying type:_ _string_ + +DeletionPolicy defines the strategy the Kubernetes operator uses when you delete a resource, either manually or by a system event. + +You must use one of the following values: + +- `retain`: When you delete the custom resource, the operator does not delete the workspace. +- `soft`: Attempts to delete the associated workspace only if it does not contain any managed resources. +- `destroy`: Executes a destroy operation to remove all resources managed by the associated workspace. Once the destruction of these resources is successful, the operator deletes the workspace, and then deletes the custom resource. +- `force`: Forcefully and immediately deletes the workspace and the custom resource. + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +#### Module + +Module implements API-driven Run Workflows. + +More information: + +- [The API-driven run workflow](/terraform/enterprise/run/api) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `Module` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[ModuleSpec](#modulespec)_ | | + +#### ModuleOutput + +Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive). + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| --------------------- | ----------------------------------------------------------------- | +| `name` _string_ | Output name must match with the module output. | +| `sensitive` _boolean_ | Specify whether or not the output is sensitive. Default: `false`. | + +#### ModuleSource + +Module source and version to execute. + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| ------------------ | ------------------------------------------------------------------------------------------- | +| `source` _string_ | Non local Terraform module source. [More information](/terraform/language/modules/sources). | +| `version` _string_ | Terraform module version. | + +#### ModuleSpec + +ModuleSpec defines the desired state of Module. + +_Appears in:_ + +- [Module](#module) + +| Field | Description | +| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `module` _[ModuleSource](#modulesource)_ | Module source and version to execute. | +| `workspace` _[ModuleWorkspace](#moduleworkspace)_ | Workspace to execute the module. | +| `name` _string_ | Name of the module that will be uploaded and executed. Default: `this`. | +| `variables` _[ModuleVariable](#modulevariable) array_ | Variables to pass to the module, they must exist in the Workspace. | +| `outputs` _[ModuleOutput](#moduleoutput) array_ | Module outputs to store in ConfigMap(non-sensitive) or Secret(sensitive). | +| `destroyOnDeletion` _boolean_ | Specify whether or not to execute a Destroy run when the object is deleted from the Kubernetes. Default: `false`. | +| `restartedAt` _string_ | Allows executing a new Run without changing any Workspace or Module attributes. Example: ``kubectl patch KIND NAME --type=merge --patch '{"spec": \{"restartedAt": "'\`date -u -Iseconds\`'"\}\}'`` | + +#### ModuleVariable + +Variables to pass to the module. + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| --------------- | ------------------------------------------ | +| `name` _string_ | Variable name must exist in the Workspace. | + +#### ModuleWorkspace + +Workspace to execute the module. Only one of the fields `ID` or `Name` is allowed. At least one of the fields `ID` or `Name` is mandatory. + +_Appears in:_ + +- [ModuleSpec](#modulespec) + +| Field | Description | +| --------------- | ------------------------------------------------------------ | +| `id` _string_ | Module Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` | +| `name` _string_ | Module Workspace Name. | + +#### Notification + +Notifications allow you to send messages to other applications based on run and workspace events. + +More information: + +- [Workspace notifications](/terraform/enterprise/workspaces/settings/notifications) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Notification name. | +| `type` _[NotificationDestinationType](#notificationdestinationtype)_ | The type of the notification. Must be one of the following values: `email`, `generic`, `microsoft-teams`, `slack`. | +| `enabled` _boolean_ | Whether the notification configuration should be enabled or not. Default: `true`. | +| `token` _string_ | The token of the notification. | +| `triggers` _[NotificationTrigger](#notificationtrigger) array_ | The list of run events that will trigger notifications. Trigger represents the different TFC notifications that can be sent as a run's progress transitions between different states. There are two categories of triggers: - Health Events: `assessment:check_failure`, `assessment:drifted`, `assessment:failed`. - Run Events: `run:applying`, `run:completed`, `run:created`, `run:errored`, `run:needs_attention`, `run:planning`. | +| `url` _string_ | The URL of the notification. Must match pattern: `^https?://.*` | +| `emailAddresses` _string array_ | The list of email addresses that will receive notification emails. It is only available for Terraform Enterprise users. It is not available in HCP Terraform. | +| `emailUsers` _string array_ | The list of users belonging to the organization that will receive notification emails. | + +#### NotificationTrigger + +_Underlying type:_ _string_ + +NotificationTrigger represents the different TFC notifications that can be sent as a run's progress transitions between different states. This must be aligned with go-tfe type `NotificationTriggerType`. + +Must be one of the following values: `run:applying`, `assessment:check_failure`, `run:completed`, `run:created`, `assessment:drifted`, `run:errored`, `assessment:failed`, `run:needs_attention`, `run:planning`. + +_Appears in:_ + +- [Notification](#notification) + +#### OutputStatus + +Outputs status. + +_Appears in:_ + +- [ModuleStatus](#modulestatus) + +| Field | Description | +| ---------------- | -------------------------------------------------- | +| `runID` _string_ | Run ID of the latest run that updated the outputs. | + +#### PlanStatus + +_Appears in:_ + +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| --------------------------- | ------------------------------------------------------- | +| `id` _string_ | Latest plan-only/speculative plan HCP Terraform run ID. | +| `terraformVersion` _string_ | The version of Terraform to use for this run. | + +#### Project + +Project manages HCP Terraform Projects. + +More information: + +- [Manage projects](/terraform/enterprise/projects/manage) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `Project` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[ProjectSpec](#projectspec)_ | | + +#### ProjectSpec + +ProjectSpec defines the desired state of Project. + +More information: + +- [Manage projects](/terraform/enterprise/workspaces/organize-workspaces-with-projects) + +_Appears in:_ + +- [Project](#project) + +| Field | Description | +| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `name` _string_ | Name of the Project. | +| `teamAccess` _[ProjectTeamAccess](#projectteamaccess) array_ | HCP Terraform's access model is team-based. In order to perform an action within a HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. You can assign project-specific permissions to teams. More information: [Manage projects](/terraform/enterprise/workspaces/organize-workspaces-with-projects#permissions) and [Project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions). | + +#### ProjectTeamAccess + +HCP Terraform's access model is team-based. In order to perform an action within a HCP Terraform organization, users must belong to a team that has been granted the appropriate permissions. You can assign project-specific permissions to teams. + +More information: + +- [Manage projects](/terraform/enterprise/workspaces/organize-workspaces-with-projects#permissions) +- [Project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) + +_Appears in:_ + +- [ProjectSpec](#projectspec) + +| Field | Description | +| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `team` _[Team](#team)_ | Team to grant access. [More information](/terraform/enterprise/users-teams-organizations/teams). | +| `access` _[TeamProjectAccessType](#teamprojectaccesstype)_ | There are two ways to choose which permissions a given team has on a project: fixed permission sets, and custom permissions. Must be one of the following values: `admin`, `custom`, `maintain`, `read`, `write`. More information: [Project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) and [General project permissions](/terraform/enterprise/users-teams-organizations/permissions#general-project-permissions). | +| `custom` _[CustomProjectPermissions](#customprojectpermissions)_ | Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/enterprise/users-teams-organizations/permissions#custom-project-permissions). | + +#### RemoteStateSharing + +RemoteStateSharing allows remote state access between workspaces. By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. + +More information: + +- [Accessing state from other workspaces](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | +| `allWorkspaces` _boolean_ | Allow access to the state for all workspaces within the same organization. Default: `false`. | +| `workspaces` _[ConsumerWorkspace](#consumerworkspace) array_ | Allow access to the state for specific workspaces within the same organization. | + +#### RunStatus + +_Appears in:_ + +- [ModuleStatus](#modulestatus) +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| ------------------------------- | ------------------------------------------------------- | +| `id` _string_ | Current(both active and finished) HCP Terraform run ID. | +| `configurationVersion` _string_ | The configuration version of this run. | +| `outputRunID` _string_ | Run ID of the latest run that could update the outputs. | + +#### RunTrigger + +RunTrigger allows you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Run triggers](/terraform/enterprise/workspaces/settings/run-triggers) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ------------------------------------------------------------ | +| `id` _string_ | Source Workspace ID. Must match pattern: `^ws-[a-zA-Z0-9]+$` | +| `name` _string_ | Source Workspace Name. | + +#### SSHKey + +SSH key used to clone Terraform modules. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Use SSH Keys for cloning modules](/terraform/enterprise/workspaces/settings/ssh-keys) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ------------------------------------------------------- | +| `id` _string_ | SSH key ID. Must match pattern: `^sshkey-[a-zA-Z0-9]+$` | +| `name` _string_ | SSH key name. | + +#### Tag + +_Underlying type:_ _string_ + +Tags allows you to correlate, organize, and even filter workspaces based on the assigned tags. + +Tags must be one or more characters; can include letters, numbers, colons, hyphens, and underscores; and must begin and end with a letter or number. + +Must match pattern: `^[A-Za-z0-9][A-Za-z0-9:_-]*$` + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +#### TargetWorkspace + +TargetWorkspace is the name or ID of the workspace you want autoscale against. + +_Appears in:_ + +- [AgentDeploymentAutoscaling](#agentdeploymentautoscaling) + +| Field | Description | +| ----------------------- | --------------------------------------------------------------------------------------- | +| `id` _string_ | Workspace ID | +| `name` _string_ | Workspace Name | +| `wildcardName` _string_ | Wildcard Name to match match workspace names using `*` on name suffix, prefix, or both. | + +#### Team + +Teams are groups of HCP Terraform users within an organization. If a user belongs to at least one team in an organization, they are considered a member of that organization. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Teams overview](/terraform/enterprise/users-teams-organizations/teams) + +_Appears in:_ + +- [ProjectTeamAccess](#projectteamaccess) +- [TeamAccess](#teamaccess) + +| Field | Description | +| --------------- | -------------------------------------------------- | +| `id` _string_ | Team ID. Must match pattern: `^team-[a-zA-Z0-9]+$` | +| `name` _string_ | Team name. | + +#### TeamAccess + +HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. When a workspace is created, only the owners team and teams with the "manage workspaces" permission can access it, with full admin permissions. These teams' access can't be removed from a workspace. + +More information: + +- [Manage access to workspaces](/terraform/enterprise/workspaces/settings/access) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `team` _[Team](#team)_ | Team to grant access. [More information](/terraform/enterprise/users-teams-organizations/teams). | +| `access` _string_ | There are two ways to choose which permissions a given team has on a workspace: fixed permission sets, and custom permissions. Must be one of the following values: `admin`, `custom`, `plan`, `read`, `write`. [More information](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). | +| `custom` _[CustomPermissions](#custompermissions)_ | Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. [More information](/terraform/enterprise/users-teams-organizations/permissions#custom-workspace-permissions). | + +#### Token + +Token refers to a Kubernetes Secret object within the same namespace as the Workspace object + +_Appears in:_ + +- [AgentPoolSpec](#agentpoolspec) +- [ModuleSpec](#modulespec) +- [ProjectSpec](#projectspec) +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | Selects a key of a secret in the workspace's namespace | + +#### ValueFrom + +ValueFrom source for the variable's value. Cannot be used if value is not empty. + +_Appears in:_ + +- [Variable](#variable) + +| Field | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | +| `configMapKeyRef` _[ConfigMapKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#configmapkeyselector-v1-core)_ | Selects a key of a ConfigMap. | +| `secretKeyRef` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#secretkeyselector-v1-core)_ | Selects a key of a Secret. | + +#### Variable + +Variables let you customize configurations, modify Terraform's behavior, and store information like provider credentials. + +More information: + +- [Workspace variables](/terraform/enterprise/workspaces/variables) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Name of the variable. | +| `description` _string_ | Description of the variable. | +| `hcl` _boolean_ | Parse this field as HashiCorp Configuration Language (HCL). This allows you to interpolate values at runtime. Default: `false`. | +| `sensitive` _boolean_ | Sensitive variables are never shown in the UI or API. They may appear in Terraform logs if your configuration is designed to output them. Default: `false`. | +| `value` _string_ | Value of the variable. | +| `valueFrom` _[ValueFrom](#valuefrom)_ | Source for the variable's value. Cannot be used if value is not empty. | + +#### VariableSetStatus + +_Appears in:_ + +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| --------------- | ----------- | +| `id` _string_ | | +| `name` _string_ | | + +#### VariableStatus + +_Appears in:_ + +- [WorkspaceStatus](#workspacestatus) + +| Field | Description | +| -------------------- | --------------------------------------------------- | +| `name` _string_ | Name of the variable. | +| `id` _string_ | ID of the variable. | +| `versionID` _string_ | VersionID is a hash of the variable on the TFC end. | +| `valueID` _string_ | ValueID is a hash of the variable on the CRD end. | +| `category` _string_ | Category of the variable. | + +#### VersionControl + +VersionControl settings for the workspace's VCS repository, enabling the UI/VCS-driven run workflow. Omit this argument to utilize the CLI-driven and API-driven workflows, where runs are not driven by webhooks on your VCS provider. + +More information: + +- [UI and VCS-driven run workflow](/terraform/enterprise/run/ui) +- [Connect to VCS Providers](/terraform/enterprise/vcs) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `oAuthTokenID` _string_ | The VCS Connection (OAuth Connection + Token) to use. Must match pattern: `^ot-[a-zA-Z0-9]+$` | +| `repository` _string_ | A reference to your VCS repository in the format `/` where `` and `` refer to the organization and repository in your VCS provider. | +| `branch` _string_ | The repository branch that Run will execute from. This defaults to the repository's default branch (e.g. main). | +| `speculativePlans` _boolean_ | Whether this workspace allows automatic speculative plans on PR. Default: `true`. More information: [Speculative plans on pull requests](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) and [Speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). | + +#### Workspace + +Workspace manages HCP Terraform Workspaces. + +More information: + +- [Workspaces](/terraform/enterprise/workspaces) + +| Field | Description | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion` _string_ | `app.terraform.io/v1alpha2` | +| `kind` _string_ | `Workspace` | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds) | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. [More information](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources) | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[WorkspaceSpec](#workspacespec)_ | | + +#### WorkspaceAgentPool + +AgentPool allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [HCP Terraform agents](/terraform/cloud-docs/agents) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | --------------------------------------------------------- | +| `id` _string_ | Agent Pool ID. Must match pattern: `^apool-[a-zA-Z0-9]+$` | +| `name` _string_ | Agent Pool name. | + +#### WorkspaceProject + +Projects let you organize your workspaces into groups. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Organize workspaces with projects](/terraform/tutorials/cloud/projects) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ---------------------------------------------------- | +| `id` _string_ | Project ID. Must match pattern: `^prj-[a-zA-Z0-9]+$` | +| `name` _string_ | Project name. | + +#### WorkspaceRunTask + +Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. + +Only one of the fields `ID` or `Name` is allowed. + +At least one of the fields `ID` or `Name` is mandatory. + +More information: + +- [Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` _string_ | Run Task ID. Must match pattern: `^task-[a-zA-Z0-9]+$` | +| `name` _string_ | Run Task Name. | +| `enforcementLevel` _string_ | Run Task Enforcement Level. Can be one of `advisory` or `mandatory`. Default: `advisory`. Must be one of the following values: `advisory`, `mandatory` Default: `advisory`. | +| `stage` _string_ | Run Task Stage. Must be one of the following values: `pre_apply`, `pre_plan`, `post_plan`. Default: `post_plan`. | + +#### WorkspaceSpec + +WorkspaceSpec defines the desired state of Workspace. + +_Appears in:_ + +- [Workspace](#workspace) + +| Field | Description | +| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `name` _string_ | Workspace name. | +| `organization` _string_ | Organization name where the Workspace will be created. [More information](/terraform/enterprise/users-teams-organizations/organizations). | +| `token` _[Token](#token)_ | API Token to be used for API calls. | +| `applyMethod` _string_ | Define either change will be applied automatically(auto) or require an operator to confirm(manual). Must be one of the following values: `auto`, `manual`. Default: `manual`. [More information](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply). | +| `allowDestroyPlan` _boolean_ | Allows a destroy plan to be created and applied. Default: `true`. [More information](/terraform/enterprise/workspaces/settings#destruction-and-deletion). | +| `description` _string_ | Workspace description. | +| `agentPool` _[WorkspaceAgentPool](#workspaceagentpool)_ | HCP Terraform Agents allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure. [More information](/terraform/cloud-docs/agents). | +| `executionMode` _string_ | Define where the Terraform code will be executed. Must be one of the following values: `agent`, `local`, `remote`. Default: `remote`. [More information](/terraform/enterprise/workspaces/settings#execution-mode). | +| `runTasks` _[WorkspaceRunTask](#workspaceruntask) array_ | Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. [More information](/terraform/enterprise/workspaces/settings/run-tasks). | +| `tags` _[Tag](#tag) array_ | Workspace tags are used to help identify and group together workspaces. Tags must be one or more characters; can include letters, numbers, colons, hyphens, and underscores; and must begin and end with a letter or number. | +| `teamAccess` _[TeamAccess](#teamaccess) array_ | HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. When a workspace is created, only the owners team and teams with the "manage workspaces" permission can access it, with full admin permissions. These teams' access can't be removed from a workspace. [More information](/terraform/enterprise/workspaces/settings/access). | +| `terraformVersion` _string_ | The version of Terraform to use for this workspace. If not specified, the latest available version will be used. Must match pattern: `^\\d\{1\}\\.\\d\{1,2\}\\.\\d\{1,2\}$` [More information](/terraform/enterprise/workspaces/settings#terraform-version) | +| `workingDirectory` _string_ | The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. [More information](/terraform/enterprise/workspaces/settings#terraform-working-directory) | +| `environmentVariables` _[Variable](#variable) array_ | Terraform Environment variables for all plans and applies in this workspace. Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key. More information: [Workspace variables](/terraform/enterprise/workspaces/variables) and [Environment variables](/terraform/enterprise/workspaces/variables#environment-variables). | +| `terraformVariables` _[Variable](#variable) array_ | Terraform variables for all plans and applies in this workspace. Variables defined within a workspace always overwrite variables from variable sets that have the same type and the same key. More information: [Workspace variables](/terraform/enterprise/workspaces/variables) and [Terraform variables](/terraform/enterprise/workspaces/variables#terraform-variables). | +| `remoteStateSharing` _[RemoteStateSharing](#remotestatesharing)_ | Remote state access between workspaces. By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. [More information](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces). | +| `runTriggers` _[RunTrigger](#runtrigger) array_ | Run triggers allow you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. [More information](/terraform/enterprise/workspaces/settings/run-triggers). | +| `versionControl` _[VersionControl](#versioncontrol)_ | Settings for the workspace's VCS repository, enabling the UI/VCS-driven run workflow. Omit this argument to utilize the CLI-driven and API-driven workflows, where runs are not driven by webhooks on your VCS provider. More information: [UI and VCS-driven run workflow](/terraform/enterprise/run/ui) and [Connect to VCS providers](/terraform/enterprise/vcs) | +| `sshKey` _[SSHKey](#sshkey)_ | SSH key used to clone Terraform modules. [More information](/terraform/enterprise/workspaces/settings/ssh-keys). | +| `notifications` _[Notification](#notification) array_ | Notifications allow you to send messages to other applications based on run and workspace events. [More information](/terraform/enterprise/workspaces/settings/notifications). | +| `project` _[WorkspaceProject](#workspaceproject)_ | Projects let you organize your workspaces into groups. Default: default organization project. [More information](/terraform/tutorials/cloud/projects). | +| `deletionPolicy` _[DeletionPolicy](#deletionpolicy)_ | The Deletion Policy specifies the behavior of the custom resource and its associated workspace when the custom resource is deleted. - `retain`: When you delete the custom resource, the operator does not delete the workspace. - `soft`: Attempts to delete the associated workspace only if it does not contain any managed resources. - `destroy`: Executes a destroy operation to remove all resources managed by the associated workspace. Once the destruction of these resources is successful, the operator deletes the workspace, and then deletes the custom resource. - `force`: Forcefully and immediately deletes the workspace and the custom resource. Default: `retain`. | +| `variableSets` _[WorkspaceVariableSet](#workspacevariableset) array_ | HCP Terraform variable sets let you reuse variables in an efficient and centralized way. [More information](/terraform/tutorials/cloud/cloud-multiple-variable-sets) | + +#### WorkspaceVariableSet + +_Appears in:_ + +- [WorkspaceSpec](#workspacespec) + +| Field | Description | +| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` _string_ | ID of the variable set. Must match pattern: `varset-[a-zA-Z0-9]+$` [More information](/terraform/tutorials/cloud/cloud-multiple-variable-sets). | +| `name` _string_ | Name of the variable set. [More information](/terraform/tutorials/cloud/cloud-multiple-variable-sets). | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/index.mdx new file mode 100644 index 0000000000..0b3e18a397 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/index.mdx @@ -0,0 +1,220 @@ +--- +page_title: Terraform Enterprise Operator for Kubernetes overview +description: >- + The Terraform Enterprise Operator for Kubernetes allows you to provision + infrastructure directly from the Kubernetes control plane. +source: terraform-docs-common +--- + +# HCP Terraform Operator for Kubernetes overview + +The [HCP Terraform Operator for Kubernetes](https://github.com/hashicorp/hcp-terraform-operator) allows you to manage HCP Terraform resources with Kubernetes custom resources. You can provision infrastructure internal or external to your Kubernetes cluster directly from the Kubernetes control plane. + +The operator's CustomResourceDefinitions (CRD) let you dynamically create HCP Terraform workspaces with Terraform modules, populate workspace variables, and provision infrastructure with Terraform runs. + +## Key benefits + +The HCP Terraform Operator for Kubernetes v2 offers several improvements over v1: + +- **Flexible resource management**: The operator now features multiple custom resources, each with separate controllers for different HCP Terraform resources. This provides additional flexibility and the ability to manage more custom resources concurrently, significantly improving performance for large-scale deployments. + +- **Namespace management**: The `--namespace` option allows you to tailor the operator's watch scope to specific namespaces, which enables more fine-grained resource management. + +- **Configurable synchronization**: The `--sync-period` option allows you to configure the synchronization frequency between custom resources and HCP Terraform, ensuring timely updates and smoother operations. + +## Supported HCP Terraform features + +The HCP Terraform Operator for Kubernetes allows you to create agent pools, deploy modules, and manage workspaces through Kubernetes controllers. These controllers enable you to automate and manage HCP Terraform resources using custom resources in Kubernetes. + +### Agent pools + +Agent pools in HCP Terraform manage the execution environment for Terraform runs. The HCP Terraform Operator for Kubernetes allows you to create and manage agent pools as part of your Kubernetes infrastructure. + +The following example creates a new agent pool with the name `agent-pool-development` and generates an agent token with the name `token-red`. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: AgentPool +metadata: + name: my-agent-pool +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: agent-pool-development + agentTokens: + - name: token-red +``` + +The operator stores the `token-red` agent token in a Kubernetes secret named `my-agent-pool-token-red`. + +You can also enable agent autoscaling by providing a `.spec.autoscaling` configuration in your `AgentPool` specification. + + + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: AgentPool +metadata: + name: this +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: agent-pool-development + agentTokens: + - name: token-red + agentDeployment: + replicas: 1 + autoscaling: + targetWorkspaces: + - name: us-west-development + - id: ws-NUVHA9feCXzAmPHx + - wildcardName: eu-development-* + minReplicas: 1 + maxReplicas: 3 + cooldownPeriod: + scaleUpSeconds: 30 + scaleDownSeconds: 30 +``` + + + +In the above example, the operator ensures that at least one agent pod is continuously running and dynamically scales the number of pods up to a maximum of three based on the workload or resource demand. The operator then monitors resource demands by observing the load of the designated workspaces specified by the `name`, `id`, or `wildcardName` patterns. When the workload decreases, the operator downscales the number of agent pods. + +Refer to the [agent pool API reference](/terraform/enterprise/integrations/kubernetes/api-reference#agentpool) for the complete `AgentPool` specification. + +### Module + +The `Module` controller enforces an [API-driven Run workflow](/terraform/enterprise/run/api) and lets you deploy Terraform modules within workspaces. + +The following example deploys version `1.0.0` of the `hashicorp/module/random` module in the `workspace-name` workspace. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Module +metadata: + name: my-module +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + module: + source: hashicorp/module/random + version: 1.0.0 + workspace: + name: workspace-name + variables: + - name: string_length + outputs: + - name: random_string +``` + +The operator passes the workspace's `string_length` variable to the module and stores the `random_string` outputs as either a Kubernetes secret or a ConfigMap. If the workspace marks the output as `sensitive`, the operator stores the `random_string` as a Kubernetes secret; otherwise, the operator stores it as a ConfigMap. The variables must be accessible within the workspace as a workspace variable, workspace variable set, or project variable set. + +Refer to the [module API reference](/terraform/enterprise/integrations/kubernetes/api-reference#module) for the complete `Module` specification. + +### Project + +Projects let you organize your workspaces and scope access to workspace resources. The `Project` controller allows you to create, configure, and manage [projects](/terraform/tutorials/cloud/projects) directly from Kubernetes. + +The following example creates a new project named `testing`. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Project +metadata: + name: testing +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: project-demo +``` + +The `Project` controller allows you to manage team access [permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions). + +The following example creates a project named `testing` and grants the `qa` team admin access to the project. + + + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Project +metadata: + name: testing +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: project-demo + teamAccess: + - team: + name: qa + access: admin +``` + + + +Refer to the [project API reference](/terraform/enterprise/integrations/kubernetes/api-reference#project) for the complete `Project` specification. + +### Workspace + +HCP Terraform workspaces organize and manage Terraform configurations. The HCP Terraform Operator for Kubernetes allows you to create, configure, and manage workspaces directly from Kubernetes. + +The following example creates a new workspace named `us-west-development`, configured to use Terraform version `1.6.2`. This workspace has two variables, `nodes` and `rds-secret`. The variable `rds-secret` is treated as sensitive, and the operator reads the value for the variable from a Kubernetes secret named `us-west-development-secrets`. + +```yaml +--- +apiVersion: app.terraform.io/v1alpha2 +kind: Workspace +metadata: + name: us-west-development +spec: + organization: kubernetes-operator + token: + secretKeyRef: + name: tfc-operator + key: token + name: us-west-development + description: US West development workspace + terraformVersion: 1.6.2 + applyMethod: auto + agentPool: + name: ap-us-west-development + terraformVariables: + - name: nodes + value: 2 + - name: rds-secret + sensitive: true + valueFrom: + secretKeyRef: + name: us-west-development-secrets + key: rds-secret + runTasks: + - name: rt-us-west-development + stage: pre_plan +``` + +In the above example, the `applyMethod` has the value of `auto`, so HCP Terraform automatically applies any changes to this workspace. The specification also configures the workspace to use the `ap-us-west-development` agent pool and run the `rt-us-west-development` run task at the `pre_plan` stage. + +The operator stores the value of the workspace outputs as Kubernetes secrets or ConfigMaps. If the outputs are marked as `sensitive`, they are stored as Kubernetes secrets, otherwise they are stored as ConfigMaps. + +-> **Note**: The operator rolls back any external modifications made to the workspace to match the state specified in the custom resource definition. + +Refer to the [workspace API reference](/terraform/enterprise/integrations/kubernetes/api-reference#workspace) for the complete `Workspace` specification. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/ops-v2-migration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/ops-v2-migration.mdx new file mode 100644 index 0000000000..49c8bc1272 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/ops-v2-migration.mdx @@ -0,0 +1,342 @@ +--- +page_title: Migrate to Terraform Enterprise Operator for Kubernetes v2 +description: >- + Learn how to upgrade the Terraform Kubernetes Operator from version 1 to + version 2. +source: terraform-docs-common +--- + +# Migrate to HCP Terraform Operator for Kubernetes v2 + +~> **Warning**: Version 1 of the HCP Terraform Operator for Kubernetes is **deprecated** and no longer maintained. If you are installing the operator for the first time, refer to [Set up the HCP Terraform Operator for Kubernetes](/terraform/enterprise/integrations/kubernetes/setup) for guidance. + +To upgrade the HCP Terraform Operator for Kubernetes from version 1 to the HCP Terraform Operator for Kubernetes (version 2), there is a one-time process that you need to complete. This process upgrades the operator to the newest version and migrate your custom resources. + +## Prerequisites + +The migration process requires the following tools to be installed locally: + +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) +- [Helm](https://helm.sh/docs/intro/install/) + +## Prepare for the upgrade + +Configure an environment variable named `RELEASE_NAMESPACE` with the value of the namespace that the Helm chart is installed in. + +```shell-session +$ export RELEASE_NAMESPACE= +``` + +Next, create an environment variable named `RELEASE_NAME` with the value of the name that you gave your installation for the Helm chart. + +```shell-session +$ export RELEASE_NAME= +``` + +Before you migrate to HCP Terraform Operator for Kubernetes v2, you must first update v1 of the operator to the latest version, including the custom resource definitions. + +```shell-session +$ helm upgrade --namespace ${RELEASE_NAMESPACE} ${RELEASE_NAME} hashicorp/terraform +``` + +Next, backup the workspace resources. + +```shell-session +$ kubectl get workspace --all-namespaces -o yaml > backup_tfc_operator_v1.yaml +``` + +## Manifest schema migration + +Version 2 of the HCP Terraform Operator for Kubernetes renames and moves many existing fields. When you migrate, you must update your specification to match version 2's field names. + +### Workspace controller + +The table below lists the field mapping of the `Workspace` controller between v1 and v2 of the operator. + +| Version 1 | Version 2 | Changes between versions | +| --------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `apiVersion: app.terraform.io/v1alpha1` | `apiVersion: app.terraform.io/v1alpha2` | The `apiVersion` is now `v1alpha2`. | +| `kind: Workspace` | `kind: Workspace` | None. | +| `metadata` | `metadata` | None. | +| `spec.organization` | `spec.organization` | None. | +| `spec.secretsMountPath` | `spec.token.secretKeyRef` | In v2 the operator keeps the HCP Terraform access token in a Kubernetes Secret. | +| `spec.vcs` | `spec.versionControl` | Renamed the `vcs` field to `versionControl`. | +| `spec.vcs.token_id` | `spec.versionControl.oAuthTokenID` | Renamed the `token_id` field to `oAuthTokenID`. | +| `spec.vcs.repo_identifier` | `spec.versionControl.repository` | Renamed the `repo_identifier` field to `repository`. | +| `spec.vcs.branch` | `spec.versionControl.branch` | None. | +| `spec.vcs.ingress_submodules` | `spec.workingDirectory` | Moved. | +| `spec.variables.[*]` | `spec.environmentVariables.[*]` OR `spec.terraformVariables.[*]` | We split variables into two possible places. In v1's CRD, if `spec.variables.environmentVariable` was `true`, migrate those variables to `spec.environmentVariables`. If `false`, migrate those variables to `spec.terraformVariables`. | +| `spec.variables.[*]key` | `spec.environmentVariables.[*]name` OR `spec.terraformVariables.[*]name` | Renamed the `key` field as `name`. [Learn more](#workspace-variables). | +| `spec.variables.[*]value` | `spec.environmentVariables.[*]value` OR `spec.terraformVariables.[*]value` | [Learn more](#workspace-variables). | +| `spec.variables.[*]valueFrom` | `spec.environmentVariables.[*]valueFrom` OR `spec.terraformVariables.[*]valueFrom` | [Learn more](#workspace-variables). | +| `spec.variables.[*]hcl` | `spec.environmentVariables.[*]hcl` OR `spec.terraformVariables.[*]hcl` | [Learn more](#workspace-variables). | +| `spec.variables.sensitive` | `spec.environmentVariables.[*]sensitive` OR `spec.terraformVariables.[*]sensitive` | [Learn more](#workspace-variables). | +| `spec.variables.environmentVariable` | N/A | Removed, variables are split between `spec.environmentVariables` and `spec.terraformVariables`. | +| `spec.runTriggers.[*]` | `spec.runTriggers.[*]` | None. | +| `spec.runTriggers.[*].sourceableName` | `spec.runTriggers.[*].name` | The `sourceableName` field is now `name`. | +| `spec.sshKeyID` | `spec.sshKey.id` | Moved the `sshKeyID` to `spec.sshKey.id`. | +| `spec.outputs` | N/A | Removed. | +| `spec.terraformVersion` | `spec.terraformVersion` | None. | +| `spec.notifications.[*]` | `spec.notifications.[*]` | None. | +| `spec.notifications.[*].type` | `spec.notifications.[*].type` | None. | +| `spec.notifications.[*].enabled` | `spec.notifications.[*].enabled` | None. | +| `spec.notifications.[*].name` | `spec.notifications.[*].name` | None. | +| `spec.notifications.[*].url` | `spec.notifications.[*].url` | None. | +| `spec.notifications.[*].token` | `spec.notifications.[*].token` | None. | +| `spec.notifications.[*].triggers.[*]` | `spec.notifications.[*].triggers.[*]` | None. | +| `spec.notifications.[*].recipients.[*]` | `spec.notifications.[*].emailAddresses.[*]` | Renamed the `recipients` field to `emailAddresses`. | +| `spec.notifications.[*].users.[*]` | `spec.notifications.[*].emailUsers.[*]` | Renamed the `users` field to `emailUsers`. | +| `spec.omitNamespacePrefix` | N/A | Removed. In v1 `spec.omitNamespacePrefix` is a boolean field that affects how the operator generates a workspace name. In v2, you must explicitly set workspace names in `spec.name`. | +| `spec.agentPoolID` | `spec.agentPool.id` | Moved the `agentPoolID` field to `spec.agentPool.id`. | +| `spec.agentPoolName` | `spec.agentPool.name` | Moved the `agentPoolName` field to `spec.agentPool.name`. | +| `spec.module` | N/A | Removed. You now configure modules with a separate `Module` CRD. [Learn more](#module-controller). | + +Below is an example of configuring a variable in v1 of the operator. + + + +```yaml +apiVersion: app.terraform.io/v1alpha1 +kind: Workspace +metadata: + name: migration + spec: + variables: + - key: username + value: "user" + hcl: true + sensitive: false + environmentVariable: false + - key: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false + environmentVariable: true +``` + + + +In v2 of the operator, you must configure Terraform variables in `spec.terraformVariables` and environment variables `spec.environmentVariables`. + + + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Workspace +metadata: + name: migration + spec: + terraformVariables: + - name: username + value: "user" + hcl: true + sensitive: false + environmentVariables: + - name: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false +``` + + + +### Module controller + +HCP Terraform Operator for Kubernetes v2 configures modules in a new `Module` controller separate from the `Workspace` controller. Below is a template of a custom resource manifest: + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Module +metadata: + name: +spec: + organization: + token: + secretKeyRef: + name: + key: + name: operator +``` + +The table below describes the mapping between the `Workspace` controller from v1 and the `Module` controller in v2 of the operator. + +| Version 1 (Workspace CRD) | Version 2 (Module CRD) | Notes | +| ---------------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `spec.module` | N/A | In v2 of the operator a `Module` is a separate controller with its own CRD. | +| N/A | `spec.name: operator` | In v1 of the operator, the name of the generated module is hardcoded to `operator`. In v2, the default name of the generated module is `this`, but you can rename it. | +| `spec.module.source` | `spec.module.source` | This supports all Terraform [module sources](/terraform/language/modules/sources). | +| `spec.module.version` | `spec.module.version` | Refer to [module sources](/terraform/language/modules/sources) for versioning information for each module source. | +| `spec.variables.[*]` | `spec.variables.[*].name` | You should include variable names in the module. This is a reference to variables in the workspace that is executing the module. | +| `spec.outputs.[*].key` | `spec.outputs.[*].name` | You should include output names in the module. This is a reference to the output variables produced by the module. | +| `status.workspaceID` OR `metadata.namespace-metadata.name` | `spec.workspace.id` OR `spec.workspace.name` | The workspace where the module is executed. The workspace must be in the same organization. | + +Below is an example migration of a `Module` between v1 and v2 of the operator: + + + +```yaml +apiVersion: app.terraform.io/v1alpha1 +kind: Workspace +metadata: + name: migration +spec: + module: + source: app.terraform.io/org-name/module-name/provider + version: 0.0.42 + variables: + - key: username + value: "user" + hcl: true + sensitive: false + environmentVariable: false + - key: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false + environmentVariable: true +``` + + + +In v2 of the operator, separate controllers manage workspace and modules. + + + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Workspace +metadata: + name: migration + spec: + terraformVariables: + - name: username + value: "user" + hcl: true + sensitive: false + environmentVariables: + - name: SECRET_KEY + value: "s3cr3t" + hcl: false + sensitive: false +``` + + + + + +```yaml +apiVersion: app.terraform.io/v1alpha2 +kind: Module +metadata: + name: migration +spec: + name: operator + module: + source: app.terraform.io/org-name/module-name/provider + version: 0.0.42 + workspace: + name: migration +``` + + + +## Upgrade the operator + +Download Workspace CRD patch A: + +```shell-session +$ curl -sO https://raw.githubusercontent.com/hashicorp/hcp-terraform-operator/main/docs/migration/crds/workspaces_patch_a.yaml +``` + +View the changes that patch A applies to the workspace CRD. + +```shell-session +$ kubectl diff --filename workspaces_patch_a.yaml +``` + +Patch the workspace CRD with patch A. This patch adds `app.terraform.io/v1alpha2` support, but excludes `.status.runStatus` because it has a different format in `app.terraform.io/v1alpha1` and causes JSON un-marshalling issues. + +!> **Upgrade warning**: Once you apply a patch, Kubernetes converts existing `app.terraform.io/v1alpha1` custom resources to `app.terraform.io/v1alpha2` according to the updated schema, meaning that v1 of the operator can no longer serve custom resources. Before patching, update your existing custom resources to satisfy the v2 schema requirements. [Learn more](#manifest-schema-migration). + +```shell-session +$ kubectl patch crd workspaces.app.terraform.io --patch-file workspaces_patch_a.yaml +``` + +Install the Operator v2 Helm chart with the `helm install` command. Be sure to set the `operator.watchedNamespaces` value to the list of namespaces your Workspace resources are deployed to. If this value is not provided, the operator will watch all namespaces in the Kubernetes cluster. + +```shell-session +$ helm install \ + ${RELEASE_NAME} hashicorp/hcp-terraform-operator \ + --version 2.4.0 \ + --namespace ${RELEASE_NAMESPACE} \ + --set 'operator.watchedNamespaces={white,blue,red}' \ + --set controllers.agentPool.workers=5 \ + --set controllers.module.workers=5 \ + --set controllers.workspace.workers=5 +``` + +Next, create a Kubernetes secret to store the HCP Terraform API token following the [Usage Guide](https://github.com/hashicorp/hcp-terraform-operator/blob/main/docs/usage.md#prerequisites). The API token can be copied from the Kubernetes secret that you created for v1 of the operator. By default, this is named `terraformrc`. Use the `kubectl get secret` command to get the API token. + +```shell-session +$ kubectl --namespace ${RELEASE_NAMESPACE} get secret terraformrc -o json | jq '.data.credentials' | tr -d '"' | base64 -d +``` + +Update existing custom resources [according to the schema migration guidance](#manifest-schema-migration) and apply your changes. + +```shell-session +$ kubectl apply --filename +``` + +Download Workspace CRD patch B. + +```shell-session +$ curl -sO https://raw.githubusercontent.com/hashicorp/hcp-terraform-operator/main/docs/migration/crds/workspaces_patch_b.yaml +``` + +View the changes that patch B applies to the workspace CRD. + +```shell-session +$ kubectl diff --filename workspaces_patch_b.yaml +``` + +Patch the workspace CRD with patch B. This patch adds `.status.runStatus` support, which was excluded in patch A. + +```shell-session +$ kubectl patch crd workspaces.app.terraform.io --patch-file workspaces_patch_b.yaml +``` + +The v2 operator will fail to proceed if a custom resource has the v1 finalizer `finalizer.workspace.app.terraform.io`. If you encounter an error, check the logs for more information. + +```shell-session +$ kubectl logs -f +``` + +Specifically, look for an error message such as the following. + + ERROR Migration {"workspace": "default/", "msg": "spec contains old finalizer finalizer.workspace.app.terraform.io"} + +The `finalizer` exists to provide greater control over the migration process. Verify the custom resource, and when you’re ready to migrate it, use the `kubectl patch` command to update the `finalizer` value. + +```shell-session +$ kubectl patch workspace migration --type=merge --patch '{"metadata": {"finalizers": ["workspace.app.terraform.io/finalizer"]}}' +``` + +Review the operator logs once more and verify there are no error messages. + +```shell-session +$ kubectl logs -f +``` + +The operator reconciles resources during the next sync period. This interval is set by the `operator.syncPeriod` configuration of the operator and defaults to five minutes. + +If you have any migrated `Module` custom resources, apply them now. + +```shell-session +$ kubectl apply --filename +``` + +In v2 of the operator, the `applyMethod` is set to `manual` by default. In this case, a new run in a managed workspace requires manual approval. Run the following command for each `Workspace` resource to change it to `auto` approval. + +```shell-session +$ kubectl patch workspace --type=merge --patch '{"spec": {"applyMethod": "auto"}}' +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/setup.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/setup.mdx new file mode 100644 index 0000000000..ece055aa73 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/kubernetes/setup.mdx @@ -0,0 +1,94 @@ +--- +page_title: Set up the Terraform Enterprise Operator for Kubernetes +description: >- + Learn how to install and configure the Terraform Enterprise Operator for + Kubernetes. +source: terraform-docs-common +--- + +# Set up the HCP Terraform Operator for Kubernetes + +The HCP Terraform Operator for Kubernetes' CustomResourceDefinitions (CRD) allow you to dynamically create HCP Terraform workspaces with Terraform modules, populate workspace variables, and provision infrastructure with Terraform runs. + +You can install the operator with the official [HashiCorp Helm chart](https://github.com/hashicorp/hcp-terraform-operator). + +## Prerequisites + +All HCP Terraform users can use the HCP Terraform Operator for Kubernetes. You can use the operator to manage the supported features that your organization's pricing tier enables. + +## 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. + +| Hostname | Port/Protocol | Directionality | Purpose | +| ------------------ | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | +| `app.terraform.io` | tcp/443, HTTPS | Outbound | Dynamically managing HCP Terraform workspaces and returning the output to Kubernetes with the HCP Terraform API | + +For self-managed Terraform Enterprise instances, ensure that the operator can reach your Terraform Enterprise hostname over HTTPS (TCP port 443). + +## Compatibility + +The HCP Terraform Operator for Kubernetes supports the following versions: + +- Helm 3.0.1 and above +- Kubernetes 1.15 and above + +## Install and configure + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to integrate with Kubernetes. + +2. Generate an [organization token](/terraform/enterprise/users-teams-organizations/api-tokens#organization-api-tokens) within HCP Terraform or Terraform Enterprise and save it to a file. These instructions assume you are using a file named `credentials`. + +3. Set the `NAMESPACE` environment variable. This will be the namespace that you will install the Helm chart to. + + export NAMESPACE=tfc-operator-system + +4. Create the namespace. + + kubectl create namespace $NAMESPACE + +5. Create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) with the HCP Terraform API credentials. + + kubectl -n $NAMESPACE create secret generic terraformrc --from-file=credentials + +6. Add sensitive variables, such as your cloud provider credentials, to the namespace. + + kubectl -n $NAMESPACE create secret generic workspacesecrets --from-literal=secret_key=abc123 + +7. Add the HashiCorp Helm repository. + + 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 HCP Terraform at `app.terraform.io`. The following example command installs the Helm chart for HCP Terraform: + + ```shell-session + $ helm install --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator + ``` + + 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" + ``` + + 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: + ``` + + 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 + ``` + +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. + + helm upgrade --namespace ${RELEASE_NAMESPACE} hashicorp/hcp-terraform-operator tfc-operator diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/run-tasks/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/run-tasks/index.mdx new file mode 100644 index 0000000000..c64b59a21d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/run-tasks/index.mdx @@ -0,0 +1,109 @@ +--- +page_title: Set up Terraform Enterprise run task integrations +description: >- + Use run tasks to execute tasks in external systems at specific points in the + Terraform Enterprise run lifecycle. +source: terraform-docs-common +--- + +# Set up run task integrations + +In addition to using existing technology partners integrations, HashiCorp HCP Terraform customers can build their own custom run task integrations. Custom integrations have access to plan details in between the plan and apply phase, and can display custom messages within the run pipeline as well as prevent a run from continuing to the apply phase. + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +## Prerequisites + +To build a custom integration, you must have a server capable of receiving requests from HCP Terraform and responding with a status update to a supplied callback URL. When creating a run task, you supply an endpoint url to receive the hook. We send a test POST to the supplied URL, and it must respond with a 200 for the run task to be created. + +This feature relies heavily on the proper parsing of [plan JSON output](/terraform/internals/json-format). When sending this output to an external system, be certain that system can properly interpret the information provided. + +## Available Run Tasks + +You can view the most up-to-date list of run tasks in the [Terraform Registry](https://registry.terraform.io/browse/run-tasks). + +## Integration Details + +When a run reaches the appropriate phase and a run task is triggered, the supplied URL will receive details about the run in a payload similar to the one below. The server receiving the run task should respond `200 OK`, or Terraform will retry to trigger the run task. + +Refer to the [Run Task Integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration) for the exact payload specification. + +```json +{ + "payload_version": 1, + "stage": "post_plan", + "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q", + "capabilities": { + "outcomes": true + }, + "configuration_version_download_url": "https://app.terraform.io/api/v2/configuration-versions/cv-ntv3HbhJqvFzamy7/download", + "configuration_version_id": "cv-ntv3HbhJqvFzamy7", + "is_speculative": false, + "organization_name": "hashicorp", + "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output", + "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ", + "run_created_at": "2021-09-02T14:47:13.036Z", + "run_created_by": "username", + "run_id": "run-i3Df5to9ELvibKpQ", + "run_message": "Triggered via UI", + "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback", + "task_result_enforcement_level": "mandatory", + "task_result_id": "taskrs-2nH5dncYoXaMVQmJ", + "vcs_branch": "main", + "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22", + "vcs_pull_request_url": null, + "vcs_repo_url": "https://github.com/hashicorp/terraform-random", + "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace", + "workspace_id": "ws-ck4G5bb1Yei5szRh", + "workspace_name": "tfr_github_0", + "workspace_working_directory": "/terraform" +} +``` + +Once your server receives this payload, HCP Terraform expects you to callback to the supplied `task_result_callback_url` using the `access_token` as an [Authentication Header](/terraform/enterprise/api-docs#authentication) with a [jsonapi](/terraform/enterprise/api-docs#json-api-formatting) payload of the form: + +```json +{ + "data": { + "type": "task-results", + "attributes": { + "status": "running", + "message": "Hello task", + "url": "https://example.com", + "outcomes": [...] + } + } +} +``` + +HCP Terraform expects this callback within 10 minutes, or the task will be considered to have `errored`. The supplied message attribute will be displayed in HCP Terraform on the run details page. The status can be `running`, `passed` or `failed`. + +Here's what the data flow looks like: + +![Screenshot: a diagram of the user and data flow for an HCP Terraform run task](/img/docs/terraform-cloud-run-tasks-diagram.png) + +Refer to the [run task integration API](/terraform/enterprise/api-docs/run-tasks/run-tasks-integration#structured-results) for the exact payload specifications, and the [run task JSON schema](https://github.com/hashicorp/terraform-docs-common/blob/main/website/public/schema/run-tasks/runtask-result.json) for code generation and payload validation. + +## Securing your Run Task + +When creating your run task, you can supply an HMAC key which HCP Terraform will use to create a signature of the payload in the `X-Tfc-Task-Signature` header when calling your service. + +The signature is a sha512 sum of the webhook body using the provided HMAC key. The generation of the signature depends on your implementation, however an example of how to generate a signature in bash is provided below. + +```bash +$ echo -n $WEBHOOK_BODY | openssl dgst -sha512 -hmac "$HMAC_KEY" +``` + +## HCP Packer Run Task + +> **Hands On:** Try the [Set Up HCP Terraform Run Task for HCP Packer](/packer/tutorials/hcp/setup-hcp-terraform-run-task), [Standard tier run task image validation](/packer/tutorials/hcp/run-tasks-data-source-image-validation), and [Plus tier run task image validation](/packer/tutorials/hcp/run-tasks-resource-image-validation) tutorials to set up and test the HCP Terraform Run Task integration end to end. + +[Packer](https://www.packer.io/) lets you create identical machine images for multiple platforms from a single source template. The [HCP Packer registry](/hcp/docs/packer) lets you track golden images, designate images for test and production environments, and query images to use in Packer and Terraform configurations. + +The HCP Packer validation run task checks the image artifacts within a Terraform configuration. If the configuration references images marked as unusable (revoked), the run task fails and provides an error message containing the number of revoked artifacts and whether HCP Packer has metadata for newer versions. For HCP Packer Plus registries, run tasks also help you identify hardcoded and untracked images that may not meet security and compliance requirements. + +To get started, [create an HCP Packer account](https://cloud.hashicorp.com/products/packer) and follow the instructions in the [HCP Packer Run Task](/hcp/docs/packer/manage-image-use/terraform-cloud-run-tasks) documentation. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/admin-guide.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/admin-guide.mdx new file mode 100644 index 0000000000..735371a432 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/admin-guide.mdx @@ -0,0 +1,56 @@ +--- +page_title: Configure the ServiceNow Service Catalog integration +description: Learn how to configure the ServiceNow Service Catalog integration workers. +source: terraform-docs-common +--- + +# Configure the ServiceNow Service Catalog integration + +ServiceNow administrators have several options with configuring the Terraform +integration. + +If you haven't yet installed the integration, see the [installation +documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform). + +Once the integration has been installed, you can add and customize a service +catalog and VCS repositories using the [service catalog +documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config). + +You can also configure how frequently ServiceNow will poll HCP Terraform using +the documentation below. + +## Configure Polling Workers + +The integration includes 3 ServiceNow Scheduled Flows to poll the HCP Terraform +API using ServiceNow Outbound HTTP REST requests. By default, all flows +schedules are set to 5 minutes. These can be customized inside the ServiceNow +Server Studio: + +1. Select the Worker Poll Run State Flow. +2. Adjust Repeat Intervals +3. Click "Done" +4. Click "Save" +5. Click "Activate" + +### Worker Poll Apply Run + +This worker approves runs for any workspaces that have finished a Terraform plan +and are ready to apply their changes. It also adds a comment on the request item +for those workspaces notifying that a run has been triggered. + +### Worker Poll Destroy Workspace + +This worker looks for any records in the Terraform ServiceNow table that are +marked for deletion with the value `is_destroyable` set to true. It then checks +the status of the workspace to ensure it is ready to be deleted. Once the +destroy run has been completed, this work will send the delete request for the +workspace to Terraform. + +### Worker Poll Run State + +The worker synchronizes ServiceNow with the current run state of Terraform +workspaces by polling the HCP Terraform API. On state changes, the worker adds +a comment to the ServiceNow request item with the updated run state and other +metadata. + +![screenshot: ServiceNow integration comments](/img/docs/service-now-comments.png) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/developer-reference.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/developer-reference.mdx new file mode 100644 index 0000000000..13ae4b2163 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/developer-reference.mdx @@ -0,0 +1,112 @@ +--- +page_title: ServiceNow Service Catalog integration developer reference +description: Learn how developers can customize the ServiceNow Service Catalog integration. +source: terraform-docs-common +--- + +# Terraform ServiceNow Service Catalog Integration Developer Reference + +The Terraform ServiceNow integration can be customized by ServiceNow developers +using the information found in this document. + +## Terraform Variables and ServiceNow Variable Sets + +ServiceNow has the concept of a Variable Set which is a collection of ServiceNow +Variables that can be referenced in a Flow from a Service Catalog item. The +Terraform Integration codebase can create [Terraform Variables and Terraform +Environment Variables](/terraform/enterprise/workspaces/variables) via the API using the +`tf_variable.createVariablesFromSet()` function. + +This function looks for variables following these conventions: + +| ServiceNow Variable Name | HCP Terraform Variable | +| -------------------------------- | ---------------------------------------------------------- | +| `tf_var_VARIABLE_NAME` | Terraform Variable: `VARIABLE_NAME` | +| `tf_env_ENV_NAME` | Environment Variable: `ENV_NAME` | +| `sensitive_tf_var_VARIABLE_NAME` | Sensitive Terraform Variable (Write Only): `VARIABLE_NAME` | +| `sensitive_tf_env_ENV_NAME` | Sensitive Environment Variable (Write Only): `ENV_NAME` | + +This function takes the ServiceNow Variable Set and HCP Terraform workspace +ID. It will loop through the given variable set collection and create any +necessary Terraform variables or environment variables in the workspace. + +## Customizing with ServiceNow "Script Includes" Libraries + +The Terraform/ServiceNow Integration codebase includes [ServiceNow Script +Includes +Classes](https://docs.servicenow.com/csh?topicname=c_ScriptIncludes.html&version=latest) +that are used to interface with HCP Terraform. The codebase also includes +example catalog items and flows that implement the interface to the HCP Terraform API. + +These classes and examples can be used to help create ServiceNow Catalog Items +customized to your specific ServiceNow instance and requirements. + +### Script Include Classes + +The ServiceNow Script Include Classes can be found in the ServiceNow Studio > +Server Development > Script Include. + +| Class Name | Description | +| ---------------------- | -------------------------------------------------------------- | +| `tf_config` | Helper to pull values from the SN Terraform Configs Table | +| `tf_get_workspace` | Client-callable script to retrieve workspace data | +| `tf_http` | ServiceNow HTTP REST wrapper for requests to the Terraform API | +| `tf_no_code_workspace` | Resources for Terraform no-code module API requests | +| `tf_run` | Resources for Terraform run API requests | +| `tf_terraform_record` | Manage ServiceNow Terraform Table Records | +| `tf_test_config` | Client-callable script to test Terraform connectivity | +| `tf_util` | Miscellaneous helper functions | +| `tf_variable` | Resources for Terraform variable API Requests | +| `tf_vcs_record` | Manage ServiceNow Terraform VCS repositories table records | +| `tf_workspace` | Resources for Terraform workspace API requests | + +### Example Service Catalog Flows and Actions + +The ServiceNow Service Catalog for Terraform provides sample catalog items that use **Flows** +and **Workflows** as their primary process engines. **Flows** are a newer solution developed +by ServiceNow and are generally preferred over **Workflows**. To see which engine an item is using, open it +in the edit mode and navigate to the **Process Engine** tab. For example, **Create Workspace** uses a **Workflow**, +whereas **Create Workspace Flow** is built upon a **Flow**. You can access both in the **Studio**. You can also +manage **Flows** in the **Flow Designer**. To manage **Workflows**, navigate to **All > Workflow Editor**. + +You can find the ServiceNow Example Flows for Terraform in the **ServiceNow Studio > Flows** (or **All > Flow Designer**). +Search for items that belong to the **Terraform** application. By default, Flows execute when someone submits an order request +for a catalog item based on a Flow. Admins can customize the Flows and Actions to add approval flows, set approval rules based +on certain conditions, and configure multiple users or roles as approvers for specific catalog items. + +| Flow Name | Description | +| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Create Workspace | Creates a new HCP Terraform workspace from VCS repository. | +| Create Workspace with Vars | Creates a new HCP Terraform workspace from VCS repository and creates any variables provided. | +| Create Run | Creates and queues a new run in the HCP Terraform workspace. | +| Apply Run | Applies a run in the HCP Terraform workspace. | +| Provision Resources | Creates a new HCP Terraform workspace (with auto-apply), creates and queues a run, then applies the run when ready. | +| Provision Resources with Vars | Creates a new HCP Terraform workspace (with auto-apply), creates any variables, creates/queues a run, applies the run when ready. | +| Provision No-Code Workspace and Deploy Resources | Creates a new HCP Terraform workspace based on a no-code module configured in the private registry (with auto-apply), creates any variables, creates and queues a run, then applies the run when ready. | +| Delete Workspace | Creates a destroy run plan. | +| Worker Poll Run State | Polls the HCP Terraform API for the current run state of a workspace. | +| Worker Poll Apply Run | Polls the HCP Terraform API and applies any pending Terraform runs. | +| Worker Poll Destroy Workspace | Queries ServiceNow Terraform Records for resources marked `is_destroyable`, applies the destroy run to destroy resources, and deletes the corresponding Terraform workspace. | +| Update No-Code Workspace and Deploy Resources | Updates an existing no-code workspace to the most recent no-code module version, updates that workspace's attached variable values, and then starts a new Terraform run. | +| Update Workspace | Updates HCP Terraform workspace configurations, such as VCS repository, description, project, execution mode, and agent pool ID (if applicable). | +| Update Workspace with Vars | Allows you to change details about the HCP Terraform workspace configurations and attached variable values. | +| Update Resources | Updates HCP Terraform workspace details and starts a new Terraform run with these new values. | +| Update Resources with Vars | Updates your existing HCP Terraform workspace and its variables, then starts a Terraform run with these updated values. | + +## ServiceNow ACLs + +Access control lists (ACLs) restrict user access to objects and operations based +on permissions granted. This integration includes the following roles that can +be used to manage various components. + +| Access Control Roles | Description | +| :---------------------------------- | --------------------------------------------------------------------------------------------- | +| `x_terraform.config_user` | Can manage the connection from the ServiceNow application to your HCP Terraform organization. | +| `x_terraform.terraform_user` | Can manage all of the Terraform resources created in ServiceNow. | +| `x_terraform.vcs_repositories_user` | Can manage the VCS repositories available for catalog items to be ordered by end-users. | + +For users who only need to order from the Terraform Catalog, we recommend +creating another role with read-only permissions for +`x_terraform_vcs_repositories` to view the available repositories for ordering +infrastructure. Install the Terraform ServiceNow Service Catalog integration by +following [the installation guide](/terraform/enterprise/integrations/service-now/service-catalog-terraform). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/example-customizations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/example-customizations.mdx new file mode 100644 index 0000000000..c14d11a220 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/example-customizations.mdx @@ -0,0 +1,174 @@ +--- +page_title: ServiceNow Service Catalog integration example configurations +description: >- + Learn from example common customizations of the ServiceNow Service Catalog + integration. +source: terraform-docs-common +--- + +# ServiceNow Service Catalog integration example configurations + +This example use case creates a Terraform Catalog Item for requesting resources +with custom variable values passed to the Terraform configuration. + +## Change the scope + +When you make a customization to the app, ensure you switch to the "Terraform" +scope. This guarantees that all items you create are correctly assigned to that +scope. To change the scope in your ServiceNow instance, click the globe icon at +the top right of the screen. For detailed instructions on changing the scope, +refer to the [ServiceNow +documentation](https://developer.servicenow.com/dev.do#!/learn/learning-plans/xanadu/new_to_servicenow/app_store_learnv2_buildneedit_xanadu_application_scope). + +## Make a copy of the existing Catalog Item + +The ServiceNow Service Catalog for Terraform application provides pre-configured [Catalog +Items](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference#example-service-catalog-flows-and-actions) +for immediate use. We recommend creating a copy of the most recent version of the +Catalog Item to ensure you have access to the latest features and +improvements. Make a copy of the most appropriate Catalog Item for your specific +business requirements by following these steps: + +1. Navigate to **All > Service Catalog > Catalogs > Terraform Catalog**, and review the + Catalog Items based on flows, whose names use the suffix "Flow". + We recommend choosing Flows over Workflows because Flows provide enhanced functionality and performance and are actively developed by ServiceNow. + For more information, refer + to [Catalog Items based on Flows vs. Workflows](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference#example-service-catalog-flows-and-actions). +2. Open the Catalog Item in editing mode: + 1. Click the Catalog Item to open the request form. + 2. Click **...** in the top right corner. + 3. Select **Configure Item** from the menu. + ![Screenshot: ServiceNow Configure Catalog Item](/img/docs/servicenow-catalog-configure-item.png "Screenshot of the ServiceNow Configure Catalog Item dropdown menu") +3. Click the **Process Engine** tab in the Catalog Item configuration. Take + note of the Flow name associated with the Catalog Item, because you need to + create a copy of this Flow as well. + ![Screenshot: ServiceNow Process Engine](/img/docs/servicenow-catalog-process-engine.png "Screenshot of the ServiceNow Configure Catalog Item – Process Engine tab") +4. Start the copying process: + 1. Click the **Copy** button above the **Related Links** section. + 2. Assign a new name to the copied Catalog Item. + 3. Optionally, modify the description and short description fields. + Right-click the header and select **Save**. + ![Screenshot: ServiceNow Copy Item](/img/docs/servicenow-catalog-copied-item.png "Screenshot of the copied ServiceNow Catalog Item") + +## Adjust the Variable Set + +If a Catalog Item requires users to input variable values, +you must update the variable set with those required variables. +Although some default Catalog Items come with pre-defined example variables, it +is common practice to remove these and replace them with your own custom +variables. + +1. Create a new Variable Set. + 1. On the Catalog Item's configuration page, under the **Related Links** + section, click the **Variable Sets** tab. + 2. Click the **New** button to create a new variable set. Ensure that the + variables in your new set match the variables required by your Terraform + configuration. + ![Screenshot: ServiceNow New Variable Set](/img/docs/servicenow-catalog-new-varset.png "Screenshot of the ServiceNow Catalog Item – new Variable Set") + 3. Select **Single-Row Variable Set** and provide a title and description. + 4. Click **Submit**. Upon submission, you will be redirected back to the Catalog + Item's configuration page. + ![Screenshot: ServiceNow New Variable Set Form](/img/docs/servicenow-catalog-new-varset-form.png "Screenshot of the ServiceNow Catalog Item – new Variable Set") + 5. Click the name of your newly created Variable Set and create your + variables. You must follow the [naming convention for Terraform + variables](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference#terraform-variables-and-servicenow-variable-sets). + ServiceNow offers various types of variable representation (such as strings, + booleans, and dropdown menus). Refer to the [ServiceNow documentation on + variables](https://docs.servicenow.com/csh?topicname=c_ServiceCatalogVariables.html&version=latest) + and select the types that best suit your use case. You can also set default + values for the variables in the **Default Value** tab, which ServiceNow prefills for the end users. + ![Screenshot: ServiceNow New Variables](/img/docs/servicenow-catalog-variables.png "Screenshot of the ServiceNow Catalog Item – new variables") +2. Attach the newly created Variable Set to your custom Catalog Item and remove + the default Workspace Variables. + 1. Return to the **Variable Sets** tab on the Catalog Item's configuration page + and click the **Edit** button. + 2. Move the "Workspace Variables" Set from the right side to the left side + and click **Save**. Do not remove the + "Workspace Request Create" or the "Workspace Request Update" Sets. + ![Screenshot: ServiceNow Remove Example Variables](/img/docs/servicenow-catalog-remove-example-variables.png "Screenshot of the ServiceNow Catalog Item – new variables") + +## Make a copy of the Flow and Action + +1. Open the ServiceNow Studio by navigating to **All > Studio** and open the + "Terraform" application. Once in the **Terraform** application, navigate to + **Flow Designer > Flows**. + ![Screenshot: ServiceNow Flow Designer Interface](/img/docs/servicenow-catalog-original-flow.png "Screenshot of the ServiceNow Flow Designer – selecting a Flow") + + Another way to access the ServiceNow Studio is to click **All**, select + "Flow Designer", then select **Flows**. You can set the **Application** + filter to "Terraform" to quickly find the desired Flow. +2. Open the Flow referenced in your Catalog Item. Click **...** + in the top right corner of the Flow Designer interface and + select **Copy flow**. Provide a name for the copied Flow and + click **Copy**. + ![Screenshot: ServiceNow Copy Flow Interface](/img/docs/servicenow-catalog-copy-flow.png "Screenshot of the ServiceNow Flow Designer – copying a Flow") +3. Customize your newly copied Flow by clicking **Edit flow**. + ![Screenshot: ServiceNow Edit New Flow Interface](/img/docs/servicenow-catalog-edit-flow.png "Screenshot of the ServiceNow Flow Designer – editing a Flow") + 1. Do not change the **Service Catalog** trigger. + 2. Update the "Get Catalog Variables" action: + 1. Keep the "Requested Item Record" in the **Submitted Request** field. + 2. Select your newly created Catalog Item from the dropdown menu for + **Template Catalog Item**. + 3. Move all of your variables to the **Selected** side in the **Catalog + Variables** section. Remove any previous example variables from the + **Available** side. + ![Screenshot: ServiceNow Get Variables Flow Step](/img/docs/servicenow-catalog-get-variables.png "Screenshot of the ServiceNow Flow Designer – getting Variables step") + 4. Click **Done** to finish configuring this Action. +4. Unfold the second Action in the Flow and click the arrow to open it in + the Action Designer. + ![Screenshot: ServiceNow Open Action Designer](/img/docs/servicenow-catalog-open-action.png "Screenshot of the ServiceNow Action Designer") + 1. Click **...** in the top right corner and select **Copy Action**. + ![Screenshot: ServiceNow Copy Action](/img/docs/servicenow-catalog-copy-action.png "Screenshot of the ServiceNow Copy Action") + Rename it and click **Copy**. + ![Screenshot: ServiceNow Rename Action](/img/docs/servicenow-catalog-rename-action.png "Screenshot of the ServiceNow Rename Action") + 2. In the the Inputs section, remove any previous example variables. + ![Screenshot: ServiceNow Remove Variables From Action](/img/docs/servicenow-catalog-remove-example-variables-from-action.png "Screenshot of the ServiceNow Action Input Variables") + 3. Add your custom variables by clicking the **Create Input** button. Ensure that the variable names match your Catalog Item variables and select the variable type that matches each variable. Click **Save**. + ![Screenshot: ServiceNow Add Variables To Action](/img/docs/servicenow-catalog-add-variables-to-action.png "Screenshot of adding ServiceNow Action Input Variables") + 4. Open the **Script step** within the Action. Remove any example variables + and add your custom variables by clicking **Create Variable** at the + bottom. Enter the name of each variable and drag the corresponding data + pill from the right into the **Value field**. + ![Screenshot: ServiceNow Add Script Step Variables To Action](/img/docs/servicenow-catalog-adjust-script-variables.png "Screenshot of adjusting ServiceNow Action Script Variables") + 5. Click **Save** and then **Publish**. +5. Reopen the Flow and attach the newly created Action to the Flow + after "Get Catalog Variables" step: + 1. Remove the "Create Terraform Workspace with Vars" Action that you copied earlier and replace it with + your newly created Action. + ![Screenshot: ServiceNow Replace Action Step](/img/docs/servicenow-catalog-replace-action.png "Screenshot of replacing ServiceNow Action step") + 2. Connect the new Action to the Flow by dragging and dropping the data pills + from the "Get Catalog Variables" Action to the corresponding inputs of + your new Action. Click **Done** to save this step. + ![Screenshot: ServiceNow Fill Variables for Action](/img/docs/servicenow-catalog-fill-new-action-step.png "Screenshot of filling out ServiceNow Action variables") + 3. Click **Save**. + 4. Click **Activate** to enable the Flow and make it available for use. + +## Set the Flow for your Catalog Item + +1. Navigate back to the Catalog by clicking on **All** and then go to **Service + Catalog > Catalogs > Terraform Catalog**. +2. Locate your custom Catalog Item and click **...** at the top + of the item. From the dropdown menu, select **Configure item**. +3. In the configuration settings, click the **Process Engine** tab. +4. In the **Flow** field, search for the Flow you recently created. Click + the Flow then click the **Update**. + ![Screenshot: ServiceNow Update Process Engine](/img/docs/servicenow-catalog-update-process-engine.png "Screenshot of updating Process Engine for the Catalog Item") + +## Test the Catalog Item + +The new item is now available in the Terraform Service Catalog. To make the +new item accessible to your end users via the Service Portal, follow these +steps: + +1. Navigate to the configuration page of the item you want to make available. +2. Locate the **Catalogs** field on the configuration page and click the lock + icon next to it. +3. In the search bar, type "Service Catalog" and select it from the search + results. Add "Service Catalog" to the list of catalogs associated with the + item. Click the lock icon again to lock the changes. + ![Screenshot: ServiceNow Enable Service Portal](/img/docs/servicenow-catalog-service-portal.png "Screenshot of adding the Catalog Item to the Service Portal") +4. Click the **Update** button at the top of the page. + +After completing these steps, end users will be able to +access the new item through the Service Portal of your ServiceNow instance. You +can access the Service Portal by navigating to **All > Service Portal Home**. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/index.mdx new file mode 100644 index 0000000000..83f0111836 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/index.mdx @@ -0,0 +1,239 @@ +--- +page_title: Set up ServiceNow Service Catalog integration for Terraform Enterprise +description: >- + Learn how to set up the ServiceNow Service Catalog integration for Terraform + Enterprise. +source: terraform-docs-common +--- + +# Set up ServiceNow Service Catalog integration for HCP Terraform + +-> **Integration version:** v2.8.1 + +The Terraform ServiceNow Service Catalog integration enables your end-users to +provision self-serve infrastructure via ServiceNow. By connecting ServiceNow to +HCP Terraform, this integration lets ServiceNow users order Service Items, +create workspaces, and perform Terraform runs using prepared Terraform +configurations hosted in VCS repositories or as [no-code +modules](/terraform/enterprise/no-code-provisioning/module-design) for +self-service provisioning. + + + +@include 'tfc-package-callouts/servicenow-catalog.mdx' + + + +## Summary of the Setup Process + +The integration relies on Terraform ServiceNow Catalog integration software +installed within your ServiceNow instance. Installing and configuring this +integration requires administration in both ServiceNow and HCP Terraform. +Since administrators of these services within your organization are not +necessarily the same person, this documentation refers to a **ServiceNow Admin** +and a **Terraform Admin**. + +First, the Terraform Admin configures your HCP Terraform organization with a +dedicated team for the ServiceNow integration, and obtains a team API token for +that team. The Terraform Admin provides the following to your ServiceNow admin: + +- An Organization name +- A team API token +- The hostname of your HCP Terraform instance +- Any available no-code modules or version control repositories containing Terraform configurations +- Other required variables + token, the hostname of your HCP Terraform instance, and details about no-code + modules or version control repositories containing Terraform configurations and + required variables to the ServiceNow Admin. + +Next, the ServiceNow Admin will install the Terraform ServiceNow Catalog +integration to your ServiceNow instance, and configure it using the team API +token and hostname. + +Finally, the ServiceNow Admin will create a Service Catalog within ServiceNow +for the Terraform integration, and configure it using the version control +repositories or no-code modules, and variable definitions provided by the +Terraform Admin. + +| ServiceNow Admin | Terraform Admin | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | Prepare an organization for use with the ServiceNow Catalog. | +| | Create a team that can manage workspaces in that organization. | +| | Create a team API token so the integration can use that team's permissions. | +| | If using VCS repositories, retrieve the OAuth token IDs and repository identifiers that HCP Terraform uses to identify your VCS repositories. If using a no-code flow, [create a no-code ready module](/terraform/enterprise/no-code-provisioning/provisioning) in your organization's private registry. Learn more in [Configure VCS Repositories or No-Code Modules](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#configure-vcs-repositories-or-no-code-modules). | +| | Provide the API token, OAuth token ID, repository identifiers, variable definitions, and HCP Terraform hostname to the ServiceNow Admin. | +| Install the Terraform integration application from the ServiceNow App Store. | | +| Connect the integration application with HCP Terraform. | | +| Add the Terraform Service Catalog to ServiceNow. | | +| If you are using the VCS flow, configure the VCS repositories in ServiceNow. | | +| Configure variable sets for use with the VCS repositories or no-code modules. | | + +Once these steps are complete, self-serve infrastructure will be available +through the ServiceNow Catalog. HCP Terraform will provision and manage +requested infrastructure and report the status back to ServiceNow. + +## Prerequisites + +To start using Terraform with the ServiceNow Catalog Integration, you must have: + +- An administrator account on a Terraform Enterprise instance or within a + HCP Terraform organization. +- An administrator account on your ServiceNow instance. +- If you are using the VCS flow, one or more [supported version control + systems](/terraform/enterprise/vcs#supported-vcs-providers) (VCSs) with read + access to repositories with Terraform configurations. +- If you are using no-code provisioning, one or more [no-code modules](/terraform/enterprise/no-code-provisioning/provisioning) created in + your organization's private registry. Refer to the [no-code module + configuration](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#no-code-module-configuration) + for information about using no-code modules with the ServiceNow Service Catalog + for Terraform. + +You can use this integration on the following ServiceNow server versions: + +- Washington DC +- Xanadu +- Yokohama + +It requires the following ServiceNow plugins as dependencies: + +- Flow Designer support for the Service Catalog (`com.glideapp.servicecatalog.flow_designer`) +- ServiceNow IntegrationHub Action Step - Script (`com.glide.hub.action_step.script`) +- ServiceNow IntegrationHub Action Step - REST (`com.glide.hub.action_step.rest`) + +-> **Note:** Dependent plugins are installed on your ServiceNow instance automatically when the app is downloaded from the ServiceNow Store. + +## Configure HCP Terraform + +Before installing the ServiceNow integration, the Terraform Admin will need to +perform the following steps to configure and gather information from HCP +Terraform. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Either [create an + organization](/terraform/enterprise/users-teams-organizations/organizations#creating-organizations) + or choose an existing organization where ServiceNow will create new + workspaces. + **Save the organization name for later.** +3. [Create a team](/terraform/enterprise/users-teams-organizations/teams) for that + organization called "ServiceNow", and ensure that it has [permission to + manage + workspaces](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces). + You do not need to add any users to this team. + [permissions-citation]: #intentionally-unused---keep-for-maintainers +4. On the "ServiceNow" team's settings page, generate a [team API + token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). + **Save the team API token for later.** +5. If you are using the [VCS flow](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#vcs-configuration): + 1. Ensure your Terraform organization is [connected to a VCS provider](/terraform/enterprise/vcs). Repositories that are connectable to HCP Terraform workspaces can also be used as workspace templates in the ServiceNow integration. + 2. On your organization's VCS provider settings page (**Settings** > **VCS Providers**), find the OAuth Token ID for the VCS provider(s) that you intend to use with the ServiceNow integration. HCP Terraform uses the OAuth token ID to identify and authorize the VCS provider. **Save the OAuth token ID for later.** + 3. Identify the VCS repositories in the VCS provider containing Terraform configurations that the ServiceNow Terraform integration will deploy. Take note of any Terraform or environment variables used by the repositories you select. Save the Terraform and environment variables for later. +6. If using the [no-code flow](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#no-code-module-configuration), create one or more no-code modules in the private registry of your HCP Terraform. **Save the no-code module names for later.** +7. Provide the following information to the ServiceNow Admin: + - The organization name + - The team API token + - The hostname of your Terraform Enterprise instance, or of HCP Terraform. The hostname of HCP Terraform is `app.terraform.io`. + - The no-code module name(s) or the OAuth token ID(s) of your VCS provider(s), and the repository identifier for each VCS repository containing Terraform configurations that will be used by the integration. + - Any Terraform or environment variables required by the configurations in the + given VCS repositories. + +-> **Note:** Repository identifiers are determined by your VCS provider; they +typically use a format like `/` or +`/`. Azure DevOps repositories use the format +`//_git/`. A GitHub repository hosted at +`https://github.com/exampleorg/examplerepo/` would have the repository +identifier `exampleorg/examplerepo`. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +For instance, if you are configuring this integration for your company, `Example +Corp`, using two GitHub repositories, you would share values like the following +with the ServiceNow Admin. + +```markdown +Terraform Enterprise Organization Name: `ServiceNowExampleOrg` + +Team API Token: `q2uPExampleELkQ.atlasv1.A7jGHmvufExampleTeamAPITokenimVYxwunJk0xD8ObVol054` + +Terraform Enterprise Hostname: `terraform.corp.example` + +OAuth Token ID (GitHub org: example-corp): `ot-DhjEXAMPLELVtFA` + - Repository ID (Developer Environment): `example-corp/developer-repo` + - Environment variables: + - `AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY` + - `AWS_SECRET_ACCESS_KEY=ZB0ExampleSecretAccessKeyGjUiJh` + - `AWS_DEFAULT_REGION=us-west-2` + - Terraform variables: + - `instance_type=t2.medium` + - Repository ID (Testing Environment): `example-corp/testing-repo` + - Environment variables: + - `AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY` + - `AWS_SECRET_ACCESS_KEY=ZB0ExampleSecretAccessKeyGjUiJh` + - `AWS_DEFAULT_REGION=us-west-2` + - Terraform variables: + - `instance_type=t2.large` +``` + +## Install the ServiceNow Integration + +Before beginning setup, the ServiceNow Admin must install the Terraform +ServiceNow Catalog integration software. + +This can be added to your ServiceNow instance from the [ServiceNow +Store](https://store.servicenow.com/sn_appstore_store.do). Search for the "Terraform" integration, +published by "HashiCorp Inc". + +![Screenshot: ServiceNow Store Page](/img/docs/service-now-store.png "Screenshot of the ServiceNow Store listing for the Terraform Integration") + +## Connect ServiceNow to HCP Terraform + +-> **ServiceNow Roles:** `admin` or `x_terraform.config_user` + +Once the integration is installed, the ServiceNow Admin can connect your +ServiceNow instance to HCP Terraform. Before you begin, you will need the +information described in the "Configure HCP Terraform" section from your +Terraform Admin. + +Once you have this information, connect ServiceNow to HCP Terraform with +the following steps. + +1. Navigate to your ServiceNow Service Management Screen. +2. Using the left-hand navigation, open the configuration table for the + integration to manage the HCP Terraform connection. + - Terraform > Configs +3. Click on "New" to create a new HCP Terraform connection. + - Set Org Name to the HCP Terraform organization name. + - Click on the "Lock" icon to set Hostname to the hostname of your Terraform + Enterprise instance. If you are using the SaaS version of HCP Terraform, + the hostname is `https://app.terraform.io`. Be sure to include "https://" + before the hostname. + - Set API Team Token to the HCP Terraform team API token. + - (Optional) To use the [MID Server](https://docs.servicenow.com/csh?topicname=mid-server-landing.html&version=latest), + select the checkbox and type the `name` in the `MID Server Name` field. +4. Click "Submit". + +![Screenshot: ServiceNow Terraform Config](/img/docs/service-now-updated-config.png "Screenshot of the ServiceNow Terraform Config New Record page") + +## Create and Populate a Service Catalog + +Now that you have connected ServiceNow to HCP Terraform, you are ready to +create a Service Catalog using the VCS repositories or no-code modules provided +by the Terraform Admin. + +Navigate to the [Service Catalog documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config) to +begin. You can also refer to this documentation whenever you need to add or +update request items. + +### ServiceNow Developer Reference + +ServiceNow developers who wish to customize the Terraform integration can refer +to the [developer documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/developer-reference). + +### ServiceNow Administrator's Guide. + +Refer to the [ServiceNow Administrator documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/admin-guide) for +information about configuring the integration. + +### Example Customizations + +Once the ServiceNow integration is installed, you can consult the [example +customizations documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform/example-customizations). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config.mdx new file mode 100644 index 0000000000..ce972ed701 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config.mdx @@ -0,0 +1,255 @@ +--- +page_title: Create and manage ServiceNow Service Catalog items with Terraform Enterprise +description: >- + Create and manage service catalog items to allow end users to provision + infrastructure using ServiceNow and Terraform Enterprise. +source: terraform-docs-common +--- + +# Create and manage ServiceNow Service Catalog items + +When using ServiceNow with the HCP Terraform integration, you will configure +at least one service catalog item. You will also configure one or more version +control system (VCS) repositories or no-code modules containing the Terraform +configurations which will be used to provision that infrastructure. End users +will request infrastructure from the service catalog, and HCP Terraform will +fulfill the request by creating a new workspace, applying the configuration, and +then reporting the results back to ServiceNow. + +## Prerequisites + +Before configuring a service catalog, you must install and configure the +HCP Terraform integration software on your ServiceNow instance. These steps +are covered in the [installation documentation](/terraform/enterprise/integrations/service-now/service-catalog-terraform). + +Additionally, you must have have the following information: + +1. The no-code module name or the OAuth token ID and repository identifier for + each VCS repository that HCP Terraform will use to provision + infrastructure. Your Terraform Admin will provide these to you. Learn more in + [Configure VCS Repositories or No-Code + Modules](/terraform/enterprise/integrations/service-now/service-catalog-terraform/service-catalog-config#configure-vcs-repositories-or-no-code-modules). +2. Any Terraform or environment variables required by the configurations in the + given VCS repositories or no-code modules. + +Once these steps are complete, in order for end users to provision +infrastructure with ServiceNow and HCP Terraform, the ServiceNow Admin will +perform the following steps to make Service Items available to your end users. + +1. Add at least one service catalog for use with Terraform. +2. If you are using the VCS flow, configure at least one one VCS repository in ServiceNow. +3. Create variable sets to define Terraform and environment variables to be used + by HCP Terraform to provision infrastructure. + +## Add the Terraform Service Catalog + +-> **ServiceNow Role:** `admin` + +First, add a Service Catalog for use with the Terraform integration. Depending +on your organization's needs, you might use a single service catalog, or +several. If you already have a Service Catalog to use with Terraform, skip to +the next step. + +1. In ServiceNow, open the Service Catalog > Catalogs view by searching for + "Service Catalog" in the left-hand navigation. + 1. Click the plus sign in the top right. + 2. Select "Catalogs > Terraform Catalog > Title and Image" and choose a + location to add the Service Catalog. + 3. Close the "Sections" dialog box by clicking the "x" in the upper right-hand + corner. + +-> **Note:** In step 1, be sure to choose "Catalogs", not "Catalog" from the +left-hand navigation. + +## Configure VCS Repositories or No-Code Modules + +-> **ServiceNow Roles:** `admin` or `x_terraform.vcs_repositories_user` + +Terraform workspaces created through the ServiceNow Service Catalog for +Terraform can be associated with a VCS +provider repository or be backed by a [no-code +module](/terraform/enterprise/no-code-provisioning/provisioning) in your +organization's private registry. Administrators determine which workspace type +end users can request from the Terraform Catalog. Below are the key +differences between the version control and no-code approaches. + +### VCS configuration + +To make infrastructure available to your users through version control +workspaces, you must add one or more VCS repositories containing Terraform +configurations to the Service Catalog for Terraform. + +1. In ServiceNow, open the "Terraform > VCS Repositories" table by searching for + "Terraform" in the left-hand navigation. +2. Click "New" to add a VCS repository, and fill in the following fields: + - Name: The name for this repository. This name will be visible to end + users, and does not have to be the same as the repository name as defined + by your VCS provider. Ideally it will succinctly describe the + infrastructure that will be provisioned by Terraform from the repository. + - OAuth Token ID: The OAuth token ID that from your HCP Terraform + organization's VCS providers settings. This ID specifies which VCS + provider configured in HCP Terraform hosts the desired repository. + - Identifier: The VCS repository that contains the Terraform configuration + for this workspace template. Repository identifiers are determined by your + VCS provider; they typically use a format like + `/` or `/`. Azure DevOps + repositories use the format `//_git/`. + - The remaining fields are optional. + - Branch: The branch within the repository, if different from the default + branch. + - Working Directory: The directory within the repository containing + Terraform configuration. + - Terraform Version: The version of Terraform to use. This will default to + the latest version of Terraform supported by your HCP Terraform + instance. +3. Click "Submit". + +![Screenshot: ServiceNow New VCS Repository](/img/docs/service-now-vcs-repository.png "Screenshot of the ServiceNow Terraform New VCS Repository page") + +After configuring your repositories in ServiceNow, the names of those +repositories will be available in the "VCS Repository" dropdown menu a user +orders new workspaces through the following items in the Terraform Catalog: + +- **Create Workspace** +- **Create Workspace with Variables** +- **Provision Resources** +- **Provision Resources with Variables** + +### No-Code Module Configuration + +In version 2.5.0 and newer, ServiceNow administrators can configure +Catalog Items using [no-code +modules](/terraform/enterprise/no-code-provisioning/provisioning). This release +introduces two new additions to the Terraform Catalog - no-code workspace +create and update Items. Both utilize no-code modules from the private registry +in HCP Terraform to enable end users to request infrastructure without writing +code. + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +The following Catalog Items allow you to build and manage workspaces with +no-code modules: + +- **Provision No-Code Workspace and Deploy Resources**: creates a new Terraform + workspace based on a no-code module of your choice, supplies required variable + values, runs and applies Terraform. +- **Update No-Code Workspace and Deploy Resources**: Updates an existing no-code + workspace to the most recent no-code module version, updates that workspace's + attached variable values, and then starts and applies a new Terraform run. + +Administrators can skip configuring VCS repositories in ServiceNow when using +no-code modules. The only input required in the no-code workspace request form +is the name of the no-code module. + +Before utilizing a no-code module, you must publish it to the your organization's +private module registry. With this one-time configuration complete, ServiceNow +Administrators can then call the modules through Catalog requests without +repository management, simplifying the use of infrastructure-as-code. + +> **Hands On:** Try the [Self-service enablement with HCP Terraform and ServiceNow tutorial](/terraform/tutorials/it-saas/servicenow-no-code). + +## Configure a Variable Set + +Most Terraform configurations can be customized with Terraform variables or +environment variables. You can create a Variable Set within ServiceNow to +contain the variables needed for a given configuration. Your Terraform Admin +should provide these to you. + +1. In ServiceNow, open the "Service Catalog > Variable Sets" table by searching for + "variable sets" in the left-hand navigation. +2. Click "New" to add a Variable Set. +3. Select "Single-Row Variable Set". + - Title: User-visible title for the variable set. + - Internal name: The internal name for the variable set. + - Order: The order in which the variable set will be displayed. + - Type: Should be set to "Single Row" + - Application: Should be set to "Terraform" + - Display title: Whether the title is displayed to the end user. + - Layout: How the variables in the set will be displayed on the screen. + - Description: A long description of the variable set. +4. Click "Submit" to create the variable set. +5. Find and click on the title of the new variable set in the Variable Sets + table. +6. At the bottom of the variable set details page, click "New" to add a new + variable. + +- Type: Should be "Single Line Text" for most variables, or "Masked" for + variables containing sensitive values. +- Question: The user-visible question or label for the variable. +- Name: The internal name of the variable. This must be derived from the name of the + Terraform or environment variable. Consult the table below to determine the + proper prefix for each variable name. +- Tooltip: A tooltip to display for the variable. +- Example Text: Example text to show in the variable's input box. + +1. Under the "Default Value" tab, you can set a default value for the variable. +2. Continue to add new variables corresponding to the Terraform and environment + variables the configuration requires. + +When the Terraform integration applies configuration, it will map ServiceNow +variables to Terraform and environment variables using the following convention. +ServiceNow variables that begin with "sensitive\_" will be saved as sensitive +variables within HCP Terraform. + +| ServiceNow Variable Name | HCP Terraform Variable | +| -------------------------------- | ---------------------------------------------------------- | +| `tf_var_VARIABLE_NAME` | Terraform Variable: `VARIABLE_NAME` | +| `tf_env_ENV_NAME` | Environment Variable: `ENV_NAME` | +| `sensitive_tf_var_VARIABLE_NAME` | Sensitive Terraform Variable (Write Only): `VARIABLE_NAME` | +| `sensitive_tf_env_ENV_NAME` | Sensitive Environment Variable (Write Only): `ENV_NAME` | + +## Provision Infrastructure + +Once you configure the Service Catalog for Terraform, ServiceNow users +can request infrastructure to be provisioned by HCP Terraform. + +These requests will be fulfilled by HCP Terraform, which will: + +1. Create a new workspace from the no-code module or the VCS repository provided by ServiceNow. +2. Configure variables for that workspace, also provided by ServiceNow. +3. Plan and apply the change. +4. Report the results, including any outputs from Terraform, to ServiceNow. + +Once this is complete, ServiceNow will reflect that the Request Item has been +provisioned. + +-> **Note:** The integration creates workspaces with +[auto-apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) +enabled. HCP Terraform will queue an apply for these workspaces whenever +changes are merged to the associated VCS repositories. This is known as the +[VCS-driven run workflow](/terraform/enterprise/run/ui). It is important to keep in mind +that all of the ServiceNow workspaces connected to a given repository will be +updated whenever changes are merged to the associated branch in that repository. + +## Execution Mode + +If using v2.2.0 or above, the Service Catalog app allows you to set an [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) for your Terraform workspaces. There are two modes to choose from: + +- The default value is "Remote", which instructs HCP Terraform to perform runs on its disposable virtual machines. +- Selecting "Agent" mode allows you to run Terraform operations on isolated, private, or on-premises infrastructure. This option requires you to create an Agent Pool in your organization beforehand, then provide that Agent Pool's id when you order a new workspace through the Service Catalog. + + + +@include 'tfc-package-callouts/agents.mdx' + + + +## Workspace Name + +Version 2.4.0 of the Service Catalog for Terraform introduces the ability to set custom names for your Terraform workspaces. You can choose a prefix for your workspace name that the Service Catalog app will append the ServiceNow RITM number to. If you do not define a workspace prefix, ServiceNow will use RITM number as the workspace name. + +Workspace names can include letters, numbers, dashes (`-`), and underscores (`_`), and should not exceed 90 characters. +Refer to the [workspace naming recommendations](/terraform/enterprise/workspaces/create#workspace-naming) for best practices. + +## Workspace Tags + +Version 2.8.0 extends support for the key-value pair tags while still also supporting flat string tags version 2.4.0 introduced. Use the "Workspace Tags" field to provide a comma-separated list of key-value pair tags in the format "env: prod, instance: test" that will be parsed and attached to the workspace in HCP Terraform. + +Tags give you an easier way to categorize, filter, and manage workspaces provisioned through the Service Catalog for Terraform. +We recommend that you set naming conventions for tags with your end users to avoid variations such as `ec2`, `aws-ec2`, `aws_ec2`. + +Workspace tags have a 255 character limit and can contain letters, numbers, colons, hyphens, and underscores. Refer to the [workspace tagging rules](/terraform/enterprise/workspaces/create#workspace-tags) for more details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/troubleshoot.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/troubleshoot.mdx new file mode 100644 index 0000000000..b43864651c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-catalog-terraform/troubleshoot.mdx @@ -0,0 +1,120 @@ +--- +page_title: >- + Troubleshoot the ServiceNow Service Catalog Integration for Terraform + Enterprise +description: Troubleshooting tips for ServiceNow Service Catalog Integration. +source: terraform-docs-common +--- + +# Troubleshoot the ServiceNow Service Catalog integration + +This page offers troubleshooting tips for common issues with the ServiceNow Service Catalog Integration for HCP Terraform. +It also provides instructions on how to find and read logs to diagnose and resolve issues. + +## Find logs + +Logs are crucial for diagnosing issues. You can find logs in ServiceNow in the following places: + +### Workflow logs + +To find workflow logs, click on the RITM number on a failed ticket to open the request item. +Scroll down to **Related Links > Workflow Context** and open the **Workflow Log** tab. + +### Flow logs + +To find flow logs, click on the RITM number on a failed ticket to open the request item. +Scroll down to **Related Links > Flow Context > Open Context Record** and open the **Flow engine log entries** tab. + +### Application logs + +To find application logs, navigate to **All > System Log > Application Logs.** +Set the **Application** filter to "Terraform". +Search for logs around the time your issue occurred. Some records include HTTP status codes and detailed error messages. + +### Outbound requests + +ServiceNow logs all outgoing API calls, including calls to HCP Terraform. To view the log of outbound requests, navigate to **All > System Logs > Outbound HTTP Requests.** +To customize the table view, add columns like "URL," "URL Path," and "Application scope." +Logs from the Catalog app are marked with the `x_325709_terraform` scope. + +## Enable email notifications + +To enable email notifications and receive updates on your requested item tickets: + +1. Log in to your ServiceNow instance as an administrator. +2. **Click System Properties > Email Properties**. +3. In the **Outbound Email Configuration** panel, select **Yes** next to the check-box with the email that ServiceNow should send notifications to. + +To ensure you have relevant notifications configured in your instance: + +1. Navigate to **System Notification > Email > Notifications.** +2. Search for "Request Opened" and "Request Item Commented" and ensure they are activated. + +Reach out to ServiceNow customer support if you run into any issues with the global configurations. + +## Common problems + +This section details frequently encountered issues and how they can be resolved. + +### Failure to create a workspace + +If you order the "create a workspace" catalog item and nothing happens in ServiceNow and HCP Terraform does not create a workspace then there are several possible reasons why: + +Ensure your HCP Terraform token, hostname, and organization name is correct. + +1. Make sure to use a **Team API Token**. This can be found in HCP Terraform under "API Tokens". +2. Ensure the team API token has the correct permissions. +3. Double-check your organization name by copying and pasting it from HCP Terraform or Terraform Enterprise. +4. Double-check your host name. +5. Make sure you created your team API token in the same organization you are using +6. Test your configuration. First click **Update** to process any changes then \*\*Test Config to make sure the connection is working. + +Verify your VCS configuration. + +1. The **Identifier** field should not have any spaces. The ServiceNow Service Catalog Integration requires that you format repository names in the `username/repo_name` format. +2. The **Name** can be anything, but it is better to avoid special characters as per naming convention. +3. Double-check the OAuth token ID in your HCP Terraform/Terraform Enterprise settings. To retrieve your OAuth token ID, navigate to your HCP Terraform organization's settings page, then click **Provider** in the left navigation bar under **Version Control**. + +### Failure to successfully order any catalog item + +After placing an order for any catalog item, navigate to the comments section in the newly created RITM ticket. +The latest comment will contain a response from HCP Terraform. + +### Frequency of comments and outputs + +When you place an order in the Terraform Catalog, ServiceNow submits and processes the order, then attaches additional comments to the order to indicate whether HCP Terraform successfully created the workspace. + +By default, ServiceNow polls HCP Terraform every 5 minutes for the latest status of the Terraform run. ServiceNow does not show any comments until the next ping. + +To configure ServiceNow to poll HCP Terraform more frequently: + +1. Navigate to **All > Flow designer**. +2. Set the **Application** filter to **Terraform**. +3. Under the **Name** column click **Worker Poll Run State**. +4. Click on the trigger and adjust the interval to your desired schedule. +5. Click **Done > Save > Activate** to save your changes. + +### Using no-code modules feature + +If ServiceNow fails to deploy a no-code module catalog item, verify the following: + +1. Ensure that your HCP Terraform organization has an [HCP Plus tier](https://www.hashicorp.com/products/terraform/pricing) subscription. +2. Ensure the name you enter for your no-code module in the catalog user form matches the no-code module in HCP Terraform. + +### Updating no-code workspaces + +If the “update no-code workspace” catalog item returns the output message “No update has been made to the workspace”, then you have not upgraded your no-code module in HCP Terraform. + +### Application Scope + +If you are making customizations and you encounter unexpected issues, make sure to change the scope from **Global** to **Terraform** and recreate your customized items in the **Terraform scope**. +For additional instructions on customizations, refer to the [example customizations](/terraform/enterprise/integrations/service-now/service-catalog-terraform/example-customizations) documentation. + +### MID server + +If you are using a MID server in your configuration, check the connectivity by using the **Test Config** button on the configurations page. +Additionally, when ServiceNow provisions a MID server, navigate to **MID Servers > Servers** to check if the status is “up” and “validated”. + +### Configuration + +While the app allows multiple config entries, only one should be present as this can interfere with the functionality of the app. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/customizations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/customizations.mdx new file mode 100644 index 0000000000..9263ecc2a0 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/customizations.mdx @@ -0,0 +1,97 @@ +--- +page_title: Customize the ServiceNow Service Graph Connector for Terraform Enterprise +description: >- + Learn how to edit ETL mappings in the ServiceNow Service Graph Connector for + Terraform Enterprise integration. +source: terraform-docs-common +--- + +# Customize the ServiceNow Service Graph Connector for Terraform + +-> **ServiceNow roles:** `admin` + +-> **ServiceNow plugin requirement:** `IntegrationHub ETL` + +You can update and customize the default ETL mapping rules offered by the Service Graph Connector for Terraform. + +To ensure that your custom rules remain intact during future updates, you can clone the existing ETL record and maintain it separately from the default one. + +This documentation guides you through the process of mapping a resource using an example of an AWS virtual private network (VPC). Although this resource is already covered by the application, the principles discussed apply to any new potential resource mapping. + +Any customizations should be done from the application's scope: **Service Graph Connector for Terraform**. + +## Clone the ETL map + +Navigate to the **IntegrationHub ETL** in the top menu. Check the **SG-Terraform** record and click **Duplicate**. Refer to the [ServiceNow documentation](https://docs.servicenow.com/en-US/bundle/utah-servicenow-platform/page/product/configuration-management/task/duplicate-cmdb-transform-map.html) to create a duplicate of an existing ETL transform map. + +## Build a resource in HCP Terraform + +Create a new workspace in your HCP Terraform organization and create a Terraform resource that you would like to map. It helps to have a Terraform state record of the resource to ensure accurate mapping. + +[Configure a webhook](/terraform/enterprise/integrations/service-now/service-graph/service-graph-setup#configure-terraform-webhook) and initiate a Terraform run. + +## Download Terraform State + +Once the run is successfully completed, open your ServiceNow instance, click on **All** and navigate to **Scheduled Imports**. + +Open the **SG-Terraform Scheduled Process State** record, search for the import set corresponding to the latest webhook request. Click the **Import Set** field to open the import set. Wait for the import set to be successfully processed. + +Since there are no existing ETL rules configured for the new resource, it is ignored during the ETL process. + +Open the **Outbound Http Requests** tab to list the requests sent from your ServiceNow instance to HCP Terraform and get the latest state of the workspace. + +![ServiceNow Service Graph Connector Outbound Http Requests interface](/img/docs/service-now-service-graph-state-object-url.png) + +Open the record that starts with " by clicking on the timestamp. Copy the content of the URL field and open it you your browser to download the Terraform state file. + +Locate the resource in the state object. This JSON record will serve as a source for the future mapping. + +## Identify the CI target + +Pick a suitable Configuration Item (CI) target for your resource. For example, the AWS virtual private network (VPC) resource is mapped to Cloud Network (`cmdb_ci_network`) by the Service Graph Connector for Terraform. Refer to the [ServiceNow CMDB documentation](https://docs.servicenow.com/en-US/bundle/utah-servicenow-platform/page/product/configuration-management/reference/cmdb-tables-details.html) for more details on available CI tables. + +## Consult the CI Class Manager + +After selecting an appropriate CI target, it is important to consult the CI Class Manager for guidance on dependent relationships. Many CMDB resources rely on other CI tables. If a related class is not properly mapped, the ETL job will generate errors or warnings and fail to import your resource into the CMDB. + +In the top navigation, click on **All**, search for **CI Class Manager**, and click on **Open Hierarchy**. Search for your target CI Class and check **Dependent Relationships** tab to learn more about dependent mappings required by the resource. + +For example, according to the **CI Class Manager**, **Cloud Network** should be hosted on **Logical Datacenter** and **Cloud Service Account**. + +## Set the mapping rules + +Open the **IntegrationHub ETL** from the top navigation menu and select your cloned ETL map record prepared for customization. Refer to the [ServiceNow documentation](https://docs.servicenow.com/en-US/bundle/utah-servicenow-platform/page/product/configuration-management/concept/create-etl-transform-map.html) for instructions to create an ETL transform map. + +Click on the first **Specify Basic Details** section of the ETL Transform Map Assistant. Select the import set number containing your resource from the **Sample Import Set** dropdown and click **Mark as Complete**. + +Open the **Preview and Prepare Data** section and review the imported rows. Click **Mark as Complete**. + +The third section provides the interface for mapping resource attributes. Click on **Select CMDB Classes to Map Source Data**. Click on **Add Conditional Class** button at the top. Set the rules that will identify your resource in the import set. Use the `type` field value from the Terraform state object to identify your resource (on the ServiceNow side, field name are prefaced with `u_`). Set the target CMDB CI Class name and click **Save**. + +![ServiceNow Service Graph Connector: setting the Conditional Class rules in the ETL mapping](/img/docs/service-now-service-graph-conditional-class-mapping.png) + +To modify the mapping for your new Conditional Class record, select **Edit Mapping**. On the right side of the interface, drag the relevant data pills and drop them into the corresponding CMDB fields on the left side. Refer to the Terraform state record to verify the presence of attributes. For uniqueness, the **Source Native Key** value is typically mapped to the `arn` field when dealing with AWS resources. All resources mapped in the Service Graph Connector for Terraform will have the **Operational status** and **Name** fields populated. + +![ServiceNow Service Graph Connector: mapping resource attributes in the ETL](/img/docs/service-now-service-graph-etl-attribute-mapping.png) + +Once the mapping is completed, click on the left arrow at the top to return to the list of Conditional Classes. Map two more conditional classes in the same manner, according to the rules set in the CI Class Manager: **Logical Datacenter** (**AWS Datacenter** in case of AWS VPC) and **Cloud Service Account**. Since the AWS cloud provider is already covered by the application, these classes are already present. Click **Edit Class** to include your newly mapped resource into the listed conditional rules. Add another **OR** condition to each of them and click **Save**. + +![ServiceNow Service Graph Connector: updating conditions on existing parent records when a new resource is mapped](/img/docs/service-now-service-graph-etl-condition-update.png) + +Click **Mark as Complete** to finalize the **Select CMDB Classes to Map Source Data** section. + +## Set the required relationships + +Click **Add Relationships** to continue to the next section. Click the **Add Conditional Relationship** button at the top of the page. The following configuration tells the ETL that when a record with `aws_vpc` type is found in the import set, it should be hosted on **AWS Datacenter 1**. Click **Save**. + +![ServiceNow Service Graph Connector: setting dependent relationships in the ETL mapping interface](/img/docs/service-now-service-graph-etl-setting-relationship.png) + +A similar dependent relationship needs to be established from **AWS Datacenter** to **Cloud Service Account**. Since the AWS cloud provider is already covered by the application, the relationship record is present in the application. Click **Edit Relationship** and add another **OR** condition containing your new resource to the list. Click **Save**. + +![ServiceNow Service Graph Connector: updating existing dependent relationships in the ETL mapping interface](/img/docs/service-now-service-graph-etl-editing-relationship.png) + +Click **Mark as Complete** to finalize the **Add Relationships** section. + +## Run a test + +There are two ways to test the new resource mapping. You can utilize the **Test and Rollback Integration Results** interface of the ETL Transform Map Assistant. Alternatively, you can initiate a new run in your HCP Terraform workspace that includes the deployment of the resource. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/index.mdx new file mode 100644 index 0000000000..96b511744b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/index.mdx @@ -0,0 +1,83 @@ +--- +page_title: ServiceNow Service Graph Connector for Terraform Enterprise overview +description: >- + Use the ServiceNow Service Graph Connector to enable users to import Terraform + Enterprise-built infrastructure into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector for Terraform overview + +-> **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). + +The integration is based on the [Service Graph Connector](https://www.servicenow.com/products/service-graph-connectors.html) technology that provides a framework for discovering and mapping relationships between the organization's infrastructure and the ServiceNow Configuration Items (CIs), and then automatically updating the [ServiceNow CMDB (Configuration Management Database)](https://www.servicenow.com/products/servicenow-platform/configuration-management-database.html) with this information. This enables platform teams to gain a comprehensive view of the resources they support. The CMDB is a central repository within the ServiceNow platform, which provides a single source of truth for your infrastructure and offers configurable dashboards for monitoring and reporting. + +## Key benefits + +- **Enhanced visibility**: The Service Graph Connector for Terraform updates the CMDB dashboards with resources deployed in HCP Terraform. +- **Improved efficiency**: By connecting Terraform to the ServiceNow CMDB, platform teams can manage and search Terraform-provisioned resources in the CMDB alongside the rest of the company's infrastructure. +- **Consistent management**: Terraform state file changes get automatically and securely updated in the ServiceNow CMDB, capturing status changes for all technical resources in a timely manner. +- **Extensibility**: ServiceNow admins can customize mappings for additional resource types, potentially working with HashiCorp’s entire Terraform ecosystem made up of thousands of providers. + +## Technical design + +The diagram below shows how the Service Graph Connector for Terraform connects HCP Terraform to your ServiceNow instance. + +![ServiceNow Service Graph Connector for Terraform: design diagram](/img/docs/service-now-service-graph-design.png) + +The Service Graph Connector for Terraform integrates with HCP Terraform to fetch up-to-date information about your deployments. It leverages the Terraform state as the primary data source. The application doesn't make any requests to your cloud provider or require you to share any cloud credentials. + +## Import methods + +The integration offers two methods of importing your Terraform resources into CMDB. You can configure the application to periodically pull all your resources in one batch. Alternatively, you can set up webhooks in your Terraform workspaces, which will notify your ServiceNow instance about new deployments. + +### Scheduled polling + +The Service Graph Connector for Terraform can be scheduled to periodically poll HCP Terraform. Depending on the size of your infrastructure and how frequently the state of your resources needs to be refreshed in CMDB, the polling schedule can be set anywhere from once a week to every second. This option is not recommended for big environments with thousands of Terraform workspaces as the import job will take several hours to complete. + +The scheduled job makes a request to HCP Terraform to obtain all organizations that the HCP Terraform API token provided to the application has access to. It will attempt to import all relevant resources from all workspaces within each of those organizations. The processing time depends of the number of organizations and workspaces in HCP Terraform. Configuring the import job to run frequently is not recommended for big environments. + +To access the scheduler, search for **Service Graph Connector for Terraform** in the top navigation menu and select **SG-Import Schedule**. You can change the polling settings and view all previous import sets pulled into your ServiceNow instance using this method. + +### HCP Terraform Webhook Notifications + +You can configure [webhook notifications](/terraform/enterprise/workspaces/settings/notifications) for all relevant workspaces in HCP Terraform organization. Webhooks offer an event-based approach to importing your resources. The import is triggered as soon as a Terraform run is successfully completed in HCP Terraform. + +Webhook POST requests are sent to an API endpoint exposed by the Service Graph Connector for Terraform in your ServiceNow instance. Each webhook request includes an HMAC token, and the endpoint validates the signature using the secret you provide. Learn more about [HCP Terraform notification authenticity](/terraform/enterprise/workspaces/settings/notifications#notification-authenticity). + +Internally, the application uses a scheduled job as a helper to keep track of the incoming webhook requests. To activate, configure, and view the history of all webhook imports, navigate to **Scheduled Imports** and select **SG-Terraform Scheduled Process State**. By default, the job is set to run every minute. + +-> **Tip:** Both import options may be enabled, or you may choose to configure only the webhooks or the scheduled import. + +The [setup page](/terraform/enterprise/integrations/service-now/service-graph/service-graph-setup) provides configuration details for both import modes. + +## ETL (Extract, Transform, Load) + +After the application successfully imports the resources, they are temporarily stored in a staging database table. The import set records are then transferred to the ETL (Extract, Transform, Load) pipeline. Search for **IntegrationHub ETL** in the top navigation menu to view and edit the default ETL rules of the Service Graph Connector for Terraform. The application's ETL Transform Map is called **SG-Terraform**. + +To deactivate resources that you do not want imported into the CMDB, navigate to the **Select CMDB Classes to Map Source Data** section of the application's ETL record, and toggle the switch on the resource mapping record to deactivate it. + +![screenshot: ServiceNow Service Graph Connector for Terraform resource ETL deactivation button](/img/docs/service-now-service-graph-deactivate-etl.png) + +-> **Tip:** Run an import before you open the ETL map as the interface requires at least one import set stored in the memory to be able to display the rules. + +## Supported resources + +The Service Graph Connector for Terraform supports selected resources from the following cloud providers: + +- AWS +- Microsoft Azure +- Google Cloud +- VMware vSphere + +The [resource mapping](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage) documentation contains tables detailing the mapping of objects and attributes between HCP Terraform and ServiceNow CMDB. + +## Destroyed resources + +After the destroy operation is completed in HCP Terraform and the application's import job is finished in your ServiceNow instance, the **Operational Status** field of all resources in the CMDB removed from the Terraform state during the deletion process will be updated to **Non-Operational**. + +## Get started + +Refer to the [setup page](/terraform/enterprise/integrations/service-now/service-graph/service-graph-setup) for information on how to configure the integration in your ServiceNow instance. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/aws.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/aws.mdx new file mode 100644 index 0000000000..d2ccc40b18 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/aws.mdx @@ -0,0 +1,219 @@ +--- +page_title: ServiceNow Service Graph Connector AWS resource coverage +description: >- + Use the ServiceNow Service Graph integration to import selected resources from + AWS into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector AWS resource coverage + +This page details the mapping rules for importing AWS resources, provisioned with Terraform, into ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| AWS resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ------------------------------------------------------------------------------------- | --------------------------- | -------------------------------- | ----------------------------- | +| AWS account | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| AWS region | N/A | `cmdb_ci_aws_datacenter` | AWS Datacenter | +| EC2 Instance | `aws_instance` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| S3 Bucket | `aws_s3_bucket` | `cmdb_ci_cloud_object_storage` | Cloud Object Storage | +| ECS Cluster | `aws_ecs_cluster` | `cmdb_ci_cloud_ecs_cluster` | AWS Cloud ECS Cluster | +| EKS Cluster | `aws_eks_cluster` | `cmdb_ci_kubernetes_cluster` | Kubernetes Cluster | +| VPC | `aws_vpc` | `cmdb_ci_network` | Cloud Network | +| Database Instance (_non-Aurora databases: e.g., MySQL, PostgreSQL, SQL Server, etc._) | `aws_db_instance` | `cmdb_ci_cloud_database` | Cloud DataBase | +| RDS Aurora Cluster | `aws_rds_cluster` | `cmdb_ci_cloud_db_cluster` | Cloud DataBase Cluster | +| RDS Aurora Instance | `aws_rds_cluster_instance` | `cmdb_ci_cloud_database` | Cloud DataBase | +| DynamoDB Global Table | `aws_dynamodb_global_table` | `cmdb_ci_dynamodb_global_table` | DynamoDB Global Table | +| DynamoDB Table | `aws_dynamodb_table` | `cmdb_ci_dynamodb_table` | DynamoDB Table | +| Security Group | `aws_security_group` | `cmdb_ci_compute_security_group` | Compute Security Group | +| Lambda | `aws_lambda_function` | `cmdb_ci_cloud_function` | Cloud Function | +| Load Balancer | `aws_lb` | `cmdb_ci_cloud_load_balancer` | Cloud Load Balancer | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ----------------------------------------------------------- | ----------------- | --------------------------------------------------------- | +| AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | Hosted On::Hosts | Cloud Service Account 1 (`cmdb_ci_cloud_service_account`) | +| AWS Datacenter 2 (`cmdb_ci_aws_datacenter`) | Hosted On::Hosts | Cloud Service Account 6 (`cmdb_ci_cloud_service_account`) | +| Virtual Machine Instance 1 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Virtual Machine Instance 1 (`cmdb_ci_vm_instance`) | Reference | Key Value 1 (`cmdb_key_value`) | +| AWS Cloud ECS Cluster 1 (`cmdb_ci_cloud_ecs_cluster`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| AWS Cloud ECS Cluster 1 (`cmdb_ci_cloud_ecs_cluster`) | Reference | Key Value 2 (`cmdb_key_value`) | +| Cloud Object Storage 1 (`cmdb_ci_cloud_object_storage`) | Hosted On::Hosts | AWS Datacenter 2 (`cmdb_ci_aws_datacenter`) | +| Cloud Object Storage 1 (`cmdb_ci_cloud_object_storage`) | Reference | Key Value 3 (`cmdb_key_value`) | +| Kubernetes Cluster 1 (`cmdb_ci_kubernetes_cluster`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Kubernetes Cluster 1 (`cmdb_ci_kubernetes_cluster`) | Reference | Key Value 4 (`cmdb_key_value`) | +| Cloud Network 1 (`cmdb_ci_network`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud Network 1 (`cmdb_ci_network`) | Reference | Key Value 5 (`cmdb_key_value`) | +| Cloud DataBase 1 (`cmdb_ci_cloud_database` ) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud DataBase 1 (`cmdb_ci_cloud_database` ) | Reference | Key Value 6 (`cmdb_key_value`) | +| Cloud DataBase Cluster 1 (`cmdb_ci_cloud_db_cluster`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud DataBase Cluster 1 (`cmdb_ci_cloud_db_cluster`) | Reference | Key Value 7 (`cmdb_key_value`) | +| DynamoDB Global Table 1 (`cmdb_ci_dynamodb_global_table`) | Hosted On::Hosts | Cloud Service Account 1 (`cmdb_ci_cloud_service_account`) | +| DynamoDB Table 1 (`cmdb_ci_dynamodb_table`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| DynamoDB Table 1 (`cmdb_ci_dynamodb_table`) | Reference | Key Value 8 (`cmdb_key_value`) | +| Compute Security Group 1 (`cmdb_ci_compute_security_group`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Compute Security Group 1 (`cmdb_ci_compute_security_group`) | Reference | Key Value 10 (`cmdb_key_value`) | +| Cloud Function 1 (`cmdb_ci_cloud_function`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud Function 1 (`cmdb_ci_cloud_function`) | Reference | Key Value 11 (`cmdb_key_value`) | +| Cloud Load Balancer 1 (`cmdb_ci_cloud_load_balancer`) | Hosted On::Hosts | AWS Datacenter 1 (`cmdb_ci_aws_datacenter`) | +| Cloud Load Balancer 1 (`cmdb_ci_cloud_load_balancer`) | Reference | Key Value 12 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | -------------------------------------------- | +| Source Native Key | Resource account number extracted from `arn` | +| Account Id | Resource account number extracted from `arn` | +| Datacenter Type | Resource cloud provider extracted from `arn` | +| Object ID | Resource id extracted from `arn` | +| Name | Resource name extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### AWS Datacenter (`cmdb_ci_aws_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | --------------------------------------------------------------- | +| Source Native Key | Concatenation of region and account number extracted from `arn` | +| Object Id | Region extracted from `arn` | +| Region | Region extracted from `arn` | +| Name | Region extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### Virtual Machine Instance (`cmdb_ci_vm_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Placement Group ID | `placement_group` | +| IP Address | `public_ip` | +| Status | `instance_state` | +| VM Instance ID | `id` | +| Name | `id` | +| State | `state` | +| CPU | `cpu_core_count` | +| Operational Status | Defaults to "1" ("Operational") | + +### AWS Cloud ECS Cluster (`cmdb_ci_cloud_ecs_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Object Storage (`cmdb_ci_cloud_object_storage`) + +| CMDB field | Terraform state field | +| ------------------ | -------------------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Cloud Provider | Resource cloud provider extracted from `arn` | +| Name | `bucket` | +| Operational Status | Defaults to "1" ("Operational") | + +### Kubernetes Cluster (`cmdb_ci_kubernetes_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| IP Address | `endpoint` | +| Port | Defaults to "6443" | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Network (`cmdb_ci_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase (`cmdb_ci_cloud_database`) + +| CMDB field | Terraform state field | +| --------------------------- | -------------------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Version | `engine_version` | +| Type | `engine` | +| TCP port(s) | `port` | +| Category | `instance_class` | +| Fully qualified domain name | `endpoint` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Vendor | Resource cloud provider extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase Cluster (`cmdb_ci_cloud_db_cluster`) + +| CMDB field | Terraform state field | +| --------------------------- | -------------------------------------------- | +| Source Native Key | `arn` | +| Cluster ID | `cluster_resource_id` | +| Name | `name` | +| TCP port(s) | `port` | +| Fully qualified domain name | `endpoint` | +| Vendor | Resource cloud provider extracted from `arn` | +| Operational Status | Defaults to "1" ("Operational") | + +### DynamoDB Table (`cmdb_ci_dynamodb_table`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `arn` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### DynamoDB Global Table (`cmdb_ci_dynamodb_global_table`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Compute Security Group (`cmdb_ci_compute_security_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Function (`cmdb_ci_cloud_function`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `arn` | +| Language | `runtime` | +| Code Size | `source_code_size` | +| Location | Region extracted from `arn` | +| Name | `function_name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Load Balancer (`cmdb_ci_cloud_load_balancer`) + +| CMDB field | Terraform state field | +| -------------------------- | ------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Canonical Hosted Zone Name | `dns_name` | +| Canonical Hosted Zone ID | `zone_id` | +| Location | Region extracted from `arn` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/azure.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/azure.mdx new file mode 100644 index 0000000000..0a503bec63 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/azure.mdx @@ -0,0 +1,158 @@ +--- +page_title: ServiceNow Service Graph Connector Microsoft Azure resource coverage +description: >- + Use the ServiceNow Service Graph integration to import selected resources from + Microsoft Azure into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector Microsoft Azure resource coverage + +This page describes how Terraform-provisioned Azure resources are mapped to the classes within the ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| Azure resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ---------------------- | --------------------------------- | -------------------------------- | ----------------------------- | +| Azure account | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| Azure region | N/A | `cmdb_ci_azure_datacenter` | Azure Datacenter | +| Resource Group | `azurerm_resource_group` | `cmdb_ci_resource_group` | Resource Group | +| Windows VM | `azurerm_windows_virtual_machine` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| Linux VM | `azurerm_linux_virtual_machine` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| AKS Cluster | `azurerm_kubernetes_cluster` | `cmdb_ci_kubernetes_cluster` | Kubernetes Cluster | +| Storage Container | `azurerm_storage_container` | `cmdb_ci_cloud_storage_account` | Cloud Storage Account | +| MariaDB Database | `azurerm_mariadb_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| MS SQL Database | `azurerm_mssql_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| MySQL Database | `azurerm_mysql_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| PostgreSQL Database | `azurerm_postgresql_server` | `cmdb_ci_cloud_database` | Cloud DataBase | +| Network security group | `azurerm_network_security_group` | `cmdb_ci_compute_security_group` | Compute Security Group | +| Linux Function App | `azurerm_linux_function_app` | `cmdb_ci_cloud_function` | Cloud Function | +| Windows Function App | `azurerm_windows_function_app` | `cmdb_ci_cloud_function` | Cloud Function | +| Virtual Network | `azurerm_virtual_network` | `cmdb_ci_network` | Cloud Network | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ----------------------------------------------------------- | ---------------------- | --------------------------------------------------------- | +| Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | Hosted On::Hosts | Cloud Service Account 2 (`cmdb_ci_cloud_service_account`) | +| Azure Datacenter 2 (`cmdb_ci_azure_datacenter`) | Hosted On::Hosts | Cloud Service Account 3 (`cmdb_ci_cloud_service_account`) | +| Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | Contains::Contained by | Resource Group 1 (`cmdb_ci_resource_group`) | +| Cloud Storage Account 1 (`cmdb_ci_cloud_storage_account`) | Hosted On::Hosts | Azure Datacenter 2 (`cmdb_ci_azure_datacenter`) | +| Virtual Machine Instance 2 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Virtual Machine Instance 2 (`cmdb_ci_vm_instance`) | Reference | Key Value 14 (`cmdb_key_value`) | +| Virtual Machine Instance 3 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Virtual Machine Instance 3 (`cmdb_ci_vm_instance`) | Reference | Key Value 15 (`cmdb_key_value`) | +| Kubernetes Cluster 2 (`cmdb_ci_kubernetes_cluster`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Kubernetes Cluster 2 (`cmdb_ci_kubernetes_cluster`) | Reference | Key Value 16 (`cmdb_key_value`) | +| Cloud DataBase 2 (`cmdb_ci_cloud_database` ) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Cloud DataBase 2 (`cmdb_ci_cloud_database` ) | Reference | Key Value 9 (`cmdb_key_value`) | +| Compute Security Group 2 (`cmdb_ci_compute_security_group`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Compute Security Group 2 (`cmdb_ci_compute_security_group`) | Reference | Key Value 17 (`cmdb_key_value`) | +| Cloud Function 2 (`cmdb_ci_cloud_function`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Cloud Function 2 (`cmdb_ci_cloud_function`) | Reference | Key Value 19 (`cmdb_key_value`) | +| Cloud Network 2 (`cmdb_ci_network`) | Hosted On::Hosts | Azure Datacenter 1 (`cmdb_ci_azure_datacenter`) | +| Cloud Network 2 (`cmdb_ci_network`) | Reference | Key Value 20 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | ----------------------------------- | +| Source Native Key | Subscription ID extracted from `id` | +| Account Id | Subscription ID extracted from `id` | +| Datacenter Type | Defaults to `azure` | +| Object ID | Subscription ID extracted from `id` | +| Name | Subscription ID extracted from `id` | +| Operational Status | Defaults to "1" ("Operational") | + +### Azure Datacenter (`cmdb_ci_azure_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | ----------------------------------------------- | +| Source Native Key | Concatenation of `location` and Subscription ID | +| Object Id | `location` | +| Region | `location` | +| Name | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Virtual Machine Instance (`cmdb_ci_vm_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Storage Account (`cmdb_ci_cloud_storage_account`) + +| CMDB field | Terraform state field | +| --------------------------- | ------------------------------- | +| Source Native Key | `resource_manager_id` | +| Object Id | `resource_manager_id` | +| Fully qualified domain name | `id` | +| Blob Service | `storage_account_name` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Resource Group (`cmdb_ci_resource_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Location | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Kubernetes Cluster (`cmdb_ci_kubernetes_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| IP Address | `fqdn` | +| Port | Defaults to "6443" | +| Name | `name` | +| Location | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase (`cmdb_ci_cloud_database`) + +| CMDB field | Terraform state field | +| --------------------------- | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Version | `engine_version` | +| Fully qualified domain name | `fqdn` | +| Name | `name` | +| Vendor | Defaults to `azure` | +| Operational Status | Defaults to "1" ("Operational") | + +### Compute Security Group (`cmdb_ci_compute_security_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Function (`cmdb_ci_cloud_function`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Network (`cmdb_ci_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/gcp.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/gcp.mdx new file mode 100644 index 0000000000..5681430c8b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/gcp.mdx @@ -0,0 +1,159 @@ +--- +page_title: ServiceNow Service Graph Connector Google Cloud resource coverage +description: >- + Use the ServiceNow Service Graph for Terraform Enterprise integration to + import selected resources from Google Cloud into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector Google Cloud resource coverage + +This page provides details on how Google Cloud resources, set up using Terraform, are corresponded to the classes within the ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| Google resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ------------------------ | --------------------------------------------------------------------- | -------------------------------- | ----------------------------- | +| Project ID | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| Region (location) | N/A | `cmdb_ci_google_datacenter` | Google Datacenter | +| Virtual Machine Instance | `google_compute_instance` | `cmdb_ci_vm_instance` | Virtual Machine Instance | +| Kubernetes Cluster | `google_container_cluster` | `cmdb_ci_kubernetes_cluster` | Kubernetes Cluster | +| Google Storage | `google_storage_bucket` | `cmdb_ci_cloud_storage_account` | Cloud Storage Account | +| Google BigQuery | `google_bigquery_table` | `cmdb_ci_cloud_database` | Cloud DataBase | +| Google SQL | `google_sql_database` | `cmdb_ci_cloud_database` | Cloud DataBase | +| Google Compute Firewall | `google_compute_firewall` | `cmdb_ci_compute_security_group` | Compute Security Group | +| Cloud Function | `google_cloudfunctions_function` or `google_cloudfunctions2_function` | `cmdb_ci_cloud_function` | Cloud Function | +| Load Balancer | `google_compute_forwarding_rule` | `cmdb_ci_cloud_load_balancer` | Cloud Load Balancer | +| VPC | `google_compute_network` | `cmdb_ci_network` | Cloud Network | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ----------------------------------------------------------- | ----------------- | --------------------------------------------------------- | +| Google Datacenter 1 (`cmdb_ci_google_datacenter`) | Hosted On::Hosts | Cloud Service Account 4 (`cmdb_ci_cloud_service_account`) | +| Google Datacenter 2 (`cmdb_ci_google_datacenter`) | Hosted On::Hosts | Cloud Service Account 4 (`cmdb_ci_cloud_service_account`) | +| Virtual Machine Instance 4 (`cmdb_ci_vm_instance`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Virtual Machine Instance 4 (`cmdb_ci_vm_instance`) | Reference | Key Value 13 (`cmdb_key_value`) | +| Cloud Network 3 (`cmdb_ci_network`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud Network 3 (`cmdb_ci_network`) | Reference | Key Value 18 (`cmdb_key_value`) | +| Compute Security Group 3 (`cmdb_ci_compute_security_group`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Compute Security Group 3 (`cmdb_ci_compute_security_group`) | Reference | Key Value 21 (`cmdb_key_value`) | +| Kubernetes Cluster 3 (`cmdb_ci_kubernetes_cluster`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Kubernetes Cluster 3 (`cmdb_ci_kubernetes_cluster`) | Reference | Key Value 22 (`cmdb_key_value`) | +| Cloud DataBase 3 (`cmdb_ci_cloud_database` ) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud DataBase 2 (`cmdb_ci_cloud_database` ) | Reference | Key Value 24 (`cmdb_key_value`) | +| Cloud Function 3 (`cmdb_ci_cloud_function`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud Function 3 (`cmdb_ci_cloud_function`) | Reference | Key Value 25 (`cmdb_key_value`) | +| Cloud Load Balancer 2 (`cmdb_ci_cloud_load_balancer`) | Hosted On::Hosts | Google Datacenter 1 (`cmdb_ci_google_datacenter`) | +| Cloud Load Balancer 2 (`cmdb_ci_cloud_load_balancer`) | Reference | Key Value 26 (`cmdb_key_value`) | +| Cloud Storage Account 2 (`cmdb_ci_cloud_storage_account`) | Hosted On::Hosts | Google Datacenter 2 (`cmdb_ci_google_datacenter`) | +| Cloud Storage Account 2 (`cmdb_ci_cloud_storage_account`) | Reference | Key Value 23 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `project` | +| Account Id | `project` | +| Datacenter Type | Defaults to `google` | +| Object ID | `project` | +| Name | `project` | +| Operational Status | Defaults to "1" ("Operational") | + +### Google Datacenter (`cmdb_ci_google_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | --------------------------------------------------------- | +| Source Native Key | Concatenation of `project` and region extracted from `id` | +| Object Id | Region extracted from `id` | +| Region | Region extracted from `id` | +| Name | Region extracted from `id` | +| Operational Status | Defaults to "1" ("Operational") | + +### Virtual Machine Instance (`cmdb_ci_vm_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Category | `machine_type` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Network (`cmdb_ci_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Compute Security Group (`cmdb_ci_compute_security_group`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Kubernetes Cluster (`cmdb_ci_kubernetes_cluster`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `arn` | +| IP Address | `endpoint` | +| Port | Defaults to "6443" | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Object Storage (`cmdb_ci_cloud_object_storage`) + +| CMDB field | Terraform state field | +| ------------------ | -------------------------------------------- | +| Source Native Key | `arn` | +| Object Id | `id` | +| Cloud Provider | Resource cloud provider extracted from `arn` | +| Name | `bucket` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Storage Account (`cmdb_ci_cloud_storage_account`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Name | `location` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud DataBase (`cmdb_ci_cloud_database`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | Name extracted from `id` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Function (`cmdb_ci_cloud_function`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### Cloud Load Balancer (`cmdb_ci_cloud_load_balancer`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/index.mdx new file mode 100644 index 0000000000..ec81da07cc --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/index.mdx @@ -0,0 +1,37 @@ +--- +page_title: >- + ServiceNow Service Graph Connector for Terraform Enterprise resource coverage + overview +description: >- + The ServiceNow Service Graph for Terraform Enterprise integration imports + selected resources from major cloud providers into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector for Terraform resource coverage overview + +The tables provided in this section illustrate the mapping of resources from the Terraform state to the ServiceNow CMDB configuration items (CIs) by the Service Graph Connector for Terraform. + +While the default ETL map provided by the application can be utilized without modification, it is also possible to customize it according to the specific requirements of your organization. Check [customizations](/terraform/enterprise/integrations/service-now/service-graph/customizations) for more details. + +The application supports selected resources from major cloud providers. The following pages provide mapping details for each supported provider: + +- [AWS](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/aws) +- [Azure](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/azure) +- [GCP](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/gcp) +- [VMware vSphere](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere) + +# Importing Tags + +The Service Graph Connector for Terraform imports the Terraform tags associated with your resource into CMDB. Tags are mapped to the **Key Value** CI Class. +Along with the tags assigned in your Terraform code, the integration also includes `tf_organization` and `tf_workspace` tags. These tags are used to indicate the HCP Terraform organization and workspace where the resource was provisioned. + +The visibility of the **Tags** tab in CMDB varies for different configuration items. By default, not every configuration item has the **Tags** tab enabled. For instance, the **Virtual Machine Instance** class page includes the **Tags** tab, whereas the **AWS Cloud ECS Cluster** page does not. + +The following example illustrates how the **Tags** tab can be enabled for **AWS Cloud ECS Cluster** CI class in CMDB. + +1. Enter `cmdb_ci_cloud_ecs_cluster.list` in the search menu of your ServiceNow instance. +2. Open any record. Right-click on the gray bar at the top, select **Configure** and proceed to **Related Lists**. If you are in a different scope, click **Edit this view**. +3. Transfer **Key Value->Configuration item** from the left column to the right and click **Save**. Tags become available in CMDB for all AWS ECS cluster records. + +![screenshot: ServiceNow Service Graph Connector - enable the Tags tab in CMDB](/img/docs/service-now-service-graph-tags.png) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere.mdx new file mode 100644 index 0000000000..9e9f91fe20 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/resource-coverage/vsphere.mdx @@ -0,0 +1,84 @@ +--- +page_title: ServiceNow Service Graph Connector VMware vSphere resource coverage +description: >- + Use the ServiceNow Service Graph integration to import selected resources from + VMware vSphere into ServiceNow CMDB. +source: terraform-docs-common +--- + +# ServiceNow Service Graph Connector VMware vSphere resource coverage + +This page explains the rules of associating VMware vSphere resources, created via Terraform, with the classes in the ServiceNow CMDB. + +## Mapping of Terraform resources to CMDB CI Classes + +| vSphere resource | Terraform resource name | ServiceNow CMDB CI Class | ServiceNow CMDB Category Name | +| ------------------------- | --------------------------- | ------------------------------- | ------------------------------- | +| vCenter server | N/A | `cmdb_ci_cloud_service_account` | Cloud Service Account | +| vSphere Datacenter | `vsphere_datacenter` | `cmdb_ci_vcenter_datacenter` | VMware vCenter Datacenter | +| vSphere Virtual Machine | `vsphere_virtual_machine` | `cmdb_ci_vmware_instance` | VMware Virtual Machine Instance | +| vSphere Datastore Cluster | `vsphere_datastore_cluster` | `cmdb_ci_vcenter_datastore` | VMware vCenter Datastore | +| vSphere Network | `vsphere_network` | `cmdb_ci_vcenter_network` | VMware vCenter Network | +| Tags | N/A | `cmdb_key_value` | Key Value | + +## Resource relationships + +| Child CI Class | Relationship type | Parent CI Class | +| ------------------------------------------------------------- | ----------------- | ---------------------------------------------------------- | +| VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | Hosted On::Hosts | Cloud Service Account 5 (`cmdb_ci_cloud_service_account`) | +| VMware Virtual Machine Instance 1 (`cmdb_ci_vmware_instance`) | Hosted On::Hosts | VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | +| VMware Virtual Machine Instance 1 (`cmdb_ci_vmware_instance`) | Reference | Key Value 27 (`cmdb_key_value`) | +| VMware vCenter Network 1 (`cmdb_ci_vcenter_network`) | Hosted On::Hosts | VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | +| VMware vCenter Network 1 (`cmdb_ci_vcenter_network`) | Reference | Key Value 28 (`cmdb_key_value`) | +| VMware vCenter Datastore 1 (`cmdb_ci_vcenter_datastore`) | Hosted On::Hosts | VMware vCenter Datacenter 1 (`cmdb_ci_vcenter_datacenter`) | +| VMware vCenter Datastore 1 (`cmdb_ci_vcenter_datastore`) | Reference | Key Value 29 (`cmdb_key_value`) | + +## Field attributes mapping + +### Cloud Service Account (`cmdb_ci_cloud_service_account`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | Defaults to "VMware_vCenter" | +| Account Id | Defaults to "VMware_vCenter" | +| Datacenter Type | Defaults to "VMware_vCenter" | +| Object ID | Defaults to "VMware_vCenter" | +| Name | Defaults to "VMware_vCenter" | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware vCenter Datacenter (`cmdb_ci_vcenter_datacenter`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `datacenter_id` | +| Object Id | `datacenter_id` | +| Region | `datacenter_id` | +| Name | `datacenter_id` | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware Virtual Machine Instance (`cmdb_ci_vmware_instance`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware vCenter Network (`cmdb_ci_vcenter_network`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | + +### VMware vCenter Datastore (`cmdb_ci_vcenter_datastore`) + +| CMDB field | Terraform state field | +| ------------------ | ------------------------------- | +| Source Native Key | `id` | +| Object Id | `id` | +| Name | `name` | +| Operational Status | Defaults to "1" ("Operational") | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/service-graph-setup.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/service-graph-setup.mdx new file mode 100644 index 0000000000..c71384b3d3 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/integrations/service-now/service-graph/service-graph-setup.mdx @@ -0,0 +1,162 @@ +--- +page_title: Set up the ServiceNow Service Graph Connector for Terraform Enterprise +description: >- + Learn how to set up the ServiceNow Service Graph Connector for Terraform + Enterprise. +source: terraform-docs-common +--- + +# Set up the ServiceNow Service Graph Connector + +-> **Note:** Follow the [Configure ServiceNow Service Graph Connector for HCP Terraform](/terraform/tutorials/it-saas/servicenow-sgc) tutorial for hands-on instructions on how to import an AWS resource deployed in your HCP Terraform organization to the ServiceNow CMDB by using the Service Graph Connector for Terraform. + +The ServiceNow Service Graph Connector for Terraform is a certified scoped application available in the ServiceNow Store. Search for ”Service Graph Connector for Terraform” published by ”HashiCorp Inc” and click **Install**. + +## Prerequisites + +To start using the Service Graph Connector for Terraform, you must have: + +- An administrator account on a Terraform Enterprise instance or within an HCP Terraform organization. +- An administrator account on your ServiceNow vendor instance. + +The Service Graph Connector for Terraform supports the following ServiceNow server versions: + +- Washington DC +- Xanadu +- Yokohama + +The following ServiceNow plugins are required dependencies: + +- ITOM Discovery License +- Integration Commons for CMDB +- Discovery and Service Mapping Patterns +- ServiceNow IntegrationHub Standard Pack + +Additionally, you can install the IntegrationHub ETL application if you want to modify the default CMDB mappings. + +-> **Note:** Dependent plugins are installed on your ServiceNow instance automatically when the app is downloaded from the ServiceNow Store. Before installing the Service Graph Connector for Terraform, you must activate the ITOM Discovery License plugin in your production instance. + +## Connect ServiceNow to HCP Terraform + +-> **ServiceNow roles:** `admin`, `x_hashi_service_gr.terraform_user` + +Once the integration is installed, you can proceed to the guided setup form where you will enter your Terraform credentials. This step will establish a secure connection between HCP Terraform and your ServiceNow instance. + +### Create and scope Terraform API token + +In order for ServiceNow to connect to HCP Terraform, you must give it an HCP Terraform API token. The permissions of this token determine what resources the Service Graph Connector will import into the CMDB. While you could use a user API token, it could import resources from multiple organizations. By providing a team API token, you can scope permissions to only import resources from specified workspaces within a single organization. + +To create a team API token: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to create a team token. +2. Choose **Settings** from the sidebar, then **Teams**. +3. In **Team API Token** section, click **Create a team token**. + +Save this token in a safe place since HCP Terraform only displays it once. You will use it to configure ServiceNow in the next section. + +![ServiceNow Service Graph Connector Configure Team API token in HCP Terraform](/img/docs/service-now-service-graph-team-token-gen.png) + +### Configure Service Graph Connector for Terraform API token + +In the top navigation of your ServiceNow instance's control panel, click on **All**, search for **Service Graph Connector for Terraform**, and click **SG-Setup**. Next, click **Get Started**. + +Next, in the **Configure the Terraform connection** section, click **Get Started**. + +In the **Configure Terraform authentication credentials** section, click **Configure**. + +If you want to route traffic between your HCP Terraform and the ServiceNow instance through a MID server acting as a proxy, change the **Applies to** dropdown to "Specific MID servers" and select your previously configured MID server name. If you don't use MID servers, leave the default value. + +Set the **API Key** to the HCP Terraform team API token that you created in the previous section and click **Update**. + +![ServiceNow Service Graph Connector API Key Credentials configuration screen. The API key is provided, then saved by clicking the Update button](/img/docs/service-now-service-graph-apikey.png) + +In the **Configure Terraform authentication credentials** section, click **Mark as Complete**. + +### Configure Terraform Webhook Notification token + +To improve security, HCP Terraform includes an HMAC signature on all "generic" webhook notifications using a user-provided **token**. This token is an arbitrary secret string that HCP Terraform uses to sign each webhook notification. ServiceNow uses the same token to verify the request authenticity. Refer to [Notification Authenticity](/terraform/enterprise/api-docs/notification-configurations#notification-authenticity) for more information. + +Create a token and save it in a safe place. This secret token can be any value but should be treated as sensitive. + +In the **Configure Terraform Webhook token** section, click **Configure**. In the **Token** field, enter the secret token that will be shared between the HCP Terraform and your ServiceNow instance and click **Update**. + +![ServiceNow Service Graph Connector Webhook token configuration screen. The Token is provided, then saved by clicking the Update button](/img/docs/service-now-service-graph-webhook-token.png) + +In the **Configure Terraform Webhook token** section, click **Mark as Complete**. + +### Configure Terraform connection + +In the **Configure Terraform connection** section, click **Configure**. + +If you are using Terraform Enterprise, set the **Connection URL** to the URL of your Terraform Enterprise instance. If you are using HCP Terraform, leave the **Connection URL** as the default value of `https://app.terraform.io`. + +![ServiceNow Service Graph Connector HTTP Connection configuration screen. A Terraform Enterprise URL may be provided in the Connection URL field, the saved by clicking the Update button](/img/docs/service-now-service-graph-tfconn.png) + +If you want to use a MID server, check **Use MID server** box, change **MID Selection** dropdown to "Specific MID sever" and select your previously configured and validated MID server. + +Click **Update** to save these settings. In the **Configure Terraform connection** section, click **Mark as Complete**. + +## Import Resources + +Refer to the documentation explaining the difference between the [two modes of import](/terraform/enterprise/integrations/service-now/service-graph#import-methods) offered by the Service Graph Connector for Terraform. Both options may be enabled, or you may choose to enable only the webhook or scheduled import. + +### Configure scheduled import + +In the **Set up scheduled import job** section of the setup form, proceed to **Configure the scheduled jobs** and click **Configure**. + +You can use the **Execute Now** option to run a single import job, which is useful for testing. The import set will be displayed in the table below the scheduled import form, after refreshing the page. Once the import is successfully triggered, click on the **Import Set** field of the record to view the logs associated with the import run, as well as its status. + +Activate the job by checking the **Activate** box. Set the **Repeat Interval** and click **Update**. Note that the import processing time depends of the number of organizations and workspaces in your HCP Terraform. Setting the import job to run frequently is not recommended for big environments. + +![ServiceNow Service Graph Connector scheduled import screen](/img/docs/service-now-service-graph-scheduled-import.png) + +You can also access the scheduler interface by searching for **Service Graph Connector for Terraform** in the top navigation menu and selecting **SG-Import Schedule**. + +### Configure Terraform Webhook + +In the top navigation, click on **All**, search for **Scheduled Imports**, and click on **Scheduled Imports**. + +Select the **SG-Terraform Scheduled Process State** record, then click **To edit the record click here**. + +Click the **Active** checkbox to enable it. Leave the default value for the **Repeat Interval** of 5 seconds. Click **Update**. + +![ServiceNow Service Graph Connector scheduled import screen showing the Active checkbox enabled](/img/docs/service-now-service-graph-webhook-schedule.png) + +Next, create the webhook in HCP Terraform. Select a workspace and click **Settings > Notifications**. Click **Create a Notification**. + +Keep the **Destination** as the default option of **Webhook**. Choose a descriptive name **Name**. + +Set the **Webhook URL** enter `https:///api/x_hashi_service_gr/sg_terraform_webhook` and replace `` with the hostname of your ServiceNow instance. + +In the **Token** field, enter the same string you provided in **Terraform Webhook token** section the of the Service Graph guided setup form. + +Under **Health Events** choose **No events**. + +Under **Run Events** choose **Only certain events** and enable notifications only on **Completed** runs. Click **Create Notification**. + +![HCP Terraform notification creation screen, showing a webhook pointing to ServiceNow which is only triggered on completed runs](/img/docs/service-now-service-graph-webhook-tfc.png) + +Trigger a run in your workspace. Once the run is successfully completed, a webhook notification request will be sent to your ServiceNow instance. + +### Monitor the import job + +By following these steps, you can track the status of import jobs in ServiceNow and verify the completion of the import process before accessing the imported resources in the CMDB. + +For scheduled imports, navigate back to the **SG-Import Schedule** interface. For webhook imports, go to the **SG-Terraform Scheduled Process State** interface. + +Under the form, you will find a table containing all registered import sets. Locate and select the relevant import set record. + +Click on the **Import Set** field to open it and view its details. The **Outbound Http Requests** tab lists all requests made by your ServiceNow instance to HCP Terraform in order to retrieve the latest Terraform state. + +Monitor the state of the import job. Wait for it to change to **Complete**, indicated by a green mark. +Once the import job is complete, you can access the imported resources in the CMDB. + +![ServiceNow Service Graph Connector: import set with successfully completed status](/img/docs/service-now-service-graph-import-set.png) + +You can also access all import sets, regardless of the import type, by navigating to **All** and selecting **Import Sets** under the **Advanced** category. + +### View resources in ServiceNow CMDB + +In the top navigation of ServiceNow, click on **All** and search for **CMDB Workspace**, and click on **CMDB Workspace**. + +Perform a search by entering a Configuration Item (CI) name in the **Search** field (for example, **Virtual Machine Instance**). CI names supported by the application are listed on the [resource mapping page](/terraform/enterprise/integrations/service-now/service-graph/resource-coverage). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/migrate/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/index.mdx new file mode 100644 index 0000000000..e7d1fdb635 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/index.mdx @@ -0,0 +1,95 @@ +--- +page_title: Migrate Terraform state to Terraform Enterprise or Terraform Enterprise +description: >- + Learn how to migrate existing Terraform state to Terraform Enterprise or + Terraform Enterprise so that you can manage existing infrastructure without + de-provisioning. +source: terraform-docs-common +--- + +# Migrate Terraform state to HCP Terraform or Terraform Enterprise + +This topic describes how to migrate existing Terraform state files to HCP Terraform or Terraform Enterprise without first de-provisioning them. Refer to [State](/terraform/language/state) in the Terraform configuration language reference for additional information about Terraform state. + +## Overview + +Perform the following actions to migrate existing resources to one or more workspaces in HCP Terraform or Terraform Enterprise: + +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. + +You have three options to migrate your state: + +1. Manually using the Terraform CLI +2. Automatically using `tf-migrate` +3. Manually using the HCP Terraform API + +## Requirements + +- Terraform v1.1 and later is required to configure the `cloud` block. For Terraform v1.0 and older, use the [`remote` backend](/terraform/language/settings/backends/remote) instead. +- Create an account on [HCP Terraform](https://app.terraform.io/) or on a [Terraform Enterprise instance](/terraform/enterprise/users-teams-organizations/users#creating-an-account). +- You must present a token linked to appropriate permissions to use the API. Refer to the following topics for additional information: + - [HCP Terraform API overview](/terraform/enterprise/api-docs) + - [Terraform Enterprise API overview](/terraform/enterprise/api-docs) + +## Stop Terraform operations + +Stop all Terraform operations associated with the state files. This may require locking or deleting CI jobs, restricting access to the state backend, and communicating with other teams. You should also only migrate state files into HCP Terraform or Terraform Enterprise workspaces that have never performed a run. + +## Migrate state using the CLI + +> **Hands-on:** Complete the [Migrate State to HCP Terraform](/terraform/tutorials/state/cloud-migrate) tutorial for additional guidance on how to migrate Terraform state using the CLI. + +1. Add the `cloud` block to your Terraform configuration and specify the following fields: + + 1. `hostname` field: Specify either `app.terraform.io` for HCP Terraform or the hostname of your Terraform Enterprise deployment. + 2. `organization` field: Specify your HCP Terraform or Terraform Enterprise organization. + 3. `workspaces` block: Add a `tags` or `name` field and specify one or more destination workspaces as a list of strings. + + Refer to [The `cloud` Block](/terraform/cli/cloud/settings#the-cloud-block) in the Terraform CLI documentation for additional information. The following example migrates the state associated with the configuration to the `networking` workspace on HCP Terraform: + + ```hcl + terraform { + cloud { + hostname = "app.terraform.io" + organization = "my-org" + workspaces { + tags = ["networking"] + } + } + } + ``` + +2. Run `terraform init`. Terraform creates any workspaces specified in the configuration if they do not already exist in the organization. + +## 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. + +## Migrate state using the API + +1. Encode your state files as a base64 string and generate an MD5 hash. The following example generates the string and hash file for a single `terraform.tfstate` file: + + ```shell-session + $ cat terraform.tfstate | base64 + dGVycmFmb3JtLnRmc3RhdGUK + $ md5sum terraform.tfstate + 690a3f8ae079c629494a52c68757d585 terraform.tfstate + ``` +2. If the workspace does not yet exist in your organization, send a `POST` request to the `/organizations/:organization_name/workspaces` endpoint to create it. Otherwise, proceed to the next step. Refer to the following topics for details: + - [Create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) in the HCP Terraform API reference documentation. + - [Create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) in the Terraform Enterprise API reference documentation. +3. Send a `POST` request to the `/workspaces/:workspace_id/actions/lock` endpoint to lock the workspace. Refer to the following topics for details: + - [Lock a workspace](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) in the HCP Terraform API reference documentation. + - [Lock a workspace](/terraform/enterprise/api-docs/workspaces#lock-a-workspace) in the Terraform Enterprise API reference documentation. +4. To upload your state files to the workspace, send a `POST` request to the `/workspaces/:workspace_id/state-versions` endpoint. Specify the MD5 string in the `data.attributes.md5` field and encoded state file in the `data.attributes.state` field of the request body. Refer to the following topics for details: + - [Create a state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version) in the HCP Terraform API reference documentation. + - [Create a state version](/terraform/enterprise/api-docs/state-versions#create-a-state-version) in the Terraform Enterprise API reference documentation. +5. Send a `POST` request to the `/workspaces/:workspace_id/actions/unlock` endpoint to unlock the workspace. + +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/v000011-1/docs/enterprise/migrate/tf-migrate/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/index.mdx new file mode 100644 index 0000000000..9712d3e465 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/index.mdx @@ -0,0 +1,132 @@ +--- +page_title: Terraform migrate overview +description: Learn how to install and configure the Terraform migrate tf-migrate CLI tool. +source: terraform-docs-common +--- + +# Terraform migrate + +The Terraform migrate `tf-migrate` CLI automatically migrates your Terraform Community Edition state and variables to HCP Terraform or Terraform Enterprise. It also updates your local configuration with the new state storage location and optionally creates a pull request to update your code repository. + +**Hands-on**: Complete the [Migrate to HCP Terraform in bulk](/terraform/tutorials/cloud/bulk-migrate-hcp) tutorial to get started with `tf-migrate`. + +## Overview + +Complete the following steps to install and configure `tf-migrate`: + +1. [Download and install `tf-migrate`](#install). +2. Configure `tf-migrate` to [authenticate](#connect-to-hcp-terraform-or-enterprise-terraform) to HCP Terraform or Terraform Enterprise. +3. Enable logging so that you can troubleshoot potential issues that may occur during the migration process. + +### GitHub and GitLab connection requirements + +The `tf-migrate` tool can optionally open a pull request to update your configuration in GitHub or GitLab. + +If your Terraform files are stored in GitHub, you must configure an API token that meets the following requirements: + +- The token must be a classic token. Refer to the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for additional information. +- The token must have the `repo` OAuth scope. + +If your Terraform files are stored in GitLab Cloud, you must configure an API token that meets the following requirements: + +- The token must be a personal access token. Refer to the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for additional information. +- The token must be have `read_repository` and `write_repository` scopes. + +## Install + + + + + +HashiCorp distributes `tf-migrate` as a binary package. To install `tf-migrate`, find the [appropriate binary](https://releases.hashicorp.com/tf-migrate/) for your operating system and download it as a zip archive. + +After you download `tf-migrate`, unzip the archive. + +Finally, make sure that the `tf-migrate` binary is available in a directory that is in your system's `PATH`. + +### Verify the installation + +Every build of `tf-migrate` includes a `SHA256SUMS` and a `SHA256SUMS.sig` file to validate your downloaded binary. Refer to the [verify HashiCorp binary downloads tutorial](https://developer.hashicorp.com/well-architected-framework/operational-excellence/verify-hashicorp-binary) for more information. + + + + + +[Homebrew](https://brew.sh/) is a free and open-source package management system for macOS. You can install the official [`tf-migrate`](https://github.com/hashicorp/homebrew-tap) formula from the terminal. + +First, install the HashiCorp tap, a repository of all our Homebrew packages. + + $ brew tap hashicorp/tap + +Now, install `tf-migrate` with the `hashicorp/tap/tf-migrate` formula. + + $ brew install hashicorp/tap/tf-migrate + + + + + +## Connect to HCP Terraform or Enterprise Terraform + +The `tf-migrate` tool uses your locally configured Terraform CLI API token. If you have not authenticated your local Terraform installation with HCP Terraform, use the `terraform login` command to create an authentication token. + + $ terraform login + + Terraform will request an API token for app.terraform.io using your browser. + + If login is successful, Terraform will store the token in plain text in + the following file for use by subsequent commands: + /Users/redacted/.terraform.d/credentials.tfrc.json + + Do you want to proceed? + Only 'yes' will be accepted to confirm. + + Enter a value: yes + +Terraform opens a browser to the HCP Terraform sign in screen, where you can then enter a token name in the web UI, or leave the default name. Click **Create API token** to generate the authentication token. + +HCP Terraform only displays your token once. Copy this token, then when the Terraform CLI prompts you, paste the user token exactly once into your terminal. Press **Enter** to complete the authentication process. + +`tf-migrate` can optionally create a pull request that updates the state storage location specified in your Terraform configuration. To do this, `tf-migrate` uses the GitHub or GitLab Cloud API, and requires an API token with permissions to modify your Git repository. + +To configure your API token, set the `TF_GIT_PAT_TOKEN` environment variable + + $ export TF_GIT_PAT_TOKEN= + +## Supported backends + +The `tf-migrate` tool supports migrating state from the following backends to HCP Terraform or Terraform Enterprise: + +- [local](/terraform/language/backend/local) +- [azurerm](/terraform/language/backend/azurerm) +- [consul](/terraform/language/backend/consul) +- [cos](/terraform/language/backend/cos) +- [gcs](/terraform/language/backend/gcs) +- [http](/terraform/language/backend/http) +- [Kubernetes](/terraform/language/backend/kubernetes) +- [oss](/terraform/language/backend/oss) +- [pg](/terraform/language/backend/pg) +- [s3](/terraform/language/backend/s3) + +`tf-migrate` does not support migrating state from an existing `cloud` integration or `remote` backend. + +## Enable logging + +You can enable detailed logging by setting the `TF_MIGRATE_ENABLE_LOG` environment variable to `true`. When you enable this setting, `tf-migrate` writes the logs to the following locations, depending on your operating system: + +| Platform | Location | +| --------------- | --------------------------------------------------------------- | +| macOS and Linux | `/Users//.tf-migrate/logs//.log` | +| Windows | `C:\Users\\.tf-migrate\logs\\.log` | + +You can set the `TF_MIGRATE_LOG_LEVEL` environment variable to one of the following values to change the verbosity of the logs in order of decreasing verbosity: + +- `TRACE` +- `DEBUG` +- `INFO` +- `WARN` +- `ERROR` + +## Additional configuration + +You can create an optional configuration file to modify the `tf-migrate` CLI behavior and specify the path to the configuration file when you run `tf-migrate prepare`. Any command-line flags you provide with these commands override the configuration file. Refer to the [configuration reference](/terraform/enterprise/migrate/tf-migrate/reference/configuration) for additional information. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/configuration.mdx new file mode 100644 index 0000000000..215f5b9a2b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/configuration.mdx @@ -0,0 +1,88 @@ +--- +page_title: Configuration file reference +description: >- + You can configure `tf-migrate` to control how it migrate your state to + Terraform Enterprise or Terraform Enterprise. +source: terraform-docs-common +--- + +# `tf-migrate` configuration file reference + +This topic describes the parameters for configuring the `tf-migrate` CLI. + +## Configuration model + +A `tf-migrate` configuration file supports the following parameters. + +- [`skip-dir`](#skip-dir): list of strings +- [`projects`](#projects): list of objects + - [`dir`](#projects-dir): string + - [`workspaces`](#projects-workspaces): list of objects + - [`name`](#projects-workspaces): string + - [`env-vars`](#projects-workspaces): + - [`terraform-vars`](#projects-workspaces): list of strings + +## Specification + +This section provides details about the fields you can configure in a `tf-migrate` configuration file. + +### `skip-dir` + +Specifies a list of paths to directories you want `tf-migrate` to skip. This parameter is identical to using the [`-skip-dir` command-line flag](/terraform/enterprise/migrate/tf-migrate/reference/prepare#available-options). By default, `tf-migrate` processes all child directories containing Terraform configuration files. + +- Data type: List of strings +- Default: None + +### `projects` + +Specifies a list of project configurations that align with local directories. The `tf-migrate` tool creates one project in HCP Terraform or Terraform Enterprise per configuration. In each project, `tf-migrate` creates one workspace per local workspace. + +- Data type: List of objects +- Default: None + +### `projects.dir` + +Specifies the relative or absolute path to the Terraform configuration to migrate. + +- Data type: String +- Default: None + +### `projects.workspaces` + +Specifies workspace configurations in the project. Terraform creates a workspace in HCP Terraform or Terraform Enterprise for each workspace configuration. The following table describes the attributes you can configure in each item in the list of workspaces: + +| Attribute | Description | Data type | Default | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------- | +| `name` | Specifies the name of the local workspace. | String | None | +| `env-vars` | Specifies a map of environment variables to set during the migration. Each key must start with `TF_VAR`. You must specify `env-vars`, `terraform-vars`, or both. | Object | None | +| `terraform-vars` | Specifies a list of Terraform variables files to use for configuring the workspace. Each file must end with either `.tfvars` or `tfvars.json`. You must specify `terraform-vars`, `env-vars`, or both. The path can be a relative or absolute path. | List of strings | None | + +- Data type: List of objects +- Default: None + +## Example configuration file + +In the following example, Terraform creates one project using data from the `example/project1` directory. The project has a workspace named `staging` and a workspace named `dev`: + +```hcl +skip-dir = ["example/skip/dir1", "example/skip/dir2"] + +projects = [ + { + dir = "example/project1" + workspaces = [ + { + name = "staging" + env-vars = { + "TF_VAR_region": "us-east-2" + } + terraform-vars = ["staging.tfvars"] + }, + { + name = "dev" + terraform-vars = ["dev.tfvars"] + } + ] + } +] +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/execute.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/execute.mdx new file mode 100644 index 0000000000..511175e82a --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/execute.mdx @@ -0,0 +1,65 @@ +--- +page_title: tf-migrate execute reference +description: >- + The `tf-migrate execute` command runs a prepared migration to migrate locally + existing state to Terraform Enterprise or Terraform Enterprise. +source: terraform-docs-common +--- + +# `tf-migrate execute` reference + +The `tf-migrate execute` command directs Terraform to run the `init`, `plan`, and `apply` commands on the configuration generated with the `tf-migrate prepare` command. + +## Usage + + $ tf-migrate execute + +## Description + +The `tf-migrate execute` command creates the project and workspace in HCP Terraform or Terraform Enterprise, migrates the existing state, and updates your configuration to replace the `backend` block with the `cloud` block. If you responded to the prompt in the prepare workflow to create a pull request, `tf-migrate` creates the pull request after it completes the migration. + +When Terraform migrate completes the migration, it displays the number of workspaces migrated, a link to each HCP Terraform workspace, and a link to the GitHub pull request if you configured it to create one. + +## Example + +The `tf-migrate execute` command automatically performs the migration and code updates. + + + + $ tf-migrate execute + ✓ Init command ran successfully + ✓ Plan command ran successfully and changes are detected + ✓ Apply command ran successfully + Apply complete! Resources: 7 added, 0 changed, 0 destroyed. + + + Migration Summary + ┌───────────────────────────────┬───────┐ + │ Metric │ Count │ + ├───────────────────────────────┼───────┤ + │ Number of Projects Migrated │ 2 │ + │ Number of Directories Skipped │ 0 │ + │ Number of New Workspaces │ 2 │ + │ Number of Variables Migrated │ 8 │ + └───────────────────────────────┴───────┘ + ┌───────────────────────────────────────────────────────────────────────────────────────────────────┐ + │ Workspace URLs │ + ├───────────────────────────────────────────────────────────────────────────────────────────────────┤ + │ https://app.terraform.io//workspaces/web_default │ + │ https://app.terraform.io//workspaces/api_default │ + └───────────────────────────────────────────────────────────────────────────────────────────────────┘ + ┌────────────────────────────────────────────────────────────────────────┐ + │ Pull Request Link │ + ├────────────────────────────────────────────────────────────────────────┤ + │ https://github.com//learn-terraform-migrate/pull/1 │ + └────────────────────────────────────────────────────────────────────────┘ + + + +## Available options + +You can include the following flags when you run the `tf-migrate execute` command: + +| Option | Description | Default | Required | +| ---------- | ------------------------------------------------------------------------------------------------------------------- | ------- | -------- | +| `-dry-run` | If set, Terraform migrate only shows the output from the `terraform plan` step, and does not perform the migration. | None | No | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/prepare.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/prepare.mdx new file mode 100644 index 0000000000..ae735703bf --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/migrate/tf-migrate/reference/prepare.mdx @@ -0,0 +1,104 @@ +--- +page_title: tf-migrate prepare reference +description: >- + The `tf-migrate prepare` command gathers information and creates a plan to + migrate your Terraform Community Edition state. +source: terraform-docs-common +--- + +# `tf-migrate prepare` reference + +The `tf-migrate prepare` command recursively scans the current directory for Terraform state files, then generates new Terraform configuration to migrate the state to HCP Terraform or Terraform Enterprise. + +## Usage + + $ tf-migrate prepare [options] + +## Description + +The `tf-migrate prepare` command prompts you for the following information: + +- The HCP Terraform or Terraform Enterprise organization to migrate your state to. +- If you would like to create a new branch named `hcp-migrate-` where `` is the name of the branch you currently have checked out. +- If you would like it to automatically create a pull request with the updated code change when the migration is complete. + +The `tf-migrate prepare` command generates a new Terraform configuration in the `_hcp-migrate-configs` directory to perform the migration. This configuration creates the following resources: + +- One workspace per state file. The `tf-migrate` tool names the workspace following the `-` pattern. The `tf-migrate` tool also creates workspace variables from the Terraform configuration's variables. +- One project to store all workspaces. The `tf-migrate` tool uses the directory path to the state file as the project name. For example, if your configuration is stored at `./frontend/networking/terraform.tfstate`, `tf-migrate` names the project "frontend_networking". Because of this, your directory path must be between 3-40 characters and only include letters, numbers, inner spaces, hyphens, and underscores. +- A new local git branch if you responded to the prompt to create a new branch with `yes`. +- A new pull request in the remote git repository if you responded to the prompt to create a pull request with `yes`. + +The `tf-migrate` CLI tool adds the generated configuration to the `.gitignore` file so that the configuration is not committed to source control. + +The `tf-migrate` tool creates the following structure in HCP Terraform or Terraform Enterprise depending on your local configuration: + +| Source | Result | +| :------------------------------------------------------------------------- | :----------------------------------------------------------- | +| Single configuration, single state | Single HCP workspace | +| Single configuration, multiple states for each Community Edition workspace | One HCP workspace per state | +| Multiple configurations, one state per configuration | One HCP workspace per configuration | +| Multiple configurations, multiple states per configuration | One HCP workspace per combination of configuration and state | + +## Example + +The `tf-migrate prepare` command generates the configuration to migrate this state to a single HCP Terraform workspace. + + + + $ tf-migrate prepare + ✓ Current working directory: /tmp/learn-terraform-migrate + ✓ Environment readiness checks completed + ✓ Found 3 HCP Terraform organizations + ┌────────────────────────────┐ + │ Available Orgs │ + ├────────────────────────────┤ + │ my-org-1 │ + │ my-org-2 │ + │ my-org-3 │ + └────────────────────────────┘ + Enter the name of the HCP Terraform organization to migrate to: my-org-1 + ✓ You have selected organization my-org-1 for migration + ✓ Found 2 directories with Terraform files + ┌────────────────────────────────┐ + │ Terraform File Directories │ + ├────────────────────────────────┤ + │ web │ + │ api │ + └────────────────────────────────┘ + Create a local branch named hcp-migrate-main from the current branch main: ... ? + + + Only 'yes or no' will be accepted as input. + Type 'yes' to approve the step + Type 'no' to to skip + + + Enter a value: yes + + ✓ Successfully created branch hcp-migrate-main + Do you want to open a pull request from hcp-migrate-main ... ? + + + Only 'yes or no' will be accepted as input. + Type 'yes' to approve the step + Type 'no' to to skip + + + Enter a value: yes + + ✓ Migration config generation completed + ✓ Successfully updated .gitignore + + + +## Available options + +You can include the following flags when you run the `tf-migrate prepare` command: + +| Option | Description | Default | Required | +| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- | +| `-config` | Specifies the path to an optional configuration file. Refer to [`tf-migrate` configuration file reference](/terraform/enterprise/migrate/tf-migrate/reference/configuration) for more information. | None | No | +| `-hostname` | The hostname of your Terraform Enterprise server. If you do not provide a hostname, `tf-migrate` defaults to HCP Terraform. | `app.terraform.io` | No | +| `-skip-dir` | Specifies a comma-separated list of relative paths to exclude from the migration. | None | No | +| `--parallelism` | Specifies the number of threads `tf-migrate` uses to scan the local directory and prepare the migration. Set this value to `1` to disable parallelism. | The number of logical CPUs in the system. | No | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/no-code-provisioning/module-design.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/no-code-provisioning/module-design.mdx new file mode 100644 index 0000000000..8b62ff5f99 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/no-code-provisioning/module-design.mdx @@ -0,0 +1,72 @@ +--- +page_title: Design no-code ready modules for Terraform Enterprise +description: >- + No-code ready modules let users deploy a module's resources without writing + configuration. Learn how to prepare modules for no-code provisioning. +source: terraform-docs-common +--- + +# Design no-code ready modules + +Terraform [modules](/terraform/language/modules) let you define standardized collections of infrastructure resources that downstream users can more easily deploy. No-code ready modules build on these advantages by letting users deploy a module's resources without writing any Terraform configuration. This practice is called no-code provisioning. + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +No-code provisioning enables a self-service workflow that lets users provision approved collections of resources without learning Terraform or infrastructure best practices. You can enable no-code provisioning for any public or private module in your [private registry](/terraform/enterprise/registry). Users can then [provision no-code infrastructure](/terraform/enterprise/no-code-provisioning/provisioning), set the module's input variables, and deploy its resources. + +> **Hands On:** Try the [Create and Use No-Code Ready Modules tutorial](/terraform/tutorials/cloud/no-code-provisioning). + +The same best practices apply to both standard and no-code ready module design. However, no-code modules have additional requirements and considerations. + +## Requirements + +A no-code ready module must meet the following requirements: + +- **Root Module Structure:** The module must follow [standard module structure](/terraform/language/modules/develop/structure) and define its resources in the root directory of the repository. This structure allows the public and private registries to generate documentation, track resource usage, and parse submodules and examples. +- **Provider Configuration:** A no-code ready module must declare the required provider(s) directly in the module. This configuration differs from the recommendations for [modules used in written configuration](/terraform/language/modules/develop/providers#legacy-shared-modules-with-provider-configurations). + +### Provider credentials + +Organization administrators must determine how no-code workspaces access credentials for provider authentication and design modules accordingly. + +When module consumers follow the no-code workflow, HCP Terraform automatically creates a new workspace for the resources and attempts to provision them. New workspaces must be able to access credentials for all providers defined within the module. + +You can grant new no-code workspace provider credentials using one of the following methods: + +- Recommended: Create a [project-scoped variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) that HCP Terraform applies to all existing and future workspaces within a project. This approach allows you to create specific teams for those less familiar with Terraform, then give those teams access to your no-code projects. +- Create a [global variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) that HCP Terraform applies to all existing and future workspaces in the organization. This action automatically grants newly-created workspaces access to the required provider credentials. +- Expose provider credentials as sensitive outputs in another workspace. You must add additional configuration to the module to access these values through [remote state data sources](/terraform/language/state/remote-state-data) and then reference them in provider configuration. This approach provides more control over access to these credentials than placing them in a global variable set. +- Elect to let the first run in new no-code workspaces fail and have module users add credentials directly to the workspace after creation. This approach provides the most control over access to provider credentials, but requires manual intervention. Module users must manually start a new run to provision infrastructure after they configure the credentials. + +## Module Design Recommendations + +Similarly to a [standard module](/terraform/language/modules/develop#when-to-write-a-module), a well-designed no-code ready module composes resources so that they are easy for others to deploy. However, no-code module users are less familiar with Terraform, so we recommend the following best practices for no-code module design. + +### Build For a Specific Use Case + +No-code ready module users are typically less familiar with Terraform and infrastructure management. Reduce the amount of technical decision-making required to deploy the module by scoping it to a single, specific use case. This approach lets users focus on business concerns instead of infrastructure concerns. + +For example, you could build modules that satisfy the following well-scoped use cases: + +- Deploying all resources needed for a three-tier web application +- Deploying a database with constraints on resource allocation and deployment region + +### Updating a Module's Version + +When you enable no-code provisioning for a module, HCP Terraform pins the **No-code Ready** designation to the specific module version of your choice. HCP Terraform deploys that selected module version whenever a user provisions a workspace using that module, ensuring that no-code users always provision the correct version. Pinning the **No-code Ready** designation to a specific module version lets you set variable input options, which are tied to that specific module version. + +By default, a module selects the latest version available. If you pinned a specific module version and a newer one becomes available, you can always update your module's version. + +### Provide Variable Defaults When Possible + +The no-code provisioning workflow prompts users to set values for the module version's input variables before creating the new workspace and deploying resources. We recommend setting reasonable defaults when possible to reduce the effort and expertise needed to deploy the module. Remember that the workspace can also access variable values set through global or project level variable sets in your organization. + +### Define Dropdown Options for Variables without Defaults + +If your module has variables without defaults, you can define options to limit the values a user can input when you enable a module for no-code provisioning. You can define input options using the HCP Terraform UI, the [No-Code Provisioning API](/terraform/enterprise/api-docs/no-code-provisioning), or the [TFE provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/no_code_module). We recommend using the TFE provider if you want to track variable input options through a code approval process, therefore keeping your configuration as code. + +HCP Terraform surfaces any subsequent changes to a variable’s input options when no-code users provision a new module version. If you update the selected module version enabled for no-code provisioning, consider revisiting the variables and adjusting the defined input values accordingly. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/no-code-provisioning/provisioning.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/no-code-provisioning/provisioning.mdx new file mode 100644 index 0000000000..46c36667f2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/no-code-provisioning/provisioning.mdx @@ -0,0 +1,89 @@ +--- +page_title: Provision no-code infrastructure in Terraform Enterprise +description: >- + No-code ready modules let users deploy a module's resources without writing + configuration. Learn how to provision infrastructure from a no-code ready + module. +source: terraform-docs-common +--- + +# Provision no-code infrastructure + +No-code provisioning lets you deploy infrastructure resources in a new HCP Terraform workspace without writing any Terraform configuration. You can create a no-code workspace from any module version labeled **No-code Ready** in your organization's [private registry](/terraform/enterprise/registry). + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +> **Hands On:** Try the [Create and Use No-Code Ready Modules tutorial](/terraform/tutorials/cloud/no-code-provisioning). + +## Permissions + +To use no-code provisioning, you must be a member of a team with [manage all projects permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects), [manage all workspaces permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces), or [admin permissions for a project](/terraform/enterprise/users-teams-organizations/permissions#project-admins). When using [custom project permissions](/terraform/enterprise/users-teams-organizations/permissions#custom-project-permissions), your team must be able to create workspaces, write variables, and apply runs in a project. + +## Provider Credentials + +Terraform automatically starts a new run to provision no-code infrastructure upon workspace creation. No-code modules contain provider blocks in their configuration, but still require provider credentials for successful deployment. Organization administrators determine how new workspaces should [access provider credentials](/terraform/enterprise/no-code-provisioning/module-design#provider-credentials), which may require specific module design. + +## Creating a Workspace and Deploying Resources + +The no-code provisioning workflow creates a new HCP Terraform workspace to deploy and manage the no-code ready module's resources. HCP Terraform automatically starts a run to provision the module's resources in the new workspace. Depending on the workspace's settings, Terraform either automatically applies the plan or prompts you for approval to provision the infrastructure. + +To launch the no-code workflow: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization with the module you want to provision. + +2. Click **Registry** in the main HCP Terraform navigation to access your organization's private registry. + +3. Click **Modules** to view the list of available modules in the private registry. You can filter for no-code ready modules in your registry. No-code enabled modules have a **No-code Ready** badge next to their names. + +4. Select the no-code ready module to view its details, then click **Provision workspace**. The **Configure module inputs** page appears. + + HCP Terraform scans the module configuration for input variables and prompts for values for any variables without defaults or undefined in an existing global variable set. Terraform requires values for these variables to successfully complete runs in the workspace. HCP Terraform performs type validation for the variable values if the module configuration specifies a type. + +5. (Optional) Set values for the input variables. If your organization has defined options for a variable's values, these options appear in a dropdown menu. You can skip this step and configure the variables later in your workspace. However, HCP Terraform does not prompt you for these values again, and your Terraform runs may fail. + +6. Click **Next: Workspace settings**. + +7. Enter a **Workspace Name**. The name must be unique within the organization and can include letters, numbers, dashes (-), and underscores (\_). Refer to the [workspace naming recommendations](/terraform/enterprise/workspaces/create#workspace-naming) for more guidance. + +8. Choose a **Project** for the workspace. Teams with access to the specified project can view the workspace automatically. Refer to [Organizing Workspaces with Projects](/terraform/enterprise/projects/manage) for more details. If the specified project contains any project-scoped variable sets, HCP Terraform automatically applies those sets to the workspace. + +9. Add an optional **Description** for the workspace. + +10. Select an apply method for the workspace. **Auto apply** automatically applies any successful runs in the workspace, including the initial run on workspace creation. **Manual apply** prompts operators to review and confirm the changes in a run. **Auto apply** is the default option for a no-code workspace. + +11. Click **Create workspace**. HCP Terraform creates a new workspace and starts a run. Depending on the apply method, it automatically applies your infrastructure or prompts you for approval to create the no-code module's resources. + +## Operations in No-Code Workspaces + +No-code workspaces have a limited feature set because you cannot access the resource configuration. However, you can edit workspace variables and settings, including notifications, permissions, and run triggers. You can use run triggers to connect the workspace to one or more source workspaces, start new runs when you change workspace variables, or queue destroy runs. + +### Updating Variables + +To change a variable's options after provisioning, go to the **Variables** section in your workspace to see your workspace's variables listed. To edit a variable: + +1. Click the ellipses next to the variable you want to edit and select **Edit**. +2. Enter your desired value and click **Save variable**. + +Start a new run in your workspace to update your existing infrastructure with your new variable value. + +### Module Version Updates + +When you [update the module version](/terraform/enterprise/no-code-provisioning/module-design#updating-a-module-s-version) designated for no-code provisioning, every workspace provisioned from the module is notified that an updated version is available on the workspace overview page. HCP Terraform does not automatically update workspaces. A workspace admin must respond to the update notification to upgrade the workspace, and HCP Terraform prompts for values for any new input variables. + +To change the version of the module that users can deploy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. + +2. Choose **Registry** from the sidebar and navigate to the module in your organization's registry. + +3. Click **Configure Settings**. + +4. Click **Edit version and variable options**. + +5. Choose the desired module version from the **Module version** dropdown. + +6. Click **Save**. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/custom-sentinel.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/custom-sentinel.mdx new file mode 100644 index 0000000000..16334c8807 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/custom-sentinel.mdx @@ -0,0 +1,260 @@ +--- +page_title: Define Sentinel policies in Terraform Enterprise +description: >- + Learn how to use the Sentinel policy language to create policies in Terraform + Enterprise. +source: terraform-docs-common +--- + +# Define Sentinel policies in HCP Terraform + +This topic describes how to create and manage custom policies using Sentinel policy language. For instructions about how to use pre-written Sentinel policies from the registry, refer to [Run pre-written Sentinel policies](/terraform/enterprise/policy-enforcement/prewritten-sentinel). + +## Overview + +To define a policy, create a file and declare an `import` function to include reusable libraries, external data, and other functions. Sentinel policy language includes several types of elements you can import using the `import` function. + +Declare and configure additional Sentinel policy language elements. The details depend on which elements you want to use in your policy. Refer to the [Sentinel documentation](/sentinel/docs) for additional information. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Declare an `import` function + +A policy can include imports that enable a policy to access reusable libraries, external data, and functions. Refer to [imports](/sentinel/docs/concepts/imports) in the Sentinel documentation for more details. + +HCP Terraform provides four imports to define policy rules for the plan, configuration, state, and run associated with a policy check. + +- [tfplan](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) - Access a Terraform plan, which is the file created as a result of the [`terraform plan` command](/terraform/cli/commands/plan). The plan represents the changes that Terraform must make to reach the desired infrastructure state described in the configuration. +- [tfconfig](/terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2) - Access a Terraform configuration. The configuration is the set of `.tf` files that describe the desired infrastructure state. +- [tfstate](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) - Access the Terraform [state](/terraform/language/state). Terraform uses state to map real-world resources to your configuration. +- [tfrun](/terraform/enterprise/policy-enforcement/import-reference/tfrun) - Access data associated with a [run in HCP Terraform](/terraform/enterprise/run/remote-operations). For example, you could retrieve the run's workspace. + +You can create mocks of these imports to use with the the [Sentinel +CLI](/sentinel/docs/commands) mocking and testing features. Refer to [Mocking Terraform Sentinel Data](/terraform/enterprise/policy-enforcement/test-sentinel) for more details. + + + +HCP Terraform does not support custom imports. + + + +## Declare additional elements + +The following functions and idioms will be useful as you start writing Sentinel +policies for Terraform. + +### Iterate over modules and find resources + +The most basic Sentinel task for Terraform is to enforce a rule on all resources +of a given type. Before you can do that, you need to get a collection of all the +relevant resources from all modules. The easiest way to do that is to copy and +use a function like the following into your policies. + +The following example uses the `tfplan` import. Refer to our [guides for other examples](https://github.com/hashicorp/terraform-guides/tree/master/governance/second-generation/common-functions) of +functions that iterate over the `tfconfig` and `tfstate` imports. + +```python +import "tfplan" +import "strings" + +# Find all resources of specific type from all modules using the tfplan import +find_resources_from_plan = func(type) { + resources = {} + for tfplan.module_paths as path { + for tfplan.module(path).resources[type] else {} as name, instances { + for instances as index, r { + # Get the address of the resource instance + if length(path) == 0 { + # root module + address = type + "." + name + "[" + string(index) + "]" + } else { + # non-root module + address = "module." + strings.join(path, ".module.") + "." + + type + "." + name + "[" + string(index) + "]" + } + # Add the instance to resources, setting the key to the address + resources[address] = r + } + } + } + return resources +} +``` + +Call the function to get all resources of a desired type by passing the +type as a string in quotation marks: + +```python +aws_instances = find_resources_from_plan("aws_instance") +``` + +This example function does several useful things while finding resources: + +- It checks every module (including the root module) for resources of the + specified type by iterating over the `module_paths` namespace. The top-level + `resources` namespace is more convenient, but it only reveals resources from + the root module. +- It iterates over the named resources and [resource + instances](/terraform/language/expressions/references#resources) + found in each module, starting with `tfplan.module(path).resources[type]` + which is a series of nested maps keyed by resource names and instance counts. +- It uses the Sentinel [`else` + operator](/sentinel/docs/language/spec#else-operator) to + recover from `undefined` values which would occur for modules that don't have + any resources of the specified type. +- It builds a flat `resources` map of all resource instances of the specified + type. Using a flat map simplifies the code used by Sentinel policies to + evaluate rules. +- It computes an `address` variable for each resource instance and uses this as + the key in the `resources` map. This allows writers of Sentinel policies to + print the full [address](/terraform/cli/state/resource-addressing) of each + resource instance that violate a policy, using the same address format used in + plan and apply logs. Doing this tells users who see violation messages exactly + which resources they need to modify in their Terraform code to comply with the + Sentinel policies. +- It sets the value of the `resources` map to the data associated with the + resource instance (`r`). This is the data that Sentinel policies apply rules + against. + +### Validate resource attributes + +Once you have a collection of resources instances of a desired type indexed by +their addresses, you usually want to validate that one or more resource +attributes meets some conditions by iterating over the resource instances. + +While you could use Sentinel's [`all` and `any` +expressions](/sentinel/docs/language/boolexpr#any-all-expressions) +directly inside Sentinel rules, your rules would only report the first violation +because Sentinel uses short-circuit logic. It is therefore usually preferred to +use a [`for` loop](/sentinel/docs/language/loops) outside +of your rules so that you can report all violations that occur. You can do this +inside functions or directly in the policy itself. + +Here is a function that calls the `find_resources_from_plan` function and +validates that the instance types of all EC2 instances being provisioned are in +a given list: + +```python +# Validate that all EC2 instances have instance_type in the allowed_types list +validate_ec2_instance_types = func(allowed_types) { + validated = true + aws_instances = find_resources_from_plan("aws_instance") + for aws_instances as address, r { + # Determine if the attribute is computed + if r.diff["instance_type"].computed else false is true { + print("EC2 instance", address, + "has attribute, instance_type, that is computed.") + } else { + # Validate that each instance has allowed value + if (r.applied.instance_type else "") not in allowed_types { + print("EC2 instance", address, "has instance_type", + r.applied.instance_type, "that is not in the allowed list:", + allowed_types) + validated = false + } + } + } + return validated +} +``` + +The boolean variable `validated` is initially set to `true`, but it is set to +`false` if any resource instance violates the condition requiring that the +`instance_type` attribute be in the `allowed_types` list. Since the function +returns `true` or `false`, it can be called inside Sentinel rules. + +Note that this function prints a warning message for **every** resource instance +that violates the condition. This allows writers of Terraform code to fix all +violations after just one policy check. It also prints warnings when the +attribute being evaluated is +[computed](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#value-computed) and does +not evaluate the condition in this case since the applied value will not be +known. + +While this function allows a rule to validate an attribute against a list, some +rules will only need to validate an attribute against a single value; in those +cases, you could either use a list with a single value or embed that value +inside the function itself, drop the `allowed_types` parameter from the function +definition, and use the `is` operator instead of the `in` operator to compare +the resource attribute against the embedded value. + +### Write Rules + +Having used the standardized `find_resources_from_plan` function and having +written your own function to validate that resources instances of a specific +type satisfy some condition, you can define a list with allowed values and write +a rule that evaluates the value returned by your validation function. + +```python +# Allowed Types +allowed_types = [ + "t2.small", + "t2.medium", + "t2.large", +] + +# Main rule +main = rule { + validate_ec2_instance_types(allowed_types) +} + +``` + +### Validate multiple conditions in a single policy + +If you want a policy to validate multiple conditions against resources of a +specific type, you could define a separate validation function for each +condition or use a single function to evaluate all the conditions. In the latter +case, you would make this function return a list of boolean values, using one +for each condition. You can then use multiple Sentinel rules that evaluate +those boolean values or evaluate all of them in your `main` rule. Here is a +partial example: + +```python +# Function to validate that S3 buckets have private ACL and use KMS encryption +validate_private_acl_and_kms_encryption = func() { + result = { + "private": true, + "encrypted_by_kms": true, + } + s3_buckets = find_resources_from_plan("aws_s3_bucket") + # Iterate over resource instances and check that S3 buckets + # have private ACL and are encrypted by a KMS key + # If an S3 bucket is not private, set result["private"] to false + # If an S3 bucket is not encrypted, set result["encrypted_by_kms"] to false + for s3_buckets as joined_path, resource_map { + #... + } + return result +} + +# Call the validation function +validations = validate_private_acl_and_kms_encryption() + +# ACL rule +is_private = rule { + validations["private"] +} + +# KMS Encryption Rule +is_encrypted_by_kms = rule { + validations["encrypted_by_kms"] +} + +# Main rule +main = rule { + is_private and is_encrypted_by_kms +} +``` + +You can write similar functions and policies to restrict Terraform configurations using the `tfconfig` import and to restrict Terraform state using the `tfstate` import. + +## Next steps + +1. Group your policies into sets and apply them to your workspaces. Refer to [Create policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets#create-policy-sets) for additional information. +2. View results and address Terraform runs that do not comply with your policies. Refer to [View results](/terraform/enterprise/policy-enforcement/view-results) for additional information. +3. You can also view Sentinel policy results in JSON format. Refer to [View Sentinel JSON results](/terraform/enterprise/policy-enforcement/view-results/json) for additional information. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/index.mdx new file mode 100644 index 0000000000..bc5881f611 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/index.mdx @@ -0,0 +1,19 @@ +--- +page_title: Define policies overview +description: >- + You can define policies using HashiCorp Sentinel or Open Policy Agent (OPA). + Learn how to define policies for governing how Terraform provisions + infrastructure. +source: terraform-docs-common +--- + +# Define policies overview + +This topic provides overview information about how to define policies as code. Policies are rules for enforcing how Terraform provisions infrastructure as code for your workspaces and projects. + +## Workflows + +You can use two policy-as-code frameworks to define fine-grained, logic-based policies: Sentinel and Open Policy Agent (OPA). Depending on the settings, policies can act as advisory warnings or firm requirements that prevent Terraform from provisioning infrastructure. + +- **Sentinel:** You define policies with the [Sentinel policy language](/sentinel/docs/concepts/language) and use imports to parse the Terraform plan, state, and configuration. Refer to [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel) for details. +- **OPA:** You define policies with the [Rego policy language](https://www.openpolicyagent.org/docs/latest/policy-language/). Refer to [Defining OPA Policies](/terraform/enterprise/policy-enforcement/define-policies/opa) for details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/opa.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/opa.mdx new file mode 100644 index 0000000000..92305f8e9f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/define-policies/opa.mdx @@ -0,0 +1,259 @@ +--- +page_title: Define Open Policy Agent policies for Terraform Enterprise +description: >- + Use the Rego policy language to define Open Policy Agent (OPA) policies for + Terraform Enterprise. +source: terraform-docs-common +--- + +# Define Open Policy Agent policies for HCP Terraform + +This topic describes how to create and manage custom policies using the open policy agent (OPA) framework. Refer to the following topics for instructions on using HashiCorp Sentinel policies: + +- [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel) +- [Copy pre-written Sentinel policies](/terraform/enterprise/define-policies/prewritten-sentinel) + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Overview + +> **Hands-on:** Try the [Detect Infrastructure Drift and Enforce OPA Policies](/terraform/tutorials/cloud/drift-and-opa) tutorial. + +You can write OPA policies using the Rego policy language, which is the native query language for the OPA framework. Refer to the following topics in the [OPA documentation](https://www.openpolicyagent.org/docs/latest/policy-language/) for additional information: + +- [How Do I Write Rego Policies?](https://www.openpolicyagent.org/docs/v0.13.5/how-do-i-write-policies/) +- [Rego Policy Playground](https://play.openpolicyagent.org/) + +## OPA query + +You must write a query to identify a specific policy rule within your Rego code. The query may evaluate code from multiple Rego files. + +The result of each query must return an array, which HCP Terraform uses to determine whether the policy has passed or failed. If the array is empty, HCP Terraform reports that the policy has passed. + +The query is typically a combination of the policy package name and rule name, such as `data.terraform.deny`. + +## OPA input + +HCP Terraform combines the output from the Terraform run and plan into a single JSON file and passes that file to OPA as input. Refer to the [OPA Overview documentation](https://www.openpolicyagent.org/docs/latest/#the-input-document) for more details about how OPA uses JSON input data. + +The run data contains information like workspace details and the organization name. To access the properties from the Terraform plan data in your policies, use `input.plan`. To access properties from the Terraform run, use `input.run`. + +The following example shows sample OPA input data. + +```json +{ +"plan": { + "format_version": "1.1", + "output_changes": { + }, + "planned_values": { + }, + "resource_changes": [ + ], + "terraform_version": "1.2.7" +}, + +"run": { + "organization": { + "name": "hashicorp" + }, + "workspace": { + } +} +} +``` + +Use the [Retrieve JSON Execution Plan endpoint](/terraform/enterprise/api-docs/plans#retrieve-the-json-execution-plan) to retrieve Terraform plan output data for testing. Refer to [Terraform Run Data](#terraform-run-data) for the properties included in Terraform run output data. + +## Example Policies + +The following example policy parses a Terraform plan and checks whether it includes security group updates that allow ingress traffic from all CIDRs (`0.0.0.0/0`). + +The OPA query for this example policy is `data.terraform.policies.public_ingress.deny`. + +```rego +package terraform.policies.public_ingress + +import input.plan as plan + +deny[msg] { + r := plan.resource_changes[_] + r.type == "aws_security_group" + r.change.after.ingress[_].cidr_blocks[_] == "0.0.0.0/0" + msg := sprintf("%v has 0.0.0.0/0 as allowed ingress", [r.address]) +} +``` + +The following example policy ensures that databases are no larger than 128 GB. + +The OPA query for this policy is `data.terraform.policies.fws.database.fws_db_001.rule`. + +```rego +package terraform.policies.fws.database.fws_db_001 + +import future.keywords.in +import input.plan as tfplan + +actions := [ + ["no-op"], + ["create"], + ["update"], +] + +db_size := 128 + +resources := [resource_changes | + resource_changes := tfplan.resource_changes[_] + resource_changes.type == "fakewebservices_database" + resource_changes.mode == "managed" + resource_changes.change.actions in actions +] + +violations := [resource | + resource := resources[_] + not resource.change.after.size == db_size +] + +violators[address] { + address := violations[_].address +} + +rule[msg] { + count(violations) != 0 + msg := sprintf( + "%d %q severity resource violation(s) have been detected.", + [count(violations), rego.metadata.rule().custom.severity] + ) +} +``` + +## Test policies + +You can write tests for your policies by [mocking](https://www.openpolicyagent.org/docs/latest/policy-testing/#data-and-function-mocking) the input data the policies use during Terraform runs. + +The following example policy called `block_auto_apply_runs` checks whether or not an HCP Terraform workspace has been configured to automatically apply a successful Terraform plan. + +```rego +package terraform.tfc.block_auto_apply_runs + +import input.run as run + +deny[msg] { + run.workspace.auto_apply != false + msg := sprintf( + "HCP Terraform workspace %s has been configured to automatically provision Terraform infrastructure. Change the workspace Apply Method settings to 'Manual Apply'", + [run.workspace.name], + ) +} +``` + +The following test validates `block_auto_apply_runs`. The test is written in rego and uses the OPA [test format](https://www.openpolicyagent.org/docs/latest/policy-testing/#test-format) to check that the workspace [apply method](/terraform/enterprise/workspaces/settings#apply-method) is not configured to auto apply. You can run this test with the `opa test` CLI command. Refer to [Policy Testing](https://www.openpolicyagent.org/docs/latest/policy-testing/) in the OPA documentation for more details. + +```rego +package terraform.tfc.block_auto_apply_runs + +import future.keywords + +test_run_workspace_auto_apply if { + deny with input as {"run": {"workspace": {"auto_apply": true}}} +} +``` + +## Terraform run data + +Each [Terraform run](/terraform/docs/glossary#run) outputs data describing the run settings and the associated workspace. + +### Schema + +The following code shows the schema for Terraform run data. + + run + ├── id (string) + ├── created_at (string) + ├── created_by (string) + ├── message (string) + ├── commit_sha (string) + ├── is_destroy (boolean) + ├── refresh (boolean) + ├── refresh_only (boolean) + ├── replace_addrs (array of strings) + ├── speculative (boolean) + ├── target_addrs (array of strings) + └── project + │ ├── id (string) + │ └── name (string) + ├── variables (map of keys) + ├── organization + │ └── name (string) + └── workspace + ├── id (string) + ├── name (string) + ├── created_at (string) + ├── description (string) + ├── execution_mode (string) + ├── auto_apply (bool) + ├── tags (array of strings) + ├── working_directory (string) + └── vcs_repo (map of keys) + +### Properties + +The following sections contain details about each property in Terraform run data. + +#### Run namespace + +The following table contains the attributes for the `run` namespace. + +| Properties Name | Type | Description | +| --------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | String | The ID associated with the current Terraform run | +| `created_at` | String | The time Terraform created the run. The timestamp follows the [standard timestamp format in RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). | +| `created_by` | String | A string that specifies the user name of the HCP Terraform user for the specific run. | +| `message` | String | The message associated with the Terraform run. The default value is "Queued manually via the Terraform Enterprise API". | +| `commit_sha` | String | The checksum hash (SHA) that identifies the commit | +| `is_destroy` | Boolean | Whether the plan is a destroy plan that destroys all provisioned resources | +| `refresh` | Boolean | Whether the state refreshed prior to the plan | +| `refresh_only` | Boolean | Whether the plan is in refresh-only mode. In refresh-only mode, Terraform ignores configuration changes and updates state with any changes made outside of Terraform. | +| `replace_addrs` | An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing) | The targets specified using the [`-replace`](/terraform/cli/commands/plan#replace-address) flag in the CLI or the `replace-addrs` property in the API. Undefined if there are no specified resource targets. | +| `speculative` | Boolean | Whether the plan associated with the run is a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) only | +| `target_addrs` | An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing). | The targets specified using the [`-target`](/terraform/cli/commands/plan#resource-targeting) flag in the CLI or the `target-addrs` property in the API. Undefined if there are no specified resource targets. | +| `variables` | A string-keyed map of values. | Provides the variables configured within the run. Each variable `name` maps to two properties: `category` and `sensitive`. The `category` property is a string indicating the variable type, either "input" or "environment". The `sensitive` property is a boolean, indicating whether the variable is a [sensitive value](/terraform/enterprise/workspaces/variables/managing-variables#sensitive-values). | + +#### Project Namespace + +The following table contains the properties for the `project` namespace. + +| Property Name | Type | Description | +| ------------- | ------ | --------------------------------------------------------------------------------------- | +| `id` | String | The ID associated with the Terraform project | +| `name` | String | The name of the project, which can only include letters, numbers, spaces, `-`, and `_`. | + +#### Organization namespace + +The `organization` namespace has one property called `name`. The `name` property is a string that specifies the name of the HCP Terraform organization for the run. + +#### Workspace namespace + +The following table contains the properties for the `workspace` namespace. + +| Property Name | Type | Description | +| ------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | String | The ID associated with the Terraform workspace | +| `name` | String | The name of the workspace, which can only include letters, numbers, `-`, and `_` | +| `created_at` | String | The time of the workspace's creation. The timestamp follows the [standard timestamp format in RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). | +| `description` | String | The description for the workspace. This value can be `null`. | +| `auto_apply` | Boolean | The workspace's [auto-apply](/terraform/enterprise/workspaces/settings#apply-method) setting | +| `tags` | Array of strings | The list of tag names for the workspace | +| `working_directory` | String | The configured [Terraform working directory](/terraform/enterprise/workspaces/settings#terraform-working-directory) of the workspace. This value can be `null`. | +| `execution_mode` | String | The configured Terraform execution mode of the workspace. The default value is `remote`. | +| `vcs_repo` | A string-keyed map to objects | Data associated with a VCS repository connected to the workspace. The map contains `identifier` (string), ` display_identifier` (string), `branch` (string), and `ingress_submodules` (boolean). Refer to the HCP Terraform [Workspaces API documentation](/terraform/enterprise/api-docs/workspaces) for details about each property. This value can be `null`. | + +## Next steps + +- Group your policies into sets and apply them to your workspaces. Refer to [Create policy sets](/policy-enforcement/manage-policy-sets#create-policy-sets) for additional information. +- View results and address Terraform runs that do not comply with your policies. Refer to [View results](/terraform/enterprise/policy-enforcement/view-results) for additional information. +- You can also view Sentinel policy results in JSON format. Refer to [View Sentinel JSON results](/terraform/enterprise/policy-enforcement/view-results/json) for additional information. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/index.mdx new file mode 100644 index 0000000000..eebf3b47f7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/index.mdx @@ -0,0 +1,32 @@ +--- +page_title: Sentinel import function reference +description: >- + Use the Sentinel import function to configure policy behaviors in custom + Sentinel policies. +source: terraform-docs-common +--- + +# `import` function reference overview + +This topic provides an overview of the Sentinel `import` function, which you can use to import Sentinel libraries into your custom Sentinel policies. Refer to [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel) for additional information about how to use the `import` function. + +## Functions for Terraform + +You can add Sentinel the `import` function, which enables a policy to access reusable libraries, external data, and other functions. Refer to the [Sentinel imports documentation](/sentinel/docs/language/imports) for more details. + +HCP Terraform provides the following importable libraries to define policy rules for the plan, configuration, state, and run associated with a policy check. + +- [`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan) : Provides access to a Terraform plan, which is the file created when you run the `terraform plan` command. This library is deprecated. Use `tfplanv/2` instead. +- [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2): Provides access to a Terraform plan, which is the file created when you run the `terraform plan` command. +- [`tfconfig`](/terraform/enterprise/policy-enforcement/import-reference/tfconfig): Provides access to a Terraform configuration. The configuration is the set of `.tf` files that describe the desired infrastructure state. This library is deprecated. Use `tfconfig/v2` instead. +- [`tfconfig/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2): Provides access to a Terraform configuration. The configuration is the set of `.tf` files that describe the desired infrastructure state. +- [`tfstate`](/terraform/enterprise/policy-enforcement/import-reference/tfstate): Provides access to the Terraform state. Terraform uses state to map real-world resources to your configuration. This library is deprecated. Use `tfstate/v2` instead. +- [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2): Provides access to the Terraform state. Terraform uses state to map real-world resources to your configuration. +- [`tfrun`](/terraform/enterprise/policy-enforcement/import-reference/tfrun): Provides access to data associated with a run in HCP Terraform. For example, you could retrieve the run's workspace. + +## Test `import` functions + +You can create mocks of these functions and test them using the Sentinel CLI. Refer to the following topics for additional information: + +- [Test Sentinel policies](/terraform/enterprise/policy-enforcement/test-sentinel) +- [Sentinel CLI documentation](/sentinel/docs/commands) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfconfig-v2.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfconfig-v2.mdx new file mode 100644 index 0000000000..637d596f01 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfconfig-v2.mdx @@ -0,0 +1,422 @@ +--- +page_title: tfconfig/v2 Sentinel import +description: >- + Use the tfconfig/v2 import to give Sentinel access to a Terraform + configuration. +source: terraform-docs-common +--- + +-> **Note:** This is documentation for the next version of the `tfconfig` +Sentinel import, designed specifically for Terraform 0.12. This import requires +Terraform 0.12 or higher, and must currently be loaded by path, using an alias, +example: `import "tfconfig/v2" as tfconfig`. + +# tfconfig/v2 Sentinel import + +The `tfconfig/v2` import provides access to a Terraform configuration. + +The Terraform configuration is the set of `*.tf` files that are used to +describe the desired infrastructure state. Policies using the `tfconfig` +import can access all aspects of the configuration: providers, resources, +data sources, modules, and variables. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Some use cases for `tfconfig` include: + +- **Organizational naming conventions**: requiring that configuration elements + are named in a way that conforms to some organization-wide standard. +- **Required inputs and outputs**: organizations may require a particular set + of input variable names across all workspaces or may require a particular + set of outputs for asset management purposes. +- **Enforcing particular modules**: organizations may provide a number of + "building block" modules and require that each workspace be built only from + combinations of these modules. +- **Enforcing particular providers or resources**: an organization may wish to + require or prevent the use of providers and/or resources so that configuration + authors cannot use alternative approaches to work around policy + restrictions. + +The data in the `tfconfig/v2` import is sourced from the JSON configuration file +that is generated by the [`terraform show -json`](/terraform/cli/commands/show#json-output) command. For more information on +the file format, see the [JSON Output Format](/terraform/internals/json-format) +page. + +## Import Overview + +The `tfconfig/v2` import is structured as a series of _collections_, keyed as a +specific format, such as resource address, module address, or a +specifically-formatted provider key. + + tfconfig/v2 + ├── strip_index() (function) + ├── providers + │ └── (indexed by [module_address:]provider[.alias]) + │ ├── provider_config_key (string) + │ ├── name (string) + │ ├── full_name (string) + │ ├── alias (string) + │ ├── module_address (string) + │ ├── config (block expression representation) + │ └── version_constraint (string) + ├── resources + │ └── (indexed by address) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── provider_config_key (string) + │ ├── provisioners (list) + │ │ └── (ordered provisioners for this resource only) + │ ├── config (block expression representation) + │ ├── count (expression representation) + │ ├── for_each (expression representation) + │ └── depends_on (list of strings) + ├── provisioners + │ └── (indexed by resource_address:index) + │ ├── resource_address (string) + │ ├── type (string) + │ ├── index (string) + │ └── config (block expression representation) + ├── variables + │ └── (indexed by module_address:name) + │ ├── module_address (string) + │ ├── name (string) + │ ├── default (value) + │ └── description (string) + ├── outputs + │ └── (indexed by module_address:name) + │ ├── module_address (string) + │ ├── name (string) + │ ├── sensitive (boolean) + │ ├── value (expression representation) + │ ├── description (string) + │ └── depends_on (list of strings) + └── module_calls + └── (indexed by module_address:name) + ├── module_address (string) + ├── name (string) + ├── source (string) + ├── config (block expression representation) + ├── count (expression representation) + ├── depends_on (expression representation) + ├── for_each (expression representation) + └── version_constraint (string) + +The collections are: + +- [`providers`](#the-providers-collection) - The configuration for all provider + instances across all modules in the configuration. +- [`resources`](#the-resources-collection) - The configuration of all resources + across all modules in the configuration. +- [`variables`](#the-variables-collection) - The configuration of all variable + definitions across all modules in the configuration. +- [`outputs`](#the-outputs-collection) - The configuration of all output + definitions across all modules in the configuration. +- [`module_calls`](#the-module_calls-collection) - The configuration of all module + calls (individual [`module`](/terraform/language/modules) blocks) across + all modules in the configuration. + +These collections are specifically designed to be used with the +[`filter`](/sentinel/docs/language/collection-operations#filter-expression) +quantifier expression in Sentinel, so that one can collect a list of resources +to perform policy checks on without having to write complex module or +configuration traversal. As an example, the following code will return all +`aws_instance` resource types within the configuration, regardless of what +module they are in: + + all_aws_instances = filter tfconfig.resources as _, r { + r.mode is "managed" and + r.type is "aws_instance" + } + +You can add specific attributes to the filter to narrow the search, such as the +module address. The following code would return resources in a module named +`foo` only: + + all_aws_instances = filter tfconfig.resources as _, r { + r.module_address is "module.foo" and + r.mode is "managed" and + r.type is "aws_instance" + } + +### Address Differences Between `tfconfig`, `tfplan`, and `tfstate` + +This import deals with configuration before it is expanded into a +resource graph by Terraform. As such, it is not possible to compute an index as +the import is building its collections and computing addresses for resources and +modules. + +As such, addresses found here may not always match the expanded addresses found +in the [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) and [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) +imports, specifically when +[`count`](/terraform/language/resources#count-multiple-resource-instances-by-count) +and +[`for_each`](/terraform/language/resources#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings), +are used. + +As an example, consider a resource named `null_resource.foo` with a count of `2` +located in a module named `bar`. While there will possibly be entries in the +other imports for `module.bar.null_resource.foo[0]` and +`module.bar.null_resource.foo[1]`, in `tfconfig/v2`, there will only be a +`module.bar.null_resource.foo`. As mentioned in the start of this section, this +is because configuration actually _defines_ this scaling, whereas _expansion_ +actually happens when the resource graph is built, which happens as a natural +part of the refresh and planning process. + +The `strip_index` helper function, found in this import, can assist in +removing the indexes from addresses found in the `tfplan/v2` and `tfstate/v2` +imports so that data from those imports can be used to reference data in this +one. + +## The `strip_index` Function + +The `strip_index` helper function can be used to remove indexes from addresses +found in [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) and [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2), +by removing the indexes from each resource. + +This can be used to help facilitate cross-import lookups for data between plan, +state, and config. + + import "tfconfig/v2" as tfconfig + import "tfplan/v2" as tfplan + + main = rule { + all filter tfplan.resource_changes as _, rc { + rc.mode is "managed" and + rc.type is "aws_instance" + } as _, rc { + tfconfig.resources[tfconfig.strip_index(rc.address)].config.ami.constant_value is "ami-abcdefgh012345" + } + } + +## Expression Representations + +Most collections in this import will have one of two kinds of _expression +representations_. This is a verbose format for expressing a (parsed) +configuration value independent of the configuration source code, which is not +100% available to a policy check in HCP Terraform. + + (expression representation) + ├── constant_value (value) + └── references (list of strings) + +There are two major parts to an expression representation: + +- Any _strictly constant value_ is expressed as an expression with a + `constant_value` field. +- Any expression that requires some degree of evaluation to generate the final + value - even if that value is known at plan time - is not expressed in + configuration. Instead, any particular references that are made are added to + the `references` field. More details on this field can be found in the + [expression + representation](/terraform/internals/json-format#expression-representation) + section of the JSON output format documentation. + +For example, to determine if an output is based on a particular +resource value, one could do: + + import "tfconfig/v2" as tfconfig + + main = rule { + tfconfig.outputs["instance_id"].value.references is ["aws_instance.foo"] + } + +-> **Note:** The representation does not account for +complex interpolations or other expressions that combine constants with other +expression data. For example, the partially constant data in `"foo${var.bar}"` would be lost. + +### Block Expression Representation + +Expanding on the above, a multi-value expression representation (such as the +kind found in a [`resources`](#the-resources-collection) collection element) is +similar, but the root value is a keyed map of expression representations. This +is repeated until a "scalar" expression value is encountered, ie: a field that +is not a block in the resource's schema. + + (block expression representation) + └── (attribute key) + ├── (child block expression representation) + │ └── (...) + ├── constant_value (value) + └── references (list of strings) + +As an example, one can validate expressions in an +[`aws_instance`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance) resource using the +following: + + import "tfconfig/v2" as tfconfig + + main = rule { + tfconfig.resources["aws_instance.foo"].config.ami.constant_value is "ami-abcdefgh012345" + } + +Note that _nested blocks_, sometimes known as _sub-resources_, will be nested in +configuration as a list of blocks (reflecting their ultimate nature as a list +of objects). An example would be the `aws_instance` resource's +[`ebs_block_device`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance#ebs-ephemeral-and-root-block-devices) block: + + import "tfconfig/v2" as tfconfig + + main = rule { + tfconfig.resources["aws_instance.foo"].config.ebs_block_device[0].volume_size < 10 + } + +## The `providers` Collection + +The `providers` collection is a collection representing the configurations of +all provider instances across all modules in the configuration. + +This collection is indexed by an opaque key. This is currently +`module_address:provider.alias`, the same value as found in the +`provider_config_key` field. `module_address` and the colon delimiter are +omitted for the root module. + +The `provider_config_key` field is also found in the `resources` collection and +can be used to locate a provider that belongs to a configured resource. + +The fields in this collection are as follows: + +- `provider_config_key` - The opaque configuration key, used as the index key. +- `name` - The name of the provider, ie: `aws`. +- `full_name` - The fully-qualified name of the provider, e.g. `registry.terraform.io/hashicorp/aws`. +- `alias` - The alias of the provider, ie: `east`. Empty for a default provider. +- `module_address` - The address of the module this provider appears in. +- `config` - A [block expression + representation](#block-expression-representation) with provider configuration + values. +- `version_constraint` - The defined version constraint for this provider. + +## The `resources` Collection + +The `resources` collection is a collection representing all of the resources +found in all modules in the configuration. + +This collection is indexed by the resource address. + +The fields in this collection are as follows: + +- `address` - The resource address. This is the index of the collection. +- `module_address` - The module address that this resource was found in. +- `mode` - The resource mode, either `managed` (resources) or `data` (data + sources). +- `type` - The type of resource, ie: `null_resource` in `null_resource.foo`. +- `name` - The name of the resource, ie: `foo` in `null_resource.foo`. +- `provider_config_key` - The opaque configuration key that serves as the index + of the [`providers`](#the-providers-collection) collection. +- `provisioners` - The ordered list of provisioners for this resource. The + syntax of the provisioners matches those found in the + [`provisioners`](#the-provisioners-collection) collection, but is a list + indexed by the order the provisioners show up in the resource. +- `config` - The [block expression + representation](#block-expression-representation) of the configuration values + found in the resource. +- `count` - The [expression data](#expression-representations) for the `count` + value in the resource. +- `for_each` - The [expression data](#expression-representations) for the + `for_each` value in the resource. +- `depends_on` - The contents of the `depends_on` config directive, which + declares explicit dependencies for this resource. + +## The `provisioners` Collection + +The `provisioners` collection is a collection of all of the provisioners found +across all resources in the configuration. + +While normally bound to a resource in an ordered fashion, this collection allows +for the filtering of provisioners within a single expression. + +This collection is indexed with a key following the format +`resource_address:index`, with each field matching their respective field in the +particular element below: + +- `resource_address`: The address of the resource that the provisioner was found + in. This can be found in the [`resources`](#the-resources-collection) + collection. +- `type`: The provisioner type, ie: `local_exec`. +- `index`: The provisioner index as it shows up in the resource provisioner + order. +- `config`: The [block expression + representation](#block-expression-representation) of the configuration values + in the provisioner. + +## The `variables` Collection + +The `variables` collection is a collection of all variables across all modules +in the configuration. + +Note that this tracks variable definitions, not values. See the [`tfplan/v2` +`variables` collection](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-variables-collection) for variable +values set within a plan. + +This collection is indexed by the key format `module_address:name`, with each +field matching their respective name below. `module_address` and the colon +delimiter are omitted for the root module. + +- `module_address` - The address of the module the variable was found in. +- `name` - The name of the variable. +- `default` - The defined default value of the variable. +- `description` - The description of the variable. + +## The `outputs` Collection + +The `outputs` collection is a collection of all outputs across all modules in +the configuration. + +Note that this tracks variable definitions, not values. See the [`tfstate/v2` +`outputs` collection](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2#the-outputs-collection) for the final +values of outputs set within a state. The [`tfplan/v2` `output_changes` +collection](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-output_changes-collection) also contains a more +complex collection of planned output changes. + +This collection is indexed by the key format `module_address:name`, with each +field matching their respective name below. `module_address` and the colon +delimiter are omitted for the root module. + +- `module_address` - The address of the module the output was found in. +- `name` - The name of the output. +- `sensitive` - Indicates whether or not the output was marked as + [`sensitive`](/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output). +- `value` - An [expression representation](#expression-representations) for the output. +- `description` - The description of the output. +- `depends_on` - A list of resource names that the output depends on. These are + the hard-defined output dependencies as defined in the + [`depends_on`](/terraform/language/values/outputs#depends_on-explicit-output-dependencies) + field in an output declaration, not the dependencies that get derived from + natural evaluation of the output expression (these can be found in the + `references` field of the expression representation). + +## The `module_calls` Collection + +The `module_calls` collection is a collection of all module declarations at all +levels within the configuration. + +Note that this is the +[`module`](/terraform/language/modules#calling-a-child-module) stanza in +any particular configuration, and not the module itself. Hence, a declaration +for `module.foo` would actually be declared in the root module, which would be +represented by a blank field in `module_address`. + +This collection is indexed by the key format `module_address:name`, with each +field matching their respective name below. `module_address` and the colon +delimiter are omitted for the root module. + +- `module_address` - The address of the module the declaration was found in. +- `name` - The name of the module. +- `source` - The contents of the `source` field. +- `config` - A [block expression + representation](#block-expression-representation) for all parameter values + sent to the module. +- `count` - An [expression representation](#expression-representations) for the + `count` field. +- `depends_on`: An [expression representation](#expression-representations) for the + `depends_on` field. +- `for_each` - An [expression representation](#expression-representations) for + the `for_each` field. +- `version_constraint` - The string value found in the `version` field of the + module declaration. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfconfig.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfconfig.mdx new file mode 100644 index 0000000000..dd83787db5 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfconfig.mdx @@ -0,0 +1,976 @@ +--- +page_title: tfconfig Sentinel import +description: Use tfconfig import to give Sentinel access to a Terraform configuration. +source: terraform-docs-common +--- + +# tfconfig Sentinel import + +~> **Warning:** The `tfconfig` import is now deprecated and will be permanently removed in August 2025. We recommend that you start using the updated [tfconfig/v2](/terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2) import as soon as possible to avoid disruptions. The `tfconfig/v2` import offers improved functionality and is designed to better support your policy enforcement needs. + +The `tfconfig` import provides access to a Terraform configuration. + +The Terraform configuration is the set of `*.tf` files that are used to +describe the desired infrastructure state. Policies using the `tfconfig` +import can access all aspects of the configuration: providers, resources, +data sources, modules, and variables. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Some use cases for `tfconfig` include: + +- **Organizational naming conventions**: requiring that configuration elements + are named in a way that conforms to some organization-wide standard. +- **Required inputs and outputs**: organizations may require a particular set + of input variable names across all workspaces or may require a particular + set of outputs for asset management purposes. +- **Enforcing particular modules**: organizations may provide a number of + "building block" modules and require that each workspace be built only from + combinations of these modules. +- **Enforcing particular providers or resources**: an organization may wish to + require or prevent the use of providers and/or resources so that configuration + authors cannot use alternative approaches to work around policy + restrictions. + +Note with these use cases that this import is concerned with object _names_ +in the configuration. Since this is the configuration and not an invocation +of Terraform, you can't see values for variables, the state, or the diff for +a pending plan. If you want to write policy around expressions used +within configuration blocks, you likely want to use the +[`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import. + +## Namespace Overview + +The following is a tree view of the import namespace. For more detail on a +particular part of the namespace, see below. + +-> **Note:** The root-level alias keys shown here (`data`, `modules`, +`providers`, `resources`, and `variables`) are shortcuts to a [module +namespace](#namespace-module) scoped to the root module. For more details, see +the section on [root namespace aliases](#root-namespace-aliases). + + tfconfig + ├── module() (function) + │ └── (module namespace) + │ ├── data + │ │ └── TYPE.NAME + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── provisioners + │ │ └── NUMBER + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── type (string) + │ ├── modules + │ │ └── NAME + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ ├── source (string) + │ │ └── version (string) + │ ├──outputs + │ │ └── NAME + │ │ ├── depends_on (list of strings) + │ │ ├── description (string) + │ │ ├── sensitive (boolean) + │ │ ├── references (list of strings) (TF 0.12 and later) + │ │ └── value (value) + │ ├── providers + │ │ └── TYPE + │ │ ├── alias + │ │ │ └── ALIAS + │ │ │ ├── config (map of keys) + │ │ | ├── references (map of keys) (TF 0.12 and later) + │ │ │ └── version (string) + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── version (string) + │ ├── resources + │ │ └── TYPE.NAME + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── provisioners + │ │ └── NUMBER + │ │ ├── config (map of keys) + │ │ ├── references (map of keys) (TF 0.12 and later) + │ │ └── type (string) + │ └── variables + │ └── NAME + │ ├── default (value) + │ └── description (string) + ├── module_paths ([][]string) + │ + ├── data (root module alias) + ├── modules (root module alias) + ├── outputs (root module alias) + ├── providers (root module alias) + ├── resources (root module alias) + └── variables (root module alias) + +### `references` with Terraform 0.12 + +**With Terraform 0.11 or earlier**, if a configuration value is defined as an +expression (and not a static value), the value will be accessible in its raw, +non-interpolated string (just as with a constant value). + +As an example, consider the following resource block: + +```hcl +resource "local_file" "accounts" { + content = "some text" + filename = "${var.subdomain}.${var.domain}/accounts.txt" +} +``` + +In this example, one might want to ensure `domain` and `subdomain` input +variables are used within `filename` in this configuration. With Terraform 0.11 or +earlier, the following policy would evaluate to `true`: + +```python +import "tfconfig" + +# filename_value is the raw, non-interpolated string +filename_value = tfconfig.resources.local_file.accounts.config.filename + +main = rule { + filename_value contains "${var.domain}" and + filename_value contains "${var.subdomain}" +} +``` + +**With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present within the +configuration value and `references` should be used instead: + +```python +import "tfconfig" + +# filename_references is a list of string values containing the references used in the expression +filename_references = tfconfig.resources.local_file.accounts.references.filename + +main = rule { + filename_references contains "var.domain" and + filename_references contains "var.subdomain" +} +``` + +The `references` value is present in any namespace where non-constant +configuration values can be expressed. This is essentially every namespace +which has a `config` value as well as the `outputs` namespace. + +-> **Note:** Remember, this import enforces policy around the literal Terraform +configuration and not the final values as a result of invoking Terraform. If +you want to write policy around the _result_ of expressions used within +configuration blocks (for example, if you wanted to ensure the final value of +`filename` above includes `accounts.txt`), you likely want to use the +[`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import. + +## Namespace: Root + +The root-level namespace consists of the values and functions documented below. + +In addition to this, the root-level `data`, `modules`, `providers`, `resources`, +and `variables` keys all alias to their corresponding namespaces within the +[module namespace](#namespace-module). + + + +### Function: `module()` + + module = func(ADDR) + +- **Return Type:** A [module namespace](#namespace-module). + +The `module()` function in the [root namespace](#namespace-root) returns the +[module namespace](#namespace-module) for a particular module address. + +The address must be a list and is the module address, split on the period (`.`), +excluding the root module. + +Hence, a module with an address of simply `foo` (or `root.foo`) would be +`["foo"]`, and a module within that (so address `foo.bar`) would be read as +`["foo", "bar"]`. + +[`null`][ref-null] is returned if a module address is invalid, or if the module +is not present in the configuration. + +[ref-null]: /sentinel/docs/language/spec#null + +As an example, given the following module block: + +```hcl +module "foo" { + # ... +} +``` + +If the module contained the following content: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { subject.module(["foo"]).resources.null_resource.foo.config.triggers[0].foo is "bar" } +``` + + + +### Value: `module_paths` + +- **Value Type:** List of a list of strings. + +The `module_paths` value within the [root namespace](#namespace-root) is a list +of all of the modules within the Terraform configuration. + +Modules not present in the configuration will not be present here, even if they +are present in the diff or state. + +This data is represented as a list of a list of strings, with the inner list +being the module address, split on the period (`.`). + +The root module is included in this list, represented as an empty inner list. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The value of `module_paths` would be: + + [ + [], + ["foo"], + ] + +And the following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.module_paths contains ["foo"] } +``` + +#### Iterating Through Modules + +Iterating through all modules to find particular resources can be useful. This +[example][iterate-over-modules] shows how to use `module_paths` with the +[`module()` function](#function-module-) to find all resources of a +particular type from all modules using the `tfplan` import. By changing `tfplan` +in this function to `tfconfig`, you could make a similar function find all +resources of a specific type in the Terraform configuration. + +[iterate-over-modules]: /terraform/enterprise/policy-enforcement/sentinel#sentinel-imports + +## Namespace: Module + +The **module namespace** can be loaded by calling [`module()`](#root-function-module) +for a particular module. + +It can be used to load the following child namespaces: + +- `data` - Loads the [resource namespace](#namespace-resources-data-sources), + filtered against data sources. +- `modules` - Loads the [module configuration + namespace](#namespace-module-configuration). +- `outputs` - Loads the [output namespace](#namespace-outputs). +- `providers` - Loads the [provider namespace](#namespace-providers). +- `resources` - Loads the [resource + namespace](#namespace-resources-data-sources), filtered against resources. +- `variables` - Loads the [variable namespace](#namespace-variables). + +### Root Namespace Aliases + +The root-level `data`, `modules`, `providers`, `resources`, and `variables` keys +all alias to their corresponding namespaces within the module namespace, loaded +for the root module. They are the equivalent of running `module([]).KEY`. + + + +## Namespace: Resources/Data Sources + +The **resource namespace** is a namespace _type_ that applies to both resources +(accessed by using the `resources` namespace key) and data sources (accessed +using the `data` namespace key). + +Accessing an individual resource or data source within each respective namespace +can be accomplished by specifying the type and name, in the syntax +`[resources|data].TYPE.NAME`. + +In addition, each of these namespace levels is a map, allowing you to filter +based on type and name. Some examples of multi-level access are below: + +- To fetch all `aws_instance` resources within the root module, you can specify + `tfconfig.resources.aws_instance`. This would give you a map of resource + namespaces indexed from the names of each resource (`foo`, `bar`, and so + on). +- To fetch all resources within the root module, irrespective of type, use + `tfconfig.resources`. This is indexed by type, as shown above with + `tfconfig.resources.aws_instance`, with names being the next level down. + +As an example, perhaps you wish to deny use of the `local_file` resource +in your configuration. Consider the following resource block: + +```hcl +resource "local_file" "foo" { + content = "foo!" + filename = "${path.module}/foo.bar" +} +``` + +The following policy would fail: + +```python +import "tfconfig" + +main = rule { tfconfig.resources not contains "local_file" } +``` + +Further explanation of the namespace will be in the context of resources. As +mentioned, when operating on data sources, use the same syntax, except with +`data` in place of `resources`. + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +The `config` value within the [resource +namespace](#namespace-resources-data-sources) is a map of key-value pairs that +directly map to Terraform config keys and values. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#resources-value-references) should be used instead. + +As an example, consider the following resource block: + +```hcl +resource "local_file" "accounts" { + content = "some text" + filename = "accounts.txt" +} +``` + +In this example, one might want to access `filename` to validate that the correct +file name is used. Given the above example, the following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { + tfconfig.resources.local_file.accounts.config.filename is "accounts.txt" +} +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [resource namespace](#namespace-resources-data-sources) +contains the identifiers within non-constant expressions found in [`config`](#resources-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + + + +### Value: `provisioners` + +- **Value Type:** List of [provisioner namespaces](#namespace-provisioners). + +The `provisioners` value within the [resource namespace](#namespace-resources) +represents the [provisioners][ref-tf-provisioners] within a specific resource. + +Provisioners are listed in the order they were provided in the configuration +file. + +While the `provisioners` value will be present within data sources, it will +always be an empty map (in Terraform 0.11) or `null` (in Terraform 0.12) since +data sources cannot actually have provisioners. + +The data within a provisioner can be inspected via the returned [provisioner +namespace](#namespace-provisioners). + +[ref-tf-provisioners]: /terraform/language/resources/provisioners/syntax + +## Namespace: Provisioners + +The **provisioner namespace** represents the configuration for a particular +[provisioner][ref-tf-provisioners] within a specific resource. + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +The `config` value within the [provisioner namespace](#namespace-provisioners) +represents the values of the keys within the provisioner. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#provisioners-value-references) should be used instead. + +As an example, given the following resource block: + +```hcl +resource "null_resource" "foo" { + # ... + + provisioner "local-exec" { + command = "echo ${self.private_ip} > file.txt" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { + tfconfig.resources.null_resource.foo.provisioners[0].config.command is "echo ${self.private_ip} > file.txt" +} +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [provisioner namespace](#namespace-provisioners) +contains the identifiers within non-constant expressions found in [`config`](#provisioners-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + + + +### Value: `type` + +- **Value Type:** String. + +The `type` value within the [provisioner namespace](#namespace-provisioners) +represents the type of the specific provisioner. + +As an example, in the following resource block: + +```hcl +resource "null_resource" "foo" { + # ... + + provisioner "local-exec" { + command = "echo ${self.private_ip} > file.txt" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.resources.null_resource.foo.provisioners[0].type is "local-exec" } +``` + +## Namespace: Module Configuration + +The **module configuration** namespace displays data on _module configuration_ +as it is given within a `module` block. This means that the namespace concerns +itself with the contents of the declaration block (example: the `source` +parameter and variable assignment keys), not the data within the module +(example: any contained resources or data sources). For the latter, the module +instance would need to be looked up with the [`module()` +function](#root-function-module). + + + +### Value: `source` + +- **Value Type:** String. + +The `source` value within the [module configuration +namespace](#namespace-module-configuration) represents the module source path as +supplied to the module configuration. + +As an example, given the module declaration block: + +```hcl +module "foo" { + source = "./foo" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.modules.foo.source is "./foo" } +``` + + + +### Value: `version` + +- **Value Type:** String. + +The `version` value within the [module configuration +namespace](#namespace-module-configuration) represents the [version +constraint][module-version-constraint] for modules that support it, such as +modules within the [Terraform Module Registry][terraform-module-registry] or the +[HCP Terraform private module registry][tfe-private-registry]. + +[module-version-constraint]: /terraform/language/modules#module-versions + +[terraform-module-registry]: https://registry.terraform.io/ + +[tfe-private-registry]: /terraform/enterprise/registry + +As an example, given the module declaration block: + +```hcl +module "foo" { + source = "foo/bar" + version = "~> 1.2" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.modules.foo.version is "~> 1.2" } +``` + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#modules-value-references) should be used instead. + +The `config` value within the [module configuration +namespace](#namespace-module-configuration) represents the values of the keys +within the module configuration. This is every key within a module declaration +block except [`source`](#modules-value-source) and [`version`](#modules-value-version), which +have their own values. + +As an example, given the module declaration block: + +```hcl +module "foo" { + source = "./foo" + + bar = "baz" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.modules.foo.config.bar is "baz" } +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [module configuration namespace](#namespace-module-configuration) +contains the identifiers within non-constant expressions found in [`config`](#modules-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + +## Namespace: Outputs + +The **output namespace** represents _declared_ output data within a +configuration. As such, configuration for the [`value`](#outputs-value-value) attribute +will be in its raw form, and not yet interpolated. For fully interpolated output +values, see the [`tfstate` import][ref-tfe-sentinel-tfstate]. + +[ref-tfe-sentinel-tfstate]: /terraform/enterprise/policy-enforcement/import-reference/tfstate-v2 + +This namespace is indexed by output name. + + + +### Value: `depends_on` + +- **Value Type:** A list of strings. + +The `depends_on` value within the [output namespace](#namespace-outputs) +represents any _explicit_ dependencies for this output. For more information, +see the [depends_on output setting][ref-depends_on] within the general Terraform +documentation. + +[ref-depends_on]: /terraform/language/values/outputs#depends_on + +As an example, given the following output declaration block: + +```hcl +output "id" { + depends_on = ["null_resource.bar"] + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.depends_on[0] is "null_resource.bar" } +``` + + + +### Value: `description` + +- **Value Type:** String. + +The `description` value within the [output namespace](#namespace-outputs) +represents the defined description for this output. + +As an example, given the following output declaration block: + +```hcl +output "id" { + description = "foobar" + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.description is "foobar" } +``` + + + +### Value: `sensitive` + +- **Value Type:** Boolean. + +The `sensitive` value within the [output namespace](#namespace-outputs) +represents if this value has been marked as sensitive or not. + +As an example, given the following output declaration block: + +```hcl +output "id" { + sensitive = true + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { subject.outputs.id.sensitive } +``` + + + +### Value: `value` + +- **Value Type:** Any primitive type, list or map. + +The `value` value within the [output namespace](#namespace-outputs) represents +the defined value for the output as declared in the configuration. Primitives +will bear the implicit type of their declaration (string, int, float, or bool), +and maps and lists will be represented as such. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#outputs-value-references) should be used instead. + +As an example, given the following output declaration block: + +```hcl +output "id" { + value = "${null_resource.foo.id}" +} +``` + +With Terraform 0.11 or earlier the following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.value is "${null_resource.foo.id}" } +``` + + + +### Value: `references` + +- **Value Type:**. List of strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [output namespace](#namespace-outputs) +contains the names of any referenced identifiers when [`value`](#outputs-value-value) +is a non-constant expression. + +As an example, given the following output declaration block: + +```hcl +output "id" { + value = "${null_resource.foo.id}" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.outputs.id.references contains "null_resource.foo.id" } +``` + +## Namespace: Providers + +The **provider namespace** represents data on the declared providers within a +namespace. + +This namespace is indexed by provider type and _only_ contains data about +providers when actually declared. If you are using a completely implicit +provider configuration, this namespace will be empty. + +This namespace is populated based on the following criteria: + +- The top-level namespace [`config`](#providers-value-config) and + [`version`](#providers-value-version) values are populated with the configuration and + version information from the default provider (the provider declaration that + lacks an alias). +- Any aliased providers are added as namespaces within the + [`alias`](#providers-value-alias) value. +- If a module lacks a default provider configuration, the top-level `config` and + `version` values will be empty. + + + +### Value: `alias` + +- **Value Type:** A map of [provider namespaces](#namespace-providers), indexed + by alias. + +The `alias` value within the [provider namespace](#namespace-providers) +represents all declared [non-default provider +instances][ref-tf-provider-instances] for a specific provider type, indexed by +their specific alias. + +[ref-tf-provider-instances]: /terraform/language/providers/configuration#alias-multiple-provider-configurations + +The return type is a provider namespace with the data for the instance in +question loaded. The `alias` key will not be available within this namespace. + +As an example, given the following provider declaration block: + +```hcl +provider "aws" { + alias = "east" + region = "us-east-1" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.providers.aws.alias.east.config.region is "us-east-1" } +``` + + + +### Value: `config` + +- **Value Type:** A string-keyed map of values. + +-> **With Terraform 0.11 or earlier**, if the config value is defined as an +expression (and not a static value), the value will be in its raw, +non-interpolated string. **With Terraform 0.12 or later**, any non-static +values (such as interpolated strings) are not present and +[`references`](#providers-value-references) should be used instead. + +The `config` value within the [provider namespace](#namespace-providers) +represents the values of the keys within the provider's configuration, with the +exception of the provider version, which is represented by the +[`version`](#providers-value-version) value. [`alias`](#providers-value-alias) is also not included +when the provider is aliased. + +As an example, given the following provider declaration block: + +```hcl +provider "aws" { + region = "us-east-1" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.providers.aws.config.region is "us-east-1" } +``` + + + +### Value: `references` + +- **Value Type:** A string-keyed map of list values containing strings. + +-> **Note:** This value is only present when using Terraform 0.12 or later. + +The `references` value within the [provider namespace](#namespace-providers) +contains the identifiers within non-constant expressions found in [`config`](#providers-value-config). +See the [documentation on `references`](#references-with-terraform-0-12) for more information. + + + +### Value: `version` + +- **Value Type:** String. + +The `version` value within the [provider namespace](#namespace-providers) +represents the explicit expected version of the supplied provider. This includes +the pessimistic operator. + +As an example, given the following provider declaration block: + +```hcl +provider "aws" { + version = "~> 1.34" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.providers.aws.version is "~> 1.34" } +``` + +## Namespace: Variables + +The **variable namespace** represents _declared_ variable data within a +configuration. As such, static data can be extracted, such as defaults, but not +dynamic data, such as the current value of a variable within a plan (although +this can be extracted within the [`tfplan` import][ref-tfe-sentinel-tfplan]). + +[ref-tfe-sentinel-tfplan]: /terraform/enterprise/policy-enforcement/import-reference/tfplan-v2 + +This namespace is indexed by variable name. + + + +### Value: `default` + +- **Value Type:** Any primitive type, list, map, or `null`. + +The `default` value within the [variable namespace](#namespace-variables) +represents the default for the variable as declared in the configuration. + +The actual value will be as configured. Primitives will bear the implicit type +of their declaration (string, int, float, or bool), and maps and lists will be +represented as such. + +If no default is present, the value will be [`null`][ref-sentinel-null] (not to +be confused with [`undefined`][ref-sentinel-undefined]). + +[ref-sentinel-null]: /sentinel/docs/language/spec#null + +[ref-sentinel-undefined]: /sentinel/docs/language/undefined + +As an example, given the following variable blocks: + +```hcl +variable "foo" { + default = "bar" +} + +variable "number" { + default = 42 +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +default_foo = rule { tfconfig.variables.foo.default is "bar" } +default_number = rule { tfconfig.variables.number.default is 42 } + +main = rule { default_foo and default_number } +``` + + + +### Value: `description` + +- **Value Type:** String. + +The `description` value within the [variable namespace](#namespace-variables) +represents the description of the variable, as provided in configuration. + +As an example, given the following variable block: + +```hcl +variable "foo" { + description = "foobar" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfconfig" + +main = rule { tfconfig.variables.foo.description is "foobar" } +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfplan-v2.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfplan-v2.mdx new file mode 100644 index 0000000000..68d18aa3dd --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfplan-v2.mdx @@ -0,0 +1,388 @@ +--- +page_title: tfplan/v2 Sentinel import +description: Use tfplan/v2 import to give Sentinel access to a Terraform plan. +source: terraform-docs-common +--- + +-> **Note:** This is documentation for the next version of the `tfplan` Sentinel +import, designed specifically for Terraform 0.12. This import requires +Terraform 0.12 or higher, and must currently be loaded by path, using an alias, +example: `import "tfplan/v2" as tfplan`. + +# tfplan/v2 Sentinel import + +The `tfplan/v2` import provides access to a Terraform plan. + +A Terraform plan is the file created as a result of `terraform plan` and is the +input to `terraform apply`. The plan represents the changes that Terraform needs +to make to infrastructure to reach the desired state represented by the +configuration. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +In addition to the diff data available in the plan, there is a "planned state" +that is available through this import, via the +[`planned_values`](#the-planned_values-collection) collection. This collection +presents the Terraform state as how it might look after the plan data is +applied, but is not guaranteed to be the final state. + +The data in the `tfplan/v2` import is sourced from the JSON configuration file +that is generated by the [`terraform show -json`](/terraform/cli/commands/show#json-output) command. For more information on +the file format, see the [JSON Output Format](/terraform/internals/json-format) +page. + +The entirety of the JSON output file is exposed as a Sentinel map via the +[`raw`](#the-raw-collection) collection. This allows direct, low-level access to +the JSON data, but should only be used in complex situations where the +higher-level collections do not serve the purpose. + +## Import Overview + +The `tfplan/v2` import is structured as a series of _collections_, keyed as a +specific format depending on the collection. + + tfplan/v2 + ├── terraform_version (string) + ├── variables + │ └── (indexed by name) + │ ├── name (string) + │ └── value (value) + ├── planned_values + │ ├── outputs (tfstate/v2 outputs representation) + │ └── resources (tfstate/v2 resources representation) + ├── resource_changes + │ └── (indexed by address[:deposed]) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── index (float (number) or string) + │ ├── provider_name (string) + │ ├── deposed (string) + │ └── change (change representation) + ├── resource_drift + │ └── (indexed by address[:deposed]) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── index (float (number) or string) + │ ├── provider_name (string) + │ ├── deposed (string) + │ └── change (change representation) + ├── output_changes + │ └── (indexed by name) + │ ├── name (string) + │ └── change (change representation) + └── raw (map) + +The collections are: + +- [`variables`](#the-variables-collection) - The values of variables that have + been set in the plan itself. This collection only contains variables set in + the root module. +- [`planned_values`](#the-planned_values-collection) - The state representation + of _planned values_, or an estimation of what the state will look like after + the plan is applied. +- [`resource_changes`](#the-resource_changes-and-resource_drift-collections) - The set of change + operations for resources and data sources within this plan. +- [`resource_drift`](#the-resource_changes-and-resource_drift-collections) - A description of the + changes Terraform detected when it compared the most recent state to the prior saved state. +- [`output_changes`](#the-output_changes-collection) - The changes to outputs + within this plan. This collection only contains outputs set in the root + module. +- [`raw`](#the-raw-collection) - Access to the raw plan data as stored by + HCP Terraform. + +These collections are specifically designed to be used with the +[`filter`](/sentinel/docs/language/collection-operations#filter-expression) +quantifier expression in Sentinel, so that one can collect a list of resources +to perform policy checks on without having to write complex discovery code. As +an example, the following code will return all `aws_instance` resource changes, +across all modules in the plan: + + all_aws_instances = filter tfplan.resource_changes as _, rc { + rc.mode is "managed" and + rc.type is "aws_instance" + } + +You can add specific attributes to the filter to narrow the search, such as the +module address, or the operation being performed. The following code would +return resources in a module named `foo` only, and further narrow the search +down to only resources that were being created: + + all_aws_instances = filter tfplan.resource_changes as _, rc { + rc.module_address is "module.foo" and + rc.mode is "managed" and + rc.type is "aws_instance" and + rc.change.actions is ["create"] + } + +### Change Representation + +Certain collections in this import contain a _change representation_, an object +with details about changes to a particular entity, such as a resource (within +the [`resource_changes`](#the-resource_changes-collection) collection), or +output (within the [`output_changes`](#the-output_changes-collection) +collection). + + (change representation) + ├── actions (list) + ├── before (value, or map) + ├── after (value, or map) + └── after_unknown (boolean, or map of booleans) + +This change representation contains the following fields: + +- `actions` - A list of actions being carried out for this change. The order is + important, for example a regular replace operation is denoted by `["delete", + "create"]`, but a + [`create_before_destroy`](/terraform/language/meta-arguments/lifecycle#create_before_destroy) + resource will have an operation order of `["create", "delete"]`. +- `before` - The representation of the resource data object value before the + action. For create-only actions, this is unset. For no-op actions, this value + will be identical with `after`. +- `after` - The representation of the resource data object value after the + action. For delete-only actions, this is unset. For no-op actions, this value + will be identical with `before`. Note that unknown values will not show up in + this field. +- `after_unknown` - A deep object of booleans that denotes any values that are + unknown in a resource. These values were previously referred to as "computed" + values. If the value cannot be found in this map, then its value should be + available within `after`, so long as the operation supports it. + +#### Actions + +As mentioned above, actions show up within the `actions` field of a change +representation and indicate the type of actions being performed as part of the +change, and the order that they are being performed in. + +The current list of actions are as follows: + +- `create` - The action will create the associated entity. Depending on the + order this appears in, the entity may be created alongside a copy of the + entity before replacing it. +- `read` - The action will read the associated entity. In practice, seeing this + change type should be rare, as reads generally happen before a plan is + executed (usually during a refresh). +- `update` - The action will update the associated entity in a way that alters its state + in some way. +- `delete` - The action will remove the associated entity, deleting any + applicable state and associated real resources or infrastructure. +- `no-op` - No action will be performed on the associated entity. + +The `actions` field is a list, as some real-world actions are actually a +composite of more than one primitive action. At this point in time, this +is generally only applicable to resource replacement, in which the following +action orders apply: + +- **Normal replacement:** `["delete", "create"]` - Applies to default lifecycle + configurations. +- **Create-before-destroy:** `["create", "delete"]` - Applies when + [`create_before_destroy`](/terraform/language/meta-arguments/lifecycle#create_before_destroy) + is used in a lifecycle configuration. + +Note that, in most situations, the plan will list all "changes", including no-op +changes. This makes filtering on change type crucial to the accurate selection +of data if you are concerned with the state change of a particular resource. + +To filter on a change type, use exact list comparison. For example, the +following example from the [Import Overview](#import-overview) filters on +exactly the resources being created _only_: + + all_aws_instances = filter tfplan.resource_changes as _, rc { + rc.module_address is "module.foo" and + rc.mode is "managed" and + rc.type is "aws_instance" and + rc.change.actions is ["create"] + } + +#### `before`, `after`, and `after_unknown` + +The exact attribute changes for a particular operation are outlined in the +`before` and `after` attributes. Depending on the entity being operated on, this +will either be a map (as with +[`resource_changes`](#the-resource_changes-collection)) or a singular value (as +with [`output_changes`](#the-output_changes-collection)). + +What you can expect in these fields varies depending on the operation: + +- For fresh create operations, `before` will generally be `null`, and `after` + will contain the data you can expect to see after the change. +- For full delete operations, this will be reversed - `before` will contain + data, and `after` will be `null`. +- Update or replace operations will have data in both fields relevant to their + states before and after the operation. +- No-op operations should have identical data in `before` and `after`. + +For resources, if a field cannot be found in `after`, it generally means one of +two things: + +- The attribute does not exist in the resource schema. Generally, known + attributes that do not have a value will show up as `null` or otherwise empty + in `after`. +- The attribute is _unknown_, that is, it was unable to be determined at plan + time and will only be available after apply-time values have been able to be + calculated. + +In the latter case, there should be a value for the particular attribute in +`after_unknown`, which can be checked to assert that the value is indeed +unknown, versus invalid: + + import "tfplan/v2" as tfplan + + no_unknown_amis = rule { + all filter tfplan.resource_changes as _, rc { + rc.module_address is "module.foo" and + rc.mode is "managed" and + rc.type is "aws_instance" and + rc.change.actions is ["create"] + } as _, rc { + rc.change.after_unknown.ami else false is false + } + } + +For output changes, `after_unknown` will simply be `true` if the value won't be +known until the plan is applied. + +## The `terraform_version` Value + +The top-level `terraform_version` value in this import gives the Terraform +version that made the plan. This can be used to do version validation. + + import "tfplan/v2" as tfplan + import "strings" + + v = strings.split(tfplan.terraform_version, ".") + version_major = int(v[1]) + version_minor = int(v[2]) + + main = rule { + version_major is 12 and version_minor >= 19 + } + +-> **NOTE:** The above example will give errors when working with pre-release +versions (example: `0.12.0beta1`). Future versions of this import will include +helpers to assist with processing versions that will account for these kinds of +exceptions. + +## The `variables` Collection + +The `variables` collection is a collection of the variables set in the root +module when creating the plan. + +This collection is indexed on the name of the variable. + +The valid values are: + +- `name` - The name of the variable, also used as the collection key. +- `value` - The value of the variable assigned during the plan. + +## The `planned_values` Collection + +The `planned_values` collection is a special collection in that it contains two +fields that alias to state collections with the _planned_ state set. This is the +best prediction of what the state will look like after the plan is executed. + +The two fields are: + +- `outputs` - The prediction of what output values will look like after the + state is applied. For more details on the structure of this collection, see + the [`outputs`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2#the-outputs-collection) collection in the + [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) documentation. +- `resources` - The prediction of what resource values will look like after the + state is applied. For more details on the structure of this collection, see + the [`resources`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2#the-resources-collection) collection in the + [`tfstate/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) documentation. + +-> **NOTE:** Unknown values are omitted from the `planned_values` state +representations, regardless of whether or not they existed before. Use +[`resource_changes`](#the-resource_changes-collection) if awareness of unknown +data is important. + +## The `resource_changes` and `resource_drift` Collections + +The `resource_changes` and `resource_drift` collections are a set of change operations for resources +and data sources within this plan. + +The `resource_drift` collection provides a description of the changes Terraform detected +when it compared the most recent state to the prior saved state. + +The `resource_changes` collection includes all resources that have been found in the configuration and state, +regardless of whether or not they are changing. + +~> When [resource targeting](/terraform/cli/commands/plan#resource-targeting) is in effect, the `resource_changes` collection will only include the resources specified as targets for the run. This may lead to unexpected outcomes if a policy expects a resource to be present in the plan. To prohibit targeted runs altogether, ensure [`tfrun.target_addrs`](/terraform/enterprise/policy-enforcement/import-reference/tfrun#value-target_addrs) is undefined or empty. + +This collection is indexed on the complete resource address as the key. If +`deposed` is non-empty, it is appended to the end, and may look something like +`aws_instance.foo:deposed-abc123`. + +An element contains the following fields: + +- `address` - The absolute resource address - also the key for the collection's + index, if `deposed` is empty. + +- `module_address` - The module portion of the absolute resource address. + +- `mode` - The resource mode, either `managed` (resources) or `data` (data + sources). + +- `type` - The resource type, example: `aws_instance` for `aws_instance.foo`. + +- `name` - The resource name, example: `foo` for `aws_instance.foo`. + +- `index` - The resource index. Can be either a number or a string. + +- `provider_name` - The name of the provider this resource belongs to. This + allows the provider to be interpreted unambiguously in the unusual situation + where a provider offers a resource type whose name does not start with its own + name, such as the `googlebeta` provider offering `google_compute_instance`. + + -> **Note:** Starting with Terraform 0.13, the `provider_name` field contains the + _full_ source address to the provider in the Terraform Registry. Example: + `registry.terraform.io/hashicorp/null` for the null provider. + +- `deposed` - An identifier used during replacement operations, and can be used + to identify the exact resource being replaced in state. + +- `change` - The data describing the change that will be made to this resource. + For more details, see [Change Representation](#change-representation). + +## The `output_changes` Collection + +The `output_changes` collection is a collection of the change operations for +outputs within this plan. + +Only outputs for the root module are included. + +This collection is indexed by the name of the output. The fields in a collection +value are below: + +- `name` - The name of the output, also the index key. +- `change` - The data describing the change that will be made to this output. + For more details, see [Change Representation](#change-representation). + +## The `raw` Collection + +The `raw` collection exposes the raw, unprocessed plan data, direct from the +data stored by HCP Terraform. + +This is the same data that is produced by [`terraform show -json`](/terraform/cli/commands/show#json-output) on the plan file for the run this +policy check is attached to. + +Use of this data is only recommended in expert situations where the data the +collections present may not exactly serve the needs of the policy. For more +information on the file format, see the [JSON Output +Format](/terraform/internals/json-format) page. + +-> **NOTE:** Although designed to be relatively stable, the actual makeup for +the JSON output format is a Terraform CLI concern and as such not managed by +HCP Terraform. Use at your own risk, follow the [Terraform CLI +project](https://github.com/hashicorp/terraform), and watch the file format +documentation for any changes. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfplan.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfplan.mdx new file mode 100644 index 0000000000..12832dd583 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfplan.mdx @@ -0,0 +1,604 @@ +--- +page_title: tfplan Sentinel import reference +description: Use the tfplan import to give Sentinel access to a Terraform plan. +source: terraform-docs-common +--- + +# tfplan Sentinel import reference + +~> **Warning:** The `tfplan` import is now deprecated and will be permanently removed in August 2025. We recommend that you start using the updated [tfplan/v2](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import as soon as possible to avoid disruptions. The `tfplan/v2` import offers improved functionality and is designed to better support your policy enforcement needs. + +The `tfplan` import provides access to a Terraform plan. A Terraform plan is the +file created as a result of `terraform plan` and is the input to `terraform +apply`. The plan represents the changes that Terraform needs to make to +infrastructure to reach the desired state represented by the configuration. + +In addition to the diff data available in the plan, there is an +[`applied`](#value-applied) state available that merges the plan with the state +to create the planned state after apply. + +Finally, this import also allows you to access the configuration files and the +Terraform state at the time the plan was run. See the section on [accessing a +plan's state and configuration +data](#accessing-a-plan-39-s-state-and-configuration-data) for more information. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Namespace Overview + +The following is a tree view of the import namespace. For more detail on a +particular part of the namespace, see below. + +-> Note that the root-level alias keys shown here (`data`, `path`, and +`resources`) are shortcuts to a [module namespace](#namespace-module) scoped to +the root module. For more details, see the section on [root namespace +aliases](#root-namespace-aliases). + + tfplan + ├── module() (function) + │ └── (module namespace) + │ ├── path ([]string) + │ ├── data + │ │ └── TYPE.NAME[NUMBER] + │ │ ├── applied (map of keys) + │ │ └── diff + │ │ └── KEY + │ │ ├── computed (bool) + │ │ ├── new (string) + │ │ └── old (string) + │ └── resources + │ └── TYPE.NAME[NUMBER] + │ ├── applied (map of keys) + │ ├── destroy (bool) + │ ├── requires_new (bool) + │ └── diff + │ └── KEY + │ ├── computed (bool) + │ ├── new (string) + │ └── old (string) + ├── module_paths ([][]string) + ├── terraform_version (string) + ├── variables (map of keys) + │ + ├── data (root module alias) + ├── path (root module alias) + ├── resources (root module alias) + │ + ├── config (tfconfig namespace alias) + └── state (tfstate import alias) + +## Namespace: Root + +The root-level namespace consists of the values and functions documented below. + +In addition to this, the root-level `data`, `path`, and `resources` keys alias +to their corresponding namespaces or values within the [module +namespace](#namespace-module). + +### Accessing a Plan's State and Configuration Data + +The `config` and `state` keys alias to the [`tfconfig`][import-tfconfig] and +[`tfstate`][import-tfstate] namespaces, respectively, with the data sourced from +the Terraform _plan_ (as opposed to actual configuration and state). + +[import-tfconfig]: /terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2 + +[import-tfstate]: /terraform/enterprise/policy-enforcement/import-reference/tfstate-v2 + +-> Note that these aliases are not represented as maps. While they will appear +empty when viewed as maps, the specific import namespace keys will still be +accessible. + +-> Note that while current versions of HCP Terraform source configuration and +state data from the plan for the Terraform run in question, future versions may +source data accessed through the `tfconfig` and `tfstate` imports (as opposed to +`tfplan.config` and `tfplan.state`) from actual config bundles, or state as +stored by HCP Terraform. When this happens, the distinction here will be useful - +the data in the aliased namespaces will be the config and state data as the +_plan_ sees it, versus the actual "physical" data. + +### Function: `module()` + + module = func(ADDR) + +- **Return Type:** A [module namespace](#namespace-module). + +The `module()` function in the [root namespace](#namespace-root) returns the +[module namespace](#namespace-module) for a particular module address. + +The address must be a list and is the module address, split on the period (`.`), +excluding the root module. + +Hence, a module with an address of simply `foo` (or `root.foo`) would be +`["foo"]`, and a module within that (so address `foo.bar`) would be read as +`["foo", "bar"]`. + +[`null`][ref-null] is returned if a module address is invalid, or if the module +is not present in the diff. + +[ref-null]: /sentinel/docs/language/spec#null + +As an example, given the following module block: + +```hcl +module "foo" { + # ... +} +``` + +If the module contained the following content: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfplan" + +main = rule { tfplan.module(["foo"]).resources.null_resource.foo[0].applied.triggers.foo is "bar" } +``` + +### Value: `module_paths` + +- **Value Type:** List of a list of strings. + +The `module_paths` value within the [root namespace](#namespace-root) is a list +of all of the modules within the Terraform diff for the current plan. + +Modules not present in the diff will not be present here, even if they are +present in the configuration or state. + +This data is represented as a list of a list of strings, with the inner list +being the module address, split on the period (`.`). + +The root module is included in this list, represented as an empty inner list, as +long as there are changes. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The value of `module_paths` would be: + + [ + [], + ["foo"], + ] + +And the following policy would evaluate to `true`: + +```python +import "tfplan" + +main = rule { tfplan.module_paths contains ["foo"] } +``` + +-> Note the above example only applies if the module is present in the diff. + +#### Iterating Through Modules + +Iterating through all modules to find particular resources can be useful. This +[example][iterate-over-modules] shows how to use `module_paths` with the +[`module()` function](#function-module-) to find all resources of a +particular type from all modules that have pending changes using the `tfplan` +import. + +[iterate-over-modules]: /terraform/enterprise/policy-enforcement/sentinel#sentinel-imports + +### Value: `terraform_version` + +- **Value Type:** String. + +The `terraform_version` value within the [root namespace](#namespace-root) +represents the version of Terraform used to create the plan. This can be used to +enforce a specific version of Terraform in a policy check. + +As an example, the following policy would evaluate to `true`, as long as the +plan was made with a version of Terraform in the 0.11.x series, excluding any +pre-release versions (example: `-beta1` or `-rc1`): + +```python +import "tfplan" + +main = rule { tfplan.terraform_version matches "^0\\.11\\.\\d+$" } +``` + +### Value: `variables` + +- **Value Type:** A string-keyed map of values. + +The `variables` value within the [root namespace](#namespace-root) represents +all of the variables that were set when creating the plan. This will only +contain variables set for the root module. + +Note that unlike the [`default`][import-tfconfig-variables-default] value in the +[`tfconfig` variables namespace][import-tfconfig-variables], primitive values +here are stringified, and type conversion will need to be performed to perform +comparison for int, float, or boolean values. This only applies to variables +that are primitives themselves and not primitives within maps and lists, which +will be their original types. + +[import-tfconfig-variables-default]: /terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2#value-default + +[import-tfconfig-variables]: /terraform/enterprise/policy-enforcement/import-reference/tfconfig-v2#namespace-variables + +If a default was accepted for the particular variable, the default value will be +populated here. + +As an example, given the following variable blocks: + +```hcl +variable "foo" { + default = "bar" +} + +variable "number" { + default = 42 +} + +variable "map" { + default = { + foo = "bar" + number = 42 + } +} +``` + +The following policy would evaluate to `true`, if no values were entered to +change these variables: + +```python +import "tfplan" + +default_foo = rule { tfplan.variables.foo is "bar" } +default_number = rule { tfplan.variables.number is "42" } +default_map_string = rule { tfplan.variables.map["foo"] is "bar" } +default_map_int = rule { tfplan.variables.map["number"] is 42 } + +main = rule { default_foo and default_number and default_map_string and default_map_int } +``` + +## Namespace: Module + +The **module namespace** can be loaded by calling +[`module()`](#function-module-) for a particular module. + +It can be used to load the following child namespaces, in addition to the values +documented below: + +- `data` - Loads the [resource namespace](#namespace-resources-data-sources), + filtered against data sources. +- `resources` - Loads the [resource + namespace](#namespace-resources-data-sources), filtered against resources. + +### Root Namespace Aliases + +The root-level `data` and `resources` keys both alias to their corresponding +namespaces within the module namespace, loaded for the root module. They are the +equivalent of running `module([]).KEY`. + +### Value: `path` + +- **Value Type:** List of strings. + +The `path` value within the [module namespace](#namespace-module) contains the +path of the module that the namespace represents. This is represented as a list +of strings. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The following policy would evaluate to `true` _only_ if the diff had changes for +that module: + +```python +import "tfplan" + +main = rule { tfplan.module(["foo"]).path contains "foo" } +``` + +## Namespace: Resources/Data Sources + +The **resource namespace** is a namespace _type_ that applies to both resources +(accessed by using the `resources` namespace key) and data sources (accessed +using the `data` namespace key). + +Accessing an individual resource or data source within each respective namespace +can be accomplished by specifying the type, name, and resource number (as if the +resource or data source had a `count` value in it) in the syntax +`[resources|data].TYPE.NAME[NUMBER]`. Note that NUMBER is always needed, even if +you did not use `count` in the resource. + +In addition, each of these namespace levels is a map, allowing you to filter +based on type and name. + +-> The (somewhat strange) notation here of `TYPE.NAME[NUMBER]` may imply that +the inner resource index map is actually a list, but it's not - using the square +bracket notation over the dotted notation (`TYPE.NAME.NUMBER`) is required here +as an identifier cannot start with a number. + +Some examples of multi-level access are below: + +- To fetch all `aws_instance.foo` resource instances within the root module, you + can specify `tfplan.resources.aws_instance.foo`. This would then be indexed by + resource count index (`0`, `1`, `2`, and so on). Note that as mentioned above, + these elements must be accessed using square-bracket map notation (so `[0]`, + `[1]`, `[2]`, and so on) instead of dotted notation. +- To fetch all `aws_instance` resources within the root module, you can specify + `tfplan.resources.aws_instance`. This would be indexed from the names of + each resource (`foo`, `bar`, and so on), with each of those maps containing + instances indexed by resource count index as per above. +- To fetch all resources within the root module, irrespective of type, use + `tfplan.resources`. This is indexed by type, as shown above with + `tfplan.resources.aws_instance`, with names being the next level down, and so + on. + +~> When [resource targeting](/terraform/cli/commands/plan#resource-targeting) is in effect, `tfplan.resources` will only include the resources specified as targets for the run. This may lead to unexpected outcomes if a policy expects a resource to be present in the plan. To prohibit targeted runs altogether, ensure [`tfrun.target_addrs`](/terraform/enterprise/policy-enforcement/import-reference/tfrun#value-target_addrs) is undefined or empty. + +Further explanation of the namespace will be in the context of resources. As +mentioned, when operating on data sources, use the same syntax, except with +`data` in place of `resources`. + +### Value: `applied` + +- **Value Type:** A string-keyed map of values. + +The `applied` value within the [resource +namespace](#namespace-resources-data-sources) contains a "predicted" +representation of the resource's state post-apply. It's created by merging the +pending resource's diff on top of the existing data from the resource's state +(if any). The map is a complex representation of these values with data going +as far down as needed to represent any state values such as maps, lists, and +sets. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if the resource was in the diff: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].applied.triggers.foo is "bar" } +``` + +-> Note that some values will not be available in the `applied` state because +they cannot be known until the plan is actually applied. In Terraform 0.11 or +earlier, these values are represented by a placeholder (the UUID value +`74D93920-ED26-11E3-AC10-0800200C9A66`) and in Terraform 0.12 or later they +are `undefined`. **In either case**, you should instead use the +[`computed`](#value-computed) key within the [diff +namespace](#namespace-resource-diff) to determine that a computed value will +exist. + +-> If a resource is being destroyed, its `applied` value is omitted from the +namespace and trying to fetch it will return undefined. + +### Value: `diff` + +- **Value Type:** A map of [diff namespaces](#namespace-resource-diff). + +The `diff` value within the [resource +namespace](#namespace-resources-data-sources) contains the diff for a particular +resource. Each key within the map links to a [diff +namespace](#namespace-resource-diff) for that particular key. + +Note that unlike the [`applied`](#value-applied) value, this map is not complex; +the map is only 1 level deep with each key possibly representing a diff for a +particular complex value within the resource. + +See the below section for more details on the diff namespace, in addition to +usage examples. + +### Value: `destroy` + +- **Value Type:** Boolean. + +The `destroy` value within the [resource +namespace](#namespace-resources-data-sources) is `true` if a resource is being +destroyed for _any_ reason, including cases where it's being deleted as part of +a resource re-creation, in which case [`requires_new`](#value-requires_new) will +also be set. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` when `null_resource.foo` is being +destroyed: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].destroy } +``` + +### Value: `requires_new` + +- **Value Type:** Boolean. + +The `requires_new` value within the [resource +namespace](#namespace-resources-data-sources) is `true` if the resource is still +present in the configuration, but must be replaced to satisfy its current diff. +Whenever `requires_new` is `true`, [`destroy`](#value-destroy) is also `true`. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if one of the `triggers` in +`null_resource.foo` was being changed: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].requires_new } +``` + +## Namespace: Resource Diff + +The **diff namespace** is a namespace that represents the diff for a specific +attribute within a resource. For details on reading a particular attribute, +see the [`diff`](#value-diff) value in the [resource +namespace](#namespace-resources-data-sources). + +### Value: `computed` + +- **Value Type:** Boolean. + +The `computed` value within the [diff namespace](#namespace-resource-diff) is +`true` if the resource key in question depends on another value that isn't yet +known. Typically, that means the value it depends on belongs to a resource that +either doesn't exist yet, or is changing state in such a way as to affect the +dependent value so that it can't be known until the apply is complete. + +-> Keep in mind that when using `computed` with complex structures such as maps, +lists, and sets, it's sometimes necessary to test the count attribute for the +structure, versus a key within it, depending on whether or not the diff has +marked the whole structure as computed. This is demonstrated in the example +below. Count keys are `%` for maps, and `#` for lists and sets. If you are +having trouble determining the type of specific field within a resource, contact +the support team. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} + +resource "null_resource" "bar" { + triggers = { + foo_id = "${null_resource.foo.id}" + } +} +``` + +The following policy would evaluate to `true`, if the `id` of +`null_resource.foo` was currently not known, such as when the resource is +pending creation, or is being deleted and re-created: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.bar[0].diff["triggers.%"].computed } +``` + +### Value: `new` + +- **Value Type:** String. + +The `new` value within the [diff namespace](#namespace-resource-diff) contains +the new value of a changing attribute, _if_ the value is known at plan time. + +-> `new` will be an empty string if the attribute's value is currently unknown. +For more details on detecting unknown values, see [`computed`](#value-computed). + +Note that this value is _always_ a string, regardless of the actual type of the +value changing. [Type conversion][ref-sentinel-type-conversion] within policy +may be necessary to achieve the comparison needed. + +[ref-sentinel-type-conversion]: /sentinel/docs/language/values#type-conversion + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`, if the resource was in the diff +and each of the concerned keys were changing to new values: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].diff["triggers.foo"].new is "bar" } +``` + +### Value: `old` + +- **Value Type:** String. + +The `old` value within the [diff namespace](#namespace-resource-diff) contains +the old value of a changing attribute. + +Note that this value is _always_ a string, regardless of the actual type of the +value changing. [Type conversion][ref-sentinel-type-conversion] within policy +may be necessary to achieve the comparison needed. + +If the value did not exist in the previous state, `old` will always be an empty +string. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "baz" + } +} +``` + +If that resource was previously in config as: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfplan" + +main = rule { tfplan.resources.null_resource.foo[0].diff["triggers.foo"].old is "bar" } +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfrun.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfrun.mdx new file mode 100644 index 0000000000..51d03dfd0e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfrun.mdx @@ -0,0 +1,320 @@ +--- +page_title: tfrun Sentinel import reference +description: >- + Use tfrun import to give Sentinel access to data associated with a Terraform + run. +source: terraform-docs-common +--- + +# tfrun Sentinel import reference + +The `tfrun` import provides access to data associated with a [Terraform run][run-glossary]. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +This import currently consists of run attributes, as well as namespaces for the `organization`, `workspace` and `cost-estimate`. Each namespace provides static data regarding the HCP Terraform application that can then be consumed by Sentinel during a policy evaluation. + + tfrun + ├── id (string) + ├── created_at (string) + ├── created_by (string) + ├── message (string) + ├── commit_sha (string) + ├── is_destroy (boolean) + ├── refresh (boolean) + ├── refresh_only (boolean) + ├── replace_addrs (array of strings) + ├── speculative (boolean) + ├── target_addrs (array of strings) + ├── project + │ ├── id (string) + │ └── name (string) + ├── variables (map of keys) + ├── organization + │ └── name (string) + ├── workspace + │ ├── id (string) + │ ├── name (string) + │ ├── created_at (string) + │ ├── description (string) + │ ├── execution_mode (string) + │ ├── auto_apply (bool) + │ ├── tags (array of strings) + | ├── tag_bindings (array of objects) + │ ├── working_directory (string) + │ └── vcs_repo (map of keys) + └── cost_estimate + ├── prior_monthly_cost (string) + ├── proposed_monthly_cost (string) + └── delta_monthly_cost (string) + +-> **Note:** When writing policies using this import, keep in mind that workspace +data is generally editable by users outside of the context of policy +enforcement. For example, consider the case of omitting the enforcement of +policy rules for development workspaces by the workspace name (allowing the +policy to pass if the workspace ends in `-dev`). While this is useful for +extremely granular exceptions, the workspace name could be edited by +workspace admins, effectively bypassing the policy. In this case, where an +extremely strict separation of policy managers vs. workspace practitioners is +required, using [policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) +to only enforce the policy on non-development workspaces is more appropriate. + +[run-glossary]: /terraform/docs/glossary#run + +[workspace-glossary]: /terraform/docs/glossary#workspace + +## Namespace: root + +The **root namespace** contains data associated with the current run. + +### Value: `id` + +- **Value Type:** String. + +Specifies the ID that is associated with the current Terraform run. + +### Value: `created_at` + +- **Value Type:** String. + +The `created_at` value within the [root namespace](#namespace-root) specifies the time that the run was created. The timestamp returned follows the format outlined in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). + +Users can use the `time` import to [load](/sentinel/docs/imports/time#time-load-timeish) a run timestamp and create a new timespace from the specified value. See the `time` import [documentation](/sentinel/docs/imports/time#import-time) for available actions that can be performed on timespaces. + +### Value: `created_by` + +- **Value Type:** String. + +The `created_by` value within the [root namespace](#namespace-root) is string that specifies the user name of the HCP Terraform user for the specific run. + +### Value: `message` + +- **Value Type:** String. + +Specifies the message that is associated with the Terraform run. + +The default value is _"Queued manually via the Terraform Enterprise API"_. + +### Value: `commit_sha` + +- **Value Type:** String. + +Specifies the checksum hash (SHA) that identifies the commit. + +### Value: `is_destroy` + +- **Value Type:** Boolean. + +Specifies if the plan is a destroy plan, which will destroy all provisioned resources. + +### Value: `refresh` + +- **Value Type:** Boolean. + +Specifies whether the state was refreshed prior to the plan. + +### Value: `refresh_only` + +- **Value Type:** Boolean. + +Specifies whether the plan is in refresh-only mode, which ignores configuration changes and updates state with any changes made outside of Terraform. + +### Value: `replace_addrs` + +- **Value Type:** An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing). + +Provides the targets specified using the [`-replace`](/terraform/cli/commands/plan#resource-targeting) flag in the CLI or the `replace-addrs` attribute in the API. Will be null if no resource targets are specified. + +### Value: `speculative` + +- **Value Type:** Boolean. + +Specifies whether the plan associated with the run is a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) only. + +### Value: `target_addrs` + +- **Value Type:** An array of strings representing [resource addresses](/terraform/cli/state/resource-addressing). + +Provides the targets specified using the [`-target`](/terraform/cli/commands/plan#resource-targeting) flag in the CLI or the `target-addrs` attribute in the API. Will be null if no resource targets are specified. + +To prohibit targeted runs altogether, make sure the `target_addrs` value is null or empty: + + import "tfrun" + + main = tfrun.target_addrs is null or tfrun.target_addrs is empty + +### Value: `variables` + +- **Value Type:** A string-keyed map of values. + +Provides the names of the variables that are configured within the run and the [sensitivity](/terraform/enterprise/workspaces/variables/managing-variables#sensitive-values) state of the value. + + variables (map of keys) + └── name (string) + └── category (string) + └── sensitive (boolean) + +## Namespace: project + +The **project namespace** contains data associated with the current run's [projects](/terraform/enterprise/api-docs/projects). + +### Value: `id` + +- **Value Type:** String. + +Specifies the ID that is associated with the current project. + +### Value: `name` + +- **Value Type:** String. + +Specifies the name assigned to the HCP Terraform project. + +## Namespace: organization + +The **organization namespace** contains data associated with the current run's HCP Terraform [organization](/terraform/enterprise/users-teams-organizations/organizations). + +### Value: `name` + +- **Value Type:** String. + +Specifies the name assigned to the HCP Terraform organization. + +## Namespace: workspace + +The **workspace namespace** contains data associated with the current run's workspace. + +### Value: `id` + +- **Value Type:** String. + +Specifies the ID that is associated with the Terraform workspace. + +### Value: `name` + +- **Value Type:** String. + +The name of the workspace, which can only include letters, numbers, `-`, and `_`. + +As an example, in a workspace named `app-us-east-dev` the following policy would evaluate to `true`: + + # Enforces production rules on all non-development workspaces + + import "tfrun" + import "strings" + + # (Actual policy logic omitted) + evaluate_production_policy = rule { ... } + + main = rule when strings.has_suffix(tfrun.workspace.name, "-dev") is false { + evaluate_production_policy + } + +### Value: `created_at` + +- **Value Type:** String. + +Specifies the time that the workspace was created. The timestamp returned follows the format outlined in [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). + +Users can use the `time` import to [load](/sentinel/docs/imports/time#time-load-timeish) a workspace timestamp, and create a new timespace from the specified value. See the `time` import [documentation](/sentinel/docs/imports/time#import-time) for available actions that can be performed on timespaces. + +### Value: `description` + +- **Value Type:** String. + +Contains the description for the workspace. + +This value can be `null`. + +### Value: `auto_apply` + +- **Value Type:** Boolean. + +Contains the workspace's [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) setting. + +### Value: `tags` + +- **Value Type:** Array of strings. + +Contains the list of tag names for the workspace, as well as the keys from tag bindings. + +### Value: `tag_bindings` + +- **Value Type:** Array of objects. + +Contains the complete list of tag bindings for the workspace, which includes inherited tag bindings, as well as the workspace key-only tags. Each binding has a string `key`, a nullable string `value`, as well as a boolean `inherited` properties. + + tag_bindings (array of objects) + ├── key (string) + ├── value (string or null) + └── inherited (boolean) + +### Value: `working_directory` + +- **Value Type:** String. + +Contains the configured [Terraform working directory](/terraform/enterprise/workspaces/settings#terraform-working-directory) of the workspace. + +This value can be `null`. + +### Value: `execution_mode` + +- **Value Type:** String. + +Contains the configured [Terraform execution mode](/terraform/enterprise/workspaces/settings#execution-mode) of the workspace. + +The default value is `remote`. + +### Value: `vcs_repo` + +- **Value Type:** A string-keyed map of values. + +Contains data associated with a VCS repository connected to the workspace. + +Details regarding each attribute can be found in the documentation for the HCP Terraform [Workspaces API](/terraform/enterprise/api-docs/workspaces). + +This value can be `null`. + + vcs_repo (map of keys) + ├── identifier (string) + ├── display_identifier (string) + ├── branch (string) + └── ingress_submodules (bool) + +## Namespace: cost_estimate + +The **cost_estimation namespace** contains data associated with the current run's cost estimate. + +This namespace is only present if a cost estimate is available. + +-> Cost estimation is disabled for runs using [resource targeting](/terraform/cli/commands/plan#resource-targeting), which may cause unexpected failures. + +-> **Note:** Cost estimates are not available for Terraform 0.11. + +### Value: `prior_monthly_cost` + +- **Value Type:** String. + +Contains the monthly cost estimate at the beginning of a plan. + +This value contains a positive decimal and can be `"0.0"`. + +### Value: `proposed_monthly_cost` + +- **Value Type:** String. + +Contains the monthly cost estimate if the plan were to be applied. + +This value contains a positive decimal and can be `"0.0"`. + +### Value: `delta_monthly_cost` + +- **Value Type:** String. + +Contains the difference between the prior and proposed monthly cost estimates. + +This value may contain a positive or negative decimal and can be `"0.0"`. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfstate-v2.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfstate-v2.mdx new file mode 100644 index 0000000000..0de4f5cbd5 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfstate-v2.mdx @@ -0,0 +1,180 @@ +--- +page_title: tfstate/v2 Sentinel import +description: Use tfstate/v2 import to give Sentinel access to Terraform state. +source: terraform-docs-common +--- + +-> **Note:** This is documentation for the next version of the `tfstate` +Sentinel import, designed specifically for Terraform 0.12. This import requires +Terraform 0.12 or higher, and must currently be loaded by path, using an alias, +example: `import "tfstate/v2" as tfstate`. + +# tfstate/v2 Sentinel import + +The `tfstate/v2` import provides access to a Terraform state. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +The _state_ is the data that Terraform has recorded about a workspace at a +particular point in its lifecycle, usually after an apply. You can read more +general information about how Terraform uses state +[here](/terraform/language/state). + +-> **NOTE:** Since HCP Terraform currently only supports policy checks at plan +time, the usefulness of this import is somewhat limited, as it will usually give +you the state _prior_ to the plan the policy check is currently being run for. +Depending on your needs, you may find the +[`planned_values`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-planned_values-collection) collection in +`tfplan/v2` more useful, which will give you a _predicted_ state by applying +plan data to the data found here. The one exception to this rule is _data +sources_, which will always give up to date data here, as long as the data +source could be evaluated at plan time. + +The data in the `tfstate/v2` import is sourced from the JSON configuration file +that is generated by the [`terraform show -json`](/terraform/cli/commands/show#json-output) command. For more information on +the file format, see the [JSON Output Format](/terraform/internals/json-format) +page. + +## Import Overview + +The `tfstate/v2` import is structured as currently two _collections_, keyed in +resource address and output name, respectively. + + (tfstate/v2) + ├── terraform_version (string) + ├── resources + │ └── (indexed by address) + │ ├── address (string) + │ ├── module_address (string) + │ ├── mode (string) + │ ├── type (string) + │ ├── name (string) + │ ├── index (float (number) or string) + │ ├── provider_name (string) + │ ├── values (map) + │ ├── depends_on (list of strings) + │ ├── tainted (boolean) + │ └── deposed_key (string) + └── outputs + └── (indexed by name) + ├── name (string) + ├── sensitive (boolean) + └── value (value) + +The collections are: + +- [`resources`](#the-resources-collection) - The state of all resources across + all modules in the state. +- [`outputs`](#the-outputs-collection) - The state of all outputs from the root module in the state. + +These collections are specifically designed to be used with the +[`filter`](/sentinel/docs/language/collection-operations#filter-expression) +quantifier expression in Sentinel, so that one can collect a list of resources +to perform policy checks on without having to write complex module traversal. As +an example, the following code will return all `aws_instance` resource types +within the state, regardless of what module they are in: + + all_aws_instances = filter tfstate.resources as _, r { + r.mode is "managed" and + r.type is "aws_instance" + } + +You can add specific attributes to the filter to narrow the search, such as the +module address. The following code would return resources in a module named +`foo` only: + + all_aws_instances = filter tfstate.resources as _, r { + r.module_address is "module.foo" and + r.mode is "managed" and + r.type is "aws_instance" + } + +## The `terraform_version` Value + +The top-level `terraform_version` value in this import gives the Terraform +version that recorded the state. This can be used to do version validation. + + import "tfstate/v2" as tfstate + import "strings" + + v = strings.split(tfstate.terraform_version, ".") + version_major = int(v[1]) + version_minor = int(v[2]) + + main = rule { + version_major is 12 and version_minor >= 19 + } + +-> **NOTE:** The above example will give errors when working with pre-release +versions (example: `0.12.0beta1`). Future versions of this import will include +helpers to assist with processing versions that will account for these kinds of +exceptions. + +## The `resources` Collection + +The `resources` collection is a collection representing all of the resources in +the state, across all modules. + +This collection is indexed on the complete resource address as the key. + +An element in the collection has the following values: + +- `address` - The absolute resource address - also the key for the collection's + index. + +- `module_address` - The address portion of the absolute resource address. + +- `mode` - The resource mode, either `managed` (resources) or `data` (data + sources). + +- `type` - The resource type, example: `aws_instance` for `aws_instance.foo`. + +- `name` - The resource name, example: `foo` for `aws_instance.foo`. + +- `index` - The resource index. Can be either a number or a string. + +- `provider_name` - The name of the provider this resource belongs to. This + allows the provider to be interpreted unambiguously in the unusual situation + where a provider offers a resource type whose name does not start with its own + name, such as the `googlebeta` provider offering `google_compute_instance`. + + -> **Note:** Starting with Terraform 0.13, the `provider_name` field contains the + _full_ source address to the provider in the Terraform Registry. Example: + `registry.terraform.io/hashicorp/null` for the null provider. + +- `values` - An object (map) representation of the attribute values of the + resource, whose structure depends on the resource type schema. When accessing + proposed state through the [`planned_values`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-planned_values-collection) + collection of the tfplan/v2 import, unknown values will be omitted. + +- `depends_on` - The addresses of the resources that this resource depends on. + +- `tainted` - `true` if the resource has been explicitly marked as + [tainted](/terraform/cli/commands/taint) in the state. + +- `deposed_key` - Set if the resource has been marked deposed and will be + destroyed on the next apply. This matches the deposed field in the + [`resource_changes`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#the-resource_changes-collection) + collection in the [`tfplan/v2`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) import. + +## The `outputs` Collection + +The `outputs` collection is a collection of outputs from the root module of the +state. + +Note that no child modules are included in this output set, and there is no way +to fetch child module output values. This is to encourage the correct flow of +outputs to the recommended root consumption level. + +The collection is indexed on the output name, with the following fields: + +- `name`: The name of the output, also the collection key. +- `sensitive`: Whether or not the value was marked as + [sensitive](/terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output) + in + configuration. +- `value`: The value of the output. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfstate.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfstate.mdx new file mode 100644 index 0000000000..42e2590196 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/import-reference/tfstate.mdx @@ -0,0 +1,550 @@ +--- +page_title: tfstate Sentinel import +description: Use the tfstate import to give Sentinel access to Terraform state. +source: terraform-docs-common +--- + +# Import: tfstate + +~> **Warning:** The `tfstate` import is now deprecated and will be permanently removed in August 2025. We recommend that you start using the updated [tfstate/v2](/terraform/enterprise/policy-enforcement/import-reference/tfstate-v2) import as soon as possible to avoid disruptions. The `tfstate/v2` import offers improved functionality and is designed to better support your policy enforcement needs. + +The `tfstate` import provides access to the Terraform state. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +The _state_ is the data that Terraform has recorded about a workspace at a +particular point in its lifecycle, usually after an apply. You can read more +general information about how Terraform uses state [here][ref-tf-state]. + +[ref-tf-state]: /terraform/language/state + +-> **Note:** Since HCP Terraform currently only supports policy checks at plan +time, the usefulness of this import is somewhat limited, as it will usually give +you the state _prior_ to the plan the policy check is currently being run for. +Depending on your needs, you may find the +[`applied`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#value-applied) collection in `tfplan` more useful, +which will give you a _predicted_ state by applying plan data to the data found +here. The one exception to this rule is _data sources_, which will always give +up to date data here, as long as the data source could be evaluated at plan +time. + +## Namespace Overview + +The following is a tree view of the import namespace. For more detail on a +particular part of the namespace, see below. + +-> Note that the root-level alias keys shown here (`data`, `outputs`, `path`, +and `resources`) are shortcuts to a [module namespace](#namespace-module) scoped +to the root module. For more details, see the section on [root namespace +aliases](#root-namespace-aliases). + + tfstate + ├── module() (function) + │ └── (module namespace) + │ ├── path ([]string) + │ ├── data + │ │ └── TYPE.NAME[NUMBER] + │ │ ├── attr (map of keys) + │ │ ├── depends_on ([]string) + │ │ ├── id (string) + │ │ └── tainted (boolean) + │ ├── outputs (root module only in TF 0.12 or later) + │ │ └── NAME + │ │ ├── sensitive (bool) + │ │ ├── type (string) + │ │ └── value (value) + │ └── resources + │ └── TYPE.NAME[NUMBER] + │ ├── attr (map of keys) + │ ├── depends_on ([]string) + │ ├── id (string) + │ └── tainted (boolean) + │ + ├── module_paths ([][]string) + ├── terraform_version (string) + │ + ├── data (root module alias) + ├── outputs (root module alias) + ├── path (root module alias) + └── resources (root module alias) + +## Namespace: Root + +The root-level namespace consists of the values and functions documented below. + +In addition to this, the root-level `data`, `outputs`, `path`, and `resources` +keys alias to their corresponding namespaces or values within the [module +namespace](#namespace-module). + +### Function: `module()` + + module = func(ADDR) + +- **Return Type:** A [module namespace](#namespace-module). + +The `module()` function in the [root namespace](#namespace-root) returns the +[module namespace](#namespace-module) for a particular module address. + +The address must be a list and is the module address, split on the period (`.`), +excluding the root module. + +Hence, a module with an address of simply `foo` (or `root.foo`) would be +`["foo"]`, and a module within that (so address `foo.bar`) would be read as +`["foo", "bar"]`. + +[`null`][ref-null] is returned if a module address is invalid, or if the module +is not present in the state. + +[ref-null]: /sentinel/docs/language/spec#null + +As an example, given the following module block: + +```hcl +module "foo" { + # ... +} +``` + +If the module contained the following content: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if the resource was present in +the state: + +```python +import "tfstate" + +main = rule { tfstate.module(["foo"]).resources.null_resource.foo[0].attr.triggers.foo is "bar" } +``` + +### Value: `module_paths` + +- **Value Type:** List of a list of strings. + +The `module_paths` value within the [root namespace](#namespace-root) is a list +of all of the modules within the Terraform state at plan-time. + +Modules not present in the state will not be present here, even if they are +present in the configuration or the diff. + +This data is represented as a list of a list of strings, with the inner list +being the module address, split on the period (`.`). + +The root module is included in this list, represented as an empty inner list, as +long as it is present in state. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The value of `module_paths` would be: + + [ + [], + ["foo"], + ] + +And the following policy would evaluate to `true`: + +```python +import "tfstate" + +main = rule { tfstate.module_paths contains ["foo"] } +``` + +-> Note the above example only applies if the module is present in the state. + +#### Iterating Through Modules + +Iterating through all modules to find particular resources can be useful. This +[example][iterate-over-modules] shows how to use `module_paths` with the +[`module()` function](#function-module-) to find all resources of a +particular type from all modules using the `tfplan` import. By changing `tfplan` +in this function to `tfstate`, you could make a similar function find all +resources of a specific type in the current state. + +[iterate-over-modules]: /terraform/enterprise/policy-enforcement/sentinel#sentinel-imports + +### Value: `terraform_version` + +- **Value Type:** String. + +The `terraform_version` value within the [root namespace](#namespace-root) +represents the version of Terraform in use when the state was saved. This can be +used to enforce a specific version of Terraform in a policy check. + +As an example, the following policy would evaluate to `true` as long as the +state was made with a version of Terraform in the 0.11.x series, excluding any +pre-release versions (example: `-beta1` or `-rc1`): + +```python +import "tfstate" + +main = rule { tfstate.terraform_version matches "^0\\.11\\.\\d+$" } +``` + +-> **NOTE:** This value is also available via the [`tfplan`](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) +import, which will be more current when a policy check is run against a plan. +It's recommended you use the value in `tfplan` until HCP Terraform +supports policy checks in other stages of the workspace lifecycle. See the +[`terraform_version`][import-tfplan-terraform-version] reference within the +`tfplan` import for more details. + +[import-tfplan-terraform-version]: /terraform/enterprise/policy-enforcement/import-reference/tfplan-v2#value-terraform_version + +## Namespace: Module + +The **module namespace** can be loaded by calling +[`module()`](#function-module-) for a particular module. + +It can be used to load the following child namespaces, in addition to the values +documented below: + +- `data` - Loads the [resource namespace](#namespace-resources-data-sources), + filtered against data sources. +- `outputs` - Loads the [output namespace](#namespace-outputs), which supply the + outputs present in this module's state. Note that with Terraform 0.12 or + later, this value is only available for the root namespace. +- `resources` - Loads the [resource + namespace](#namespace-resources-data-sources), filtered against resources. + +### Root Namespace Aliases + +The root-level `data`, `outputs`, and `resources` keys both alias to their +corresponding namespaces within the module namespace, loaded for the root +module. They are the equivalent of running `module([]).KEY`. + +### Value: `path` + +- **Value Type:** List of strings. + +The `path` value within the [module namespace](#namespace-module) contains the +path of the module that the namespace represents. This is represented as a list +of strings. + +As an example, if the following module block was present within a Terraform +configuration: + +```hcl +module "foo" { + # ... +} +``` + +The following policy would evaluate to `true`, _only_ if the module was present +in the state: + +```python +import "tfstate" + +main = rule { tfstate.module(["foo"]).path contains "foo" } +``` + +## Namespace: Resources/Data Sources + +The **resource namespace** is a namespace _type_ that applies to both resources +(accessed by using the `resources` namespace key) and data sources (accessed +using the `data` namespace key). + +Accessing an individual resource or data source within each respective namespace +can be accomplished by specifying the type, name, and resource number (as if the +resource or data source had a `count` value in it) in the syntax +`[resources|data].TYPE.NAME[NUMBER]`. Note that NUMBER is always needed, even if +you did not use `count` in the resource. + +In addition, each of these namespace levels is a map, allowing you to filter +based on type and name. + +-> The (somewhat strange) notation here of `TYPE.NAME[NUMBER]` may imply that +the inner resource index map is actually a list, but it's not - using the square +bracket notation over the dotted notation (`TYPE.NAME.NUMBER`) is required here +as an identifier cannot start with number. + +Some examples of multi-level access are below: + +- To fetch all `aws_instance.foo` resource instances within the root module, you + can specify `tfstate.resources.aws_instance.foo`. This would then be indexed + by resource count index (`0`, `1`, `2`, and so on). Note that as mentioned + above, these elements must be accessed using square-bracket map notation (so + `[0]`, `[1]`, `[2]`, and so on) instead of dotted notation. +- To fetch all `aws_instance` resources within the root module, you can specify + `tfstate.resources.aws_instance`. This would be indexed from the names of + each resource (`foo`, `bar`, and so on), with each of those maps containing + instances indexed by resource count index as per above. +- To fetch all resources within the root module, irrespective of type, use + `tfstate.resources`. This is indexed by type, as shown above with + `tfstate.resources.aws_instance`, with names being the next level down, and so + on. + +Further explanation of the namespace will be in the context of resources. As +mentioned, when operating on data sources, use the same syntax, except with +`data` in place of `resources`. + +### Value: `attr` + +- **Value Type:** A string-keyed map of values. + +The `attr` value within the [resource +namespace](#namespace-resources-data-sources) is a direct mapping to the state +of the resource. + +The map is a complex representation of these values with data going as far down +as needed to represent any state values such as maps, lists, and sets. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true` if the resource was in the state: + +```python +import "tfstate" + +main = rule { tfstate.resources.null_resource.foo[0].attr.triggers.foo is "bar" } +``` + +### Value: `depends_on` + +- **Value Type:** A list of strings. + +The `depends_on` value within the [resource +namespace](#namespace-resources-data-sources) contains the dependencies for the +resource. + +This is a list of full resource addresses, relative to the module (example: +`null_resource.foo`). + +As an example, given the following resources: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} + +resource "null_resource" "bar" { + # ... + + depends_on = [ + "null_resource.foo", + ] +} +``` + +The following policy would evaluate to `true` if the resource was in the state: + +```python +import "tfstate" + +main = rule { tfstate.resources.null_resource.bar[0].depends_on contains "null_resource.foo" } +``` + +### Value: `id` + +- **Value Type:** String. + +The `id` value within the [resource +namespace](#namespace-resources-data-sources) contains the id of the resource. + +-> **NOTE:** The example below uses a _data source_ here because the +[`null_data_source`][ref-tf-null-data-source] data source gives a static ID, +which makes documenting the example easier. As previously mentioned, data +sources share the same namespace as resources, but need to be loaded with the +`data` key. For more information, see the +[synopsis](#namespace-resources-data-sources) for the namespace itself. + +[ref-tf-null-data-source]: https://registry.terraform.io/providers/hashicorp/null/latest/docs/data-sources/data_source + +As an example, given the following data source: + +```hcl +data "null_data_source" "foo" { + # ... +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +main = rule { tfstate.data.null_data_source.foo[0].id is "static" } +``` + +### Value: `tainted` + +- **Value Type:** Boolean. + +The `tainted` value within the [resource +namespace](#namespace-resources-data-sources) is `true` if the resource is +marked as tainted in Terraform state. + +As an example, given the following resource: + +```hcl +resource "null_resource" "foo" { + triggers = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`, if the resource was marked as +tainted in the state: + +```python +import "tfstate" + +main = rule { tfstate.resources.null_resource.foo[0].tainted } +``` + +## Namespace: Outputs + +The **output namespace** represents all of the outputs present within a +[module](#namespace-module). Outputs are present in a state if they were saved +during a previous apply, or if they were updated with known values during the +pre-plan refresh. + +**With Terraform 0.11 or earlier** this can be used to fetch both the outputs +of the root module, and the outputs of any module in the state below the root. +This makes it possible to see outputs that have not been threaded to the root +module. + +**With Terraform 0.12 or later** outputs are available in the top-level (root +module) namespace only and not accessible within submodules. + +This namespace is indexed by output name. + +### Value: `sensitive` + +- **Value Type:** Boolean. + +The `sensitive` value within the [output namespace](#namespace-outputs) is +`true` when the output has been [marked as sensitive][ref-tf-sensitive-outputs]. + +[ref-tf-sensitive-outputs]: /terraform/language/values/outputs#sensitive-suppressing-values-in-cli-output + +As an example, given the following output: + +```hcl +output "foo" { + sensitive = true + value = "bar" +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +main = rule { tfstate.outputs.foo.sensitive } +``` + +### Value: `type` + +- **Value Type:** String. + +The `type` value within the [output namespace](#namespace-outputs) gives the +output's type. This will be one of `string`, `list`, or `map`. These are +currently the only types available for outputs in Terraform. + +As an example, given the following output: + +```hcl +output "string" { + value = "foo" +} + +output "list" { + value = [ + "foo", + "bar", + ] +} + +output "map" { + value = { + foo = "bar" + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +type_string = rule { tfstate.outputs.string.type is "string" } +type_list = rule { tfstate.outputs.list.type is "list" } +type_map = rule { tfstate.outputs.map.type is "map" } + +main = rule { type_string and type_list and type_map } +``` + +### Value: `value` + +- **Value Type:** String, list, or map. + +The `value` value within the [output namespace](#namespace-outputs) is the value +of the output in question. + +Note that the only valid primitive output type in Terraform is currently a +string, which means that any int, float, or boolean value will need to be +converted before it can be used in comparison. This does not apply to primitives +within maps and lists, which will be their original types. + +As an example, given the following output blocks: + +```hcl +output "foo" { + value = "bar" +} + +output "number" { + value = "42" +} + +output "map" { + value = { + foo = "bar" + number = 42 + } +} +``` + +The following policy would evaluate to `true`: + +```python +import "tfstate" + +value_foo = rule { tfstate.outputs.foo.value is "bar" } +value_number = rule { int(tfstate.outputs.number.value) is 42 } +value_map_string = rule { tfstate.outputs.map.value["foo"] is "bar" } +value_map_int = rule { tfstate.outputs.map.value["number"] is 42 } + +main = rule { value_foo and value_number and value_map_string and value_map_int } +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/index.mdx new file mode 100644 index 0000000000..7a53f5ced2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/index.mdx @@ -0,0 +1,50 @@ +--- +page_title: Terraform Enterprise policy enforcement overview +description: >- + Policies are rules for provisioning infrastructure that you can use to + validate Terraform plans. Learn how to use Sentinel and OPA to enforce + policies. +source: terraform-docs-common +--- + +# HCP Terraform policy enforcement overview + +This topic provides overview information about policies in HCP Terraform. Policies are rules for Terraform runs that let you validate that Terraform plans comply with security rules and best practices. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +> **Hands-on:** Try the [Enforce Policy with Sentinel](/terraform/tutorials/policy) and [Detect Infrastructure Drift and Enforce OPA Policies](/terraform/tutorials/cloud/drift-and-opa) tutorials. + +## Introduction + +You can implement policies that check for any number of conditions, such as whether infrastructure configuration adheres to security standards or best practices. For example, you may want to write a policy to check whether Terraform plans to deploy production infrastructure to the correct region. + +You can also use policies to enforce standards for your organization’s workflows. For example, you could write a policy to prevent new infrastructure deployments on Fridays, reducing the risk of production incidents outside of your team’s working hours. + +## Workflow + +The following workflow describes how to create and manage policies manually. + +### Define policy + +You can use either the Sentinel or OPA framework to create custom policies. You can also copy pre-written Sentinel policies created and maintained by HashiCorp. + +### Create and apply policy sets + +Policy sets are collections of policies you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces in your organization. For each run in the selected workspaces, HCP Terraform checks the Terraform plan against the policy set. + +You can also exclude specific workspaces from global or project-scoped policy sets. HCP Terraform won't enforce a policy set's policies on any runs in an excluded workspace. For example, if you attach a policy set to a project and then exclude one of the project's workspaces from that policy set, HCP Terraform will not enforce the policy set on the excluded workspace. + +You can create policy sets from the [user interface](/terraform/enterprise/policy-enforcement/manage-policy-sets#create-policy-sets), the API, or by connecting HCP Terraform to your version control system. A policy set can only contain policies written in a single policy framework, but you can add Sentinel or OPA policy sets to the same workspace. + +Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. + +### Review policy results + +The HCP Terraform UI displays policy results for each policy set you apply to the workspace. Depending on their [enforcement level](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels), failed policies can stop the run. You can override failed policies with the right permissions. + +Refer to [Policy Results](/terraform/enterprise/policy-enforcement/view-results) for details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx new file mode 100644 index 0000000000..c64a99593a --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/index.mdx @@ -0,0 +1,227 @@ +--- +page_title: Manage policies and policy sets in Terraform Enterprise +description: >- + Learn how to create and manage policies and policy sets in Terraform + Enterprise. +source: terraform-docs-common +--- + +# Manage policies and policy sets in HCP Terraform + +Policies are rules that HCP Terraform enforces on Terraform runs. You can define policies using either the [Sentinel](/terraform/enterprise/policy-enforcement/sentinel) or [Open Policy Agent (OPA)](/terraform/enterprise/policy-enforcement/opa) policy-as-code frameworks. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policy sets are collections of policies you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces in your organization. For each run in the applicable workspaces, HCP Terraform checks the Terraform plan against the policy set. Depending on the [enforcement level](#policy-enforcement-levels), failed policies can stop a run in a workspace. If you do not want to enforce a policy set on a specific workspace, you can exclude the workspace from that set. + +## Permissions + +To view and manage policies and policy sets, you must have [manage policy permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-policies) for your organization. + +## Policy checks versus policy evaluations + +Policy checks and evaluations can access different types of data and enable slightly different workflows. + +### Policy checks + +Only Sentinel policies can run as policy checks. Checks can access cost estimation data but can only use the latest version of Sentinel. + +~> **Warning:** Policy checks are deprecated and will be permanently removed in August 2025. We recommend that you start using policy evaluations to avoid disruptions. + +### 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. + +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: + +- Enable overrides for soft-mandatory and hard-mandatory policies, letting any user with [Manage Policy Overrides permission](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) proceed with a run in the event of policy failure. +- Select a specific Sentinel runtime version for the policy set. + +Policy evaluations **cannot** access cost estimation data, so use policy checks if your policies rely on cost estimates. + +~> **Tip:** Sentinel runtime version pinning is supported only for Sentinel 0.23.1 and above, as well as HCP Terraform agent versions 1.13.1 and above + +## Policy enforcement levels + +You can set an enforcement level for each policy that determines what happens when a Terraform plan does not pass the policy rule. Sentinel and OPA policies have different enforcement levels available. + +### Sentinel + +Sentinel provides three policy enforcement levels: + +- **advisory:** Failed policies never interrupt the run. They provide information about policy check failures in the UI. +- **soft mandatory:** Failed policies stop the run, but any user with [Manage Policy Overrides permission](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) can override these failures and allow the run to complete. +- **hard mandatory:** Failed policies stop the run. Terraform does not apply runs with failed **hard mandatory** policies until a user fixes the issue that caused the failure. + +### OPA + +OPA provides two policy enforcement levels: + +- **advisory** Failed policies never interrupt the run. They provide information about policy failures in the UI. +- **mandatory:** Failed policies stop the run, but any user with [Manage Policy Overrides permission](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) can override these failures and allow the run to complete. + +## Policy publishing workflows + +You can create policies and policy sets for your HCP Terraform organization in one of three ways: + +- **HCP Terraform web UI:** Add individually-managed policies manually in the HCP Terraform UI, and store your policy code in HCP Terraform. This workflow is ideal for initial experimentation with policy enforcement, but we do not recommend it for organizations with large numbers of policies. +- **Version control:** Connect HCP Terraform to a version control repository containing a policy set. When you push changes to the repository, HCP Terraform automatically uses the updated policy set. +- **Automated:** Push versions of policy sets to HCP Terraform with the [HCP Terraform Policy Sets API](/terraform/enterprise/api-docs/policy-sets#create-a-policy-set-version) or the `tfe` provider [`tfe_policy_set`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/policy_set) resource. This workflow is ideal for automated Continuous Integration and Deployment (CI/CD) pipelines. + +### Manage individual policies in the web UI + +You can add policies directly to HCP Terraform using the web UI. This process requires you to paste completed, valid Sentinel or Rego code into the UI. We recommend validating your policy code before adding it to HCP Terraform. + +#### Add managed policies + +To add an individually managed policy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to add policies to. +2. Choose **Settings** from the sidebar, then **Policies**. A list of managed policies in HCP Terraform appears. Each policy designates its policy framework (Sentinel or OPA) and associated policy sets. +3. Click **Create a new policy**. +4. Choose the **Policy framework** you want to use. You can only create a policy set from policies written using the same framework. You cannot change the framework type after you create the policy. +5. Complete the following fields to define the policy: + - **Policy Name:** Add a name containing letters, numbers, `-`, and `_`. HCP Terraform displays this name in the UI. The name must be unique within your organization. + - **Description:** Describe the policy’s purpose. The description supports Markdown rendering, and HCP Terraform displays this text in the UI. + - **Enforcement mode:** Choose whether this policy can stop Terraform runs and whether users can override it. Refer to [policy enforcement levels](#policy-enforcement-levels) for more details. + - **(OPA Only) Query:** Write a query to identify a specific policy rule within your rego code. HCP Terraform uses this query to determine the result of the policy. The query is typically a combination of the policy package name and rule name, such as `terraform.deny`. The result of this query must be an array. The policy passes when the array is empty. + - **Policy code**: Paste the code for the policy: either Sentinel code or Rego code for OPA policies. The UI provides syntax highlighting for the policy language. + - **(Optional) Policy sets:** Select one or more existing managed policy sets where you want to add the new policy. You can only select policy sets compatible with the chosen policy set framework. If there are no policy sets available, you can [create a new one](#create-policy-sets). + +The policy is now available in the HCP Terraform UI for you to edit and add to one or more policy sets. + +#### Edit managed policies + +To edit a managed policy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to edit policies for. +2. Choose **Settings** from the sidebar, then **Policies**. +3. Click the policy you want to edit to go to its details page. +4. Edit the policy's fields and then click **Update policy**. + +#### Delete managed policies + +~> **Warning:** Deleting a policy that applies to an active run causes that run’s policy evaluation stage to error. We recommend warning other members of your organization before you delete widely used policies. + +You can not restore policies after deletion. You must manually re-add them to HCP Terraform. You may want to save the policy code in a separate location before you delete the policy. + +To delete a managed policy: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to delete a policy in. +2. Choose **Settings** from the sidebar, then **Policies**. +3. Click the policy you want to delete to go to its details page. +4. Click **Delete policy** and then click **Yes, delete policy** to confirm. + +The policy no longer appears in HCP Terraform and in any associated policy sets. + +## Manage policy sets + +Policy sets are collections of policies that you can apply globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. + +To view and manage policy sets, go to the **Policy Sets** section of your organization’s settings. This page contains all of the policy sets available in the organization, including those added through the API. + +The way you set up and configure a new policy set depends on your workflow and where you store policies. + +- For [managed policies](#managed-policies), you use the UI to create a policy set and add managed policies. +- For policy sets in a version control system, you use the UI to create a policy set connected to that repository. HCP Terraform automatically refreshes the policy set when you change relevant files in that repository. Version control policy sets have specific organization and formatting requirements. Refer to [Sentinel VCS Repositories](/terraform/enterprise/policy-enforcement/sentinel/vcs) and [OPA VCS Repositories](/terraform/enterprise/policy-enforcement/opa/vcs) for details. +- For automated workflows like continuous deployment, you can use the UI to create an empty policy set and then use the [Policy Sets API](/terraform/enterprise/api-docs/policy-sets) to add policies. You can also use the API or the [`tfe` provider (Sentinel Only)](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/policy_set) to add an entire, packaged policy set. + +### Create policy sets + +To create a policy set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to create a policy set in. + +2. Choose **Settings** from the sidebar, then **Policies**. + +3. Click **Connect a new policy set**. + +4. Choose your workflow. + - For managed policies, click **create a policy set with individually managed policies**. HCP Terraform shows a form to create a policy set and add individually managed policies. + - For version control policies, choose a version control provider and then select the repository with your policy set. HCP Terraform shows a form to create a policy set connected to that repository. + - For automated workflows, click **No VCS Connection**. HCP Terraform shows a form to create an empty policy set. You can use the API to add policies to this empty policy set later. + +5. Choose a **Policy framework** for the policies you want to add. A policy set can only contain policies that use the same framework (OPA or Sentinel). You cannot change a policy set's framework type after creation. + +6. Choose a policy set scope: + - **Policies enforced globally:** HCP Terraform automatically enforces this global policy set on all of an organization's existing and future workspaces. + - **Policies enforced on selected projects and workspaces:** Use the text fields to find and select the workspaces and projects to enforce this policy set on. This affects all current and future workspaces for any chosen projects. + +7. **(Optional)** Add **Policy exclusions** for this policy set. Specify any workspaces in the policy set's scope that HCP Terraform will not enforce this policy set on. + +8. **(Sentinel Only)** Choose a policy set type: + - **Standard:** This is the default workflow. A Sentinel policy set uses a [policy check](#policy-checks) in HCP Terraform and lets you access cost estimation data. + - **Agent:** A Sentinel policy set uses a [policy evaluation](#policy-evaluations) in HCP Terraform. This lets you enable policy overrides and enforce a Sentinel runtime version + +9. **(OPA Only)** Select a **Runtime version** for this policy set. + +10. **(OPA Only)** Allow **Overrides**, which enables users with override policy permissions to apply plans that have [mandatory policy](#policy-enforcement-levels) failures. + +11. **(VCS Only)** Optionally specify the **VCS branch** within your VCS repository where HCP Terraform should import new versions of policies. If you do not set this field, HCP Terraform uses your selected VCS repository's default branch. + +12. **(VCS Only)** Specify where your policy set files live using the **Policies path**. This lets you maintain multiple policy sets within a single repository. Use a relative path from your root directory to the directory that contains either the `sentinel.hcl` (Sentinel) or `policies.hcl` (OPA) configuration files. If you do not set this field, HCP Terraform uses the repository's root directory. + +13. **(Managed Policies Only)** Select managed **Policies** to add to the policy set. You can only add policies written with the same policy framework you selected for this set. + +14. Choose a descriptive and unique **Name** for the policy set. You can use any combination of letters, numbers, `-`, and `_`. + +15. Write an optional **Description** that tells other users about the purpose of the policy set and what it contains. + +### Edit policy sets + +To edit a policy set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to edit a policy set in. +2. Choose **Settings** from the sidebar, then **Policies**. +3. Click the policy set you want to edit to go to its settings page. +4. Adjust the settings and click **Update policy set**. + +### Evaluate a policy runtime upgrade + +You can validate that changing a policy runtime version does not introduce any breaking changes. + +To perform a policy evaluation: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to your organization. +2. Choose **Settings** from the sidebar, then **Policies** in your organization’s settings. +3. Click the policy set you want to upgrade. +4. Click the **Evaluate** tab. +5. Select the **Runtime version** you wish to upgrade to. +6. Select a **Workspace** to test the policy and upgraded version against. +7. Click **Evaluate**. + +HCP Terraform will execute the policy set using the specified version and the latest plan data for the selected workspace. It will display the evaluation results. If the evaluation returns a `Failed` status, inspect the JSON output to determine whether the issue is related to a non-compliant resource or is due to a syntax issue. +If the evaluation results in an error, check that the policy configuration is valid. + +### Delete policy sets + +~> **Warning:** Deleting a policy set that applies to an active run causes that run’s policy evaluation stage to error. We recommend warning other members of your organization before you delete widely used policy sets. + +You can not restore policy sets after deletion. You must manually re-add them to HCP Terraform. + +To delete a policy set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to delete a policy set in. +2. Choose **Settings** from the sidebar, then **Policies** in your organization’s settings. +3. Click the policy set you want to delete to go to its details page. +4. Click **Delete policy** and then click **Yes, delete policy set** to confirm. + +The policy set no longer appears on the UI and HCP Terraform no longer applies it to any workspaces. For managed policy sets, all of the individual policies are still available in HCP Terraform. You must delete each policy individually to remove it from your organization. + +### (Sentinel only) Sentinel parameters + +[Sentinel parameters](/sentinel/docs/language/parameters) are a list of key/value pairs that HCP Terraform sends to the Sentinel runtime when performing policy checks on workspaces. If the value parses as JSON, HCP Terraform sends it to Sentinel as the corresponding type (string, boolean, integer, map, or list). If the value fails JSON validation, HCP Terraform sends it as a string. + +You can set Sentinel parameters when you [edit a policy set](#edit-policy-sets). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/opa-vcs.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/opa-vcs.mdx new file mode 100644 index 0000000000..adb5027c99 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/opa-vcs.mdx @@ -0,0 +1,48 @@ +--- +page_title: Configure an OPA policy set with a VCS repository +description: Use a VCS repository to configure an OPA policy set in Terraform Enterprise. +source: terraform-docs-common +--- + +# Configure an OPA policy set with a VCS repository + +To enable policy enforcement, you must group OPA policies into policy sets and apply those policy sets globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. + +> **Hands-on:** Try the [Detect Infrastructure Drift and Enforce OPA Policies](/terraform/tutorials/cloud/drift-and-opa) tutorial. + +One way to create policy sets is by connecting HCP Terraform to a version control repository. When you push changes to the repository, HCP Terraform automatically uses the updated policy set. Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for more details. + +An OPA policy set repository contains a HashiCorp Configuration Language (HCL) configuration file and policy files. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Configuration File + +The root directory of your policy set repository must contain a configuration file named either `policies.hcl` or `policies.json`. Policy enforcement supports both HCL and the JSON variant of HCL syntax. +The configuration file contains one or more `policy` blocks that define each policy in the policy set. Unlike Sentinel, OPA policies do not need to be in separate files. You use an [OPA query](/terraform/enterprise/policy-enforcement/opa#opa-query) to identify each policy rule. + +The following example uses a query to define a policy named `policy1`. This query may evaluate across multiple files, or a single file. + +```hcl +policy "policy1" { + query = "data.terraform.policy1.deny" +} +``` + +Optionally, you can also provide a `description` and an `enforcement_level` property. If you do not specify an enforcement level, HCP Terraform uses `advisory`, meaning policy failures produce warnings but do not block Terraform runs. Refer to [Policy Enforcement Levels](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels) for more details. + +```hcl +policy "policy1" { + query = "data.terraform.policy1.deny" + enforcement_level = "mandatory" + description = "policy1 description" +} +``` + +## Policy Code Files + +All Rego policy files must end with `.rego` and exist in the local GitHub repository for the policy set. You can store them in separate directories from the configuration file. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs.mdx new file mode 100644 index 0000000000..3bb8a81579 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs.mdx @@ -0,0 +1,139 @@ +--- +page_title: Configure a Sentinel policy set with a VCS repository +description: >- + Use a VCS repository to configure a Sentinel policy set in Terraform + Enterprise. +source: terraform-docs-common +--- + +# Configure a Sentinel policy set with a VCS repository + +To enable policy enforcement, you must group Sentinel policies into policy sets. You can then apply those policy sets globally or to specific [projects](/terraform/enterprise/projects/manage) and workspaces. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +One way to create policy sets is by connecting HCP Terraform to a version control repository. When you push changes to the repository, HCP Terraform automatically uses the updated policy set. Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for more details. + +A Sentinel policy set repository contains a Sentinel configuration file, policy files, and module files. + +## Configuration File + +Your repository must contain a configuration file named `sentinel.hcl` that defines the following features of the policy set: + +- Each policy included in the set. The policy name must match the names of individual [policy code files](#policy-code-files) exactly. HCP Terraform ignores policy files in the repository that are not listed in the configuration file. For each policy, the configuration file must designate the policy’s [enforcement level](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels) and [source](#policy-source). +- [Terraform modules](#modules) that policies in the set need to access. + +The following example shows a portion of a `sentinel.hcl` configuration file that defines a policy named `terraform-maintenance-windows`. The policy has a `hard-mandatory` enforcement level, meaning that it can block Terraform runs when it fails and users cannot override it. + +```hcl +policy "terraform-maintenance-windows" { + source = "./terraform-maintenance-windows.sentinel" + enforcement_level = "hard-mandatory" +} +``` + +To configure a module, add a `module` entry to your `sentinel.hcl` file. The following example adds a module called `timezone`. + +```hcl +module "timezone" { + source = "./modules/timezone.sentinel" +} +``` + +The repositories for [policy libraries on the Terraform Registry](https://registry.terraform.io/browse/policies) contain more examples. + +## Policy Code Files + +Define each Sentinel policy in a separate file within your repository. All local policy files must reside in the same directory as the `sentinel.hcl` configuration file and end with the `.sentinel` suffix. + +### Policy Source + +A policy's `source` field can either reference a file within the policy repository, or it can reference a remote source. For example, the configuration could reference a policy from HashiCorp's [foundational policies library](https://github.com/hashicorp/terraform-foundational-policies-library). Sentinel only supports HTTP and HTTPS remote sources. + +To specify a local source, prefix the `source` with a `./`, or `../`. The following example shows how to reference a local source policy called `terraform-maintenance-windows.sentinel`. + +```hcl +policy "terraform-maintenance-windows" { + source = "./terraform-maintenance-windows.sentinel" + enforcement_level = "hard-mandatory" +} +``` + +To specify a remote source, supply the URL as the `source`. The following example references a policy from HashiCorp's foundational policies library. + +```hcl +policy "deny-public-ssh-nsg-rules" { + source = "https://registry.terraform.io/v2/policies/hashicorp/azure-networking-terraform/1.0.2/policy/deny-public-ssh-nsg-rules.sentinel?checksum=sha256:75c95bf1d6eb48153cb31f15c49c237bf7829549beebe20effa07bcdd3f3cb74" + enforcement_level = "advisory" +} +``` + +For GitHub, you must use the URL of the raw policy content. Other URL types cause HCP Terraform to error when checking the policy. For example, do not use `https://github.com/hashicorp/policy-library-azure-networking-terraform/blob/main/policies/deny-public-ssh-nsg-rules/deny-public-ssh-nsg-rules.sentinel`. + +To access the raw URL, open the Sentinel file in your Github repository, right-click **Raw** on the top right of the page, and save the link address. + +### Example Policy + +The following example policy uses the `time` and `tfrun` imports and a custom `timezone` module to do the following tasks: + +1. Load the time when the Terraform run occurred +2. Convert the loaded time with the correct offset using the [Timezone API](https://timezoneapi.io/) +3. Verify that the provisioning operation occurs only on a specific day + +The example policy also uses a [rule expression](/sentinel/docs/language/spec#rule-expressions) with the `when` predicate. If the value of `tfrun.workspace.auto_apply` is false, the rule is not evaluated and returns true. + +Finally, the example uses parameters to facilitate module reuse within Terraform. Refer to the [Sentinel parameter documentation](/sentinel/docs/language/parameters) for details. + +```hcl +import "time" +import "tfrun" +import "timezone" + +param token default "WbNKULOBheqV" +param maintenance_days default ["Friday", "Saturday", "Sunday"] +param timezone_id default "America/Los_Angeles" + +tfrun_created_at = time.load(tfrun.created_at) + +supported_maintenance_day = rule when tfrun.workspace.auto_apply is true { + tfrun_created_at.add(time.hour * timezone.offset(timezone_id, token)).weekday_name in maintenance_days +} + +main = rule { + supported_maintenance_day +} +``` + +To expand the policy, you could use the [time.hour](/sentinel/docs/imports/time#time-hour) function to also restrict provisioning to specific times of day. + +## Modules + +HCP Terraform supports [Sentinel modules](/sentinel/docs/extending/modules). Modules let you write reusable policy code that you can import and use within several policies at once. + +You can store modules locally or retrieve them from a remote HTTP or HTTPS source. + +-> **Note:** We recommend reviewing [Sentinel runtime's modules documentation](/sentinel/docs/extending/modules) to learn how to use modules within Sentinel. However, the configuration examples in the runtime documentation are relevant to the Sentinel CLI and not HCP Terraform. + +The following example module loads the code at `./modules/timezone.sentinel` relative to the policy set working directory. Other modules can access this code with the statement `import "timezone"`. + +```hcl +import "http" +import "json" +import "decimal" + +httpGet = func(id, token){ + uri = "https://timezoneapi.io/api/timezone/?" + id + "&token=" + token + request = http.get(uri) + return json.unmarshal(request.body) +} + +offset = func(id, token) { + tz = httpGet(id, token) + offset = decimal.new(tz.data.datetime.offset_hours).int + return offset +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/prewritten-library.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/prewritten-library.mdx new file mode 100644 index 0000000000..fc023061da --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/prewritten-library.mdx @@ -0,0 +1,26 @@ +--- +page_title: Pre-written policy library +description: >- + HashiCorp authors and maintains a library of pre-written Sentinel policies + that enforce CIS and other compliance standards. Learn about the available + pre-written policies. +source: terraform-docs-common +--- + +# Pre-written policy library reference + +This topic provides reference information about the Sentinel policy libraries that HashiCorp authors and maintains. For instructions on how to run the policy libraries, refer to [Run pre-written Sentinel policies ](/terraform/enterprise/policy-enforcement/prewritten-sentinel). + +## Center for Internet Security (CIS) + +The Center for Internet Security (CIS) is a non-profit organization that publishes standards for configuring secure cloud services. Refer to the [CIS website](https://www.cisecurity.org) for additional information. + +HashiCorp publishes pre-written policies that support the following CIS benchmarks. + +### AWS + +- Amazon Web Services Foundations version 1.2. Refer to the [AWS documentation](https://docs.aws.amazon.com/securityhub/latest/userguide/cis-aws-foundations-benchmark.html#cis1v2-standard) for additional information about this version. +- Amazon Web Services Foundations version 1.4. Refer to the [AWS documentation](https://docs.aws.amazon.com/securityhub/latest/userguide/cis-aws-foundations-benchmark.html#cis1v4-standard) for additional information about this version. +- Amazon Web Services Foundations version 3.0. Refer to the [AWS documentation](https://docs.aws.amazon.com/securityhub/latest/userguide/cis-aws-foundations-benchmark.html#cis3v0-standard) for additional information about this version. + +Refer to the [CIS policy set for AWS GitHub repository](https://github.com/hashicorp/policy-library-CIS-Policy-Set-for-AWS-Terraform) for details about these policies. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/prewritten-sentinel.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/prewritten-sentinel.mdx new file mode 100644 index 0000000000..ea73b949a1 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/prewritten-sentinel.mdx @@ -0,0 +1,133 @@ +--- +page_title: Run pre-written Sentinel policies +description: >- + Learn how to download and install pre-written Sentinel policies created and + maintained by HashiCorp. +source: terraform-docs-common +--- + +# Run pre-written Sentinel policies + +This topic describes how to run Sentinel policies created and maintained by HashiCorp. For instructions about how to create your own custom Sentinel policies, refer to [Define custom Sentinel policies](/terraform/enterprise/policy-enforcement/define-policies/custom-sentinel). + +## Overview + +Pre-written Sentinel policy libraries streamline your compliance processes and enhance security across your infrastructure. HashiCorp's ready-to-use policies can help you enforce best practices and security standards across your AWS environment. + +Complete the following steps to implement pre-written Sentinel policies in your workspaces: + +1. Obtain the policies you want to implement. Download policies directly into your repository or create a fork of the HashiCorp repositories. Alternatively, you can add the Terraform module to your configuration, which acquires the policies and connects them to your workspaces in a single step. +2. Connect policies to your workspace. After you download policies or fork policy repositories, you must connect them to your HCP Terraform or Terraform Enterprise workspaces. + +Refer to the [Sentinel documentation](/sentinel/docs) for information about the Sentinel language. + +## Requirements + +You must use one of the following Terraform applications: + +- HCP Terraform +- Terraform Enterprise v202406-1 or newer + +### Permissions + +To create new policy sets and policies, your HCP Terraform or Terraform Enterprise user account must either be a member of the owners team or have the **Manage Policies** organization-level permissions enabled. Refer to the following topics for additional information: + +- [Organization owners](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) +- [Manage policies](/terraform/enterprise/users-teams-organizations/permissions#manage-policies) + +### Version control system + +You must have a GitHub account connected to HCP Terraform or Terraform Enterprise to manually connect policy sets to your workspaces. Refer to [Connecting VCS Providers](/terraform/enterprise/vcs) for instructions. + +## Get policies + +Refer to the [pre-written policy library reference](/terraform/enterprise/policy-enforcement/prewritten-library) for a complete list of available policy sets. You can also [browse the registry](https://registry.terraform.io/search/policies?q=Pre-written) to discover additional policy libraries. + +Use one of the following methods to get pre-written policies: + +- **Download policies from the registry**: Use this method if you want to assemble custom policy sets without customizing policies. +- **Fork the HashiCorp policy GitHub repository**: Use this method if you intend to customize the policies. +- **Add the Terraform module to your configuration**: Use this method to implement specific versions of the policies as-is. This method also connects the policies to workspaces in the Terraform configuration file instead of connecting them as a separate step. + + + + + +Complete the following steps to download policies from the registry and apply them directly to your workspaces. + +1. Browse the policy libraries available in the [Terraform registry](https://registry.terraform.io/search/policies?q=Pre-written). +2. Click on a policy library and click **Choose policies**. +3. Select the policies you want to implement. The registry generates code in the **USAGE INSTRUCTIONS** box. +4. Click **Copy Code Snippet** to copy the code to your clipboard. +5. Create a GitHub repository to store the policies and the policy set configuration file. +6. Create a file called `sentinel.hcl` in the repository. +7. Paste the code from your clipboard into `sentinel.hcl` and commit your changes. +8. Complete the instructions for [connecting the policies to your workspace](#connect-policies-to-your-workspace). + + + + +Create a fork of the repository containing the policies you want to implement. Refer to the [GitHub documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) for instructions on how to create a fork. + +The following repositories are available: + +- [policy-library-CIS-Policy-Set-for-AWS-Terraform](https://github.com/hashicorp/policy-library-CIS-Policy-Set-for-AWS-Terraform) + +HashiCorp Sentinel policy libraries include a `sentinel.hcl` file. The file defines an example policy set using the policies included in the library. Modify the file to customize your policy set. Refer to [Sentinel Policy Set VCS Repositories](/terraform/enterprise/policy-enforcement/manage-policy-sets/sentinel-vcs) for additional information. + +After forking the repository, complete the instructions for [connecting the policies to your workspace](#connect-policies-to-your-workspace). + + + + +This method enables you to connect the policies to workspaces in the Terraform configuration file. As a result, you can skip the instructions described in [Connect policies to your workspaces](#connect-policies-to-your-workspaces). + +1. Go to the [module in the Terraform registry](https://registry.terraform.io/modules/hashicorp/CIS-Policy-Set/AWS/latest) and copy the code generated in the **Provision Instructions** tile. + +2. Add the `module` block to your Terraform configuration and define the following arguments: + + - `source`: Specify the path to the module you downloaded. + - `tfe_organization`: Specify the name of your organization on Terraform Enterprise or HCP Terraform. + - `policy_set_workspace_names`: Specify a list of workspace names that you want to apply the policies to. + + The following example configuration applies invokes the module for `target_workspace_1`: + + ```hcl + module "cis_v1-2-0_policies" { + source = "../prewritten-policy" + name = "cis-1-2-0" + tfe_organization = "" + policy_set_workspace_names = ["target_workspace_1"] + } + ``` + +3. Run `terraform plan` to view the plan. + +4. Run `terraform apply` to apply the changes. After running the command, Terraform will evaluate Sentinel policies for each following run of the workspaces you specified. + + + + +## Connect policies to your workspace + +Skip this step if you [added the Terraform module](#add-the-terraform-module-to-your-configuration) to your configuration. When you use the module, the `policy_set_workspace_names` argument instructs Terraform to connect the policies to the HCP Terraform workspaces specified in the configuration. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization with workspaces you want to connect policies to. +2. Choose **Settings** from the sidebar. +3. Click **Policy Sets** and click **Connect a new policy set**. +4. Click the **Version control provider (VCS)** tile. +5. Enable the **Sentinel** option as the policy framework. +6. Specify a name and description for the set. +7. Configure any additional options for the policy set and click **Next**. +8. Choose the GitHub connection type, then choose the repository you created in [Set up a repository for the policies](#set-up-a-repository-for-the-policies). +9. If the `sentinel.hcl` policy set file is stored in a subfolder, specify the path to the file in the **Policies path** field. The default is the root directory. +10. If you want to apply updated policy sets to the workspace from a specific branch, specify the name in the **VCS branch** field. The default is the default branch configured for the repository. +11. Click **Next** and specify any additional parameters you want to pass to the Sentinel runtime and click **Connect policy set** to finish applying the policies to the workspace. + +Run a plan in the workspace to trigger the connected policies. Refer to [Start a Terraform run](/terraform/enterprise/run/remote-operations#starting-runs) for additional information. + +## Next steps + +- Group your policies into sets and apply them to your workspaces. Refer to [Create policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets#create-policy-sets) for additional information. +- View results and address Terraform runs that do not comply with your policies. Refer to [View results](/terraform/enterprise/policy-enforcement/view-results) for additional information. +- You can also view Sentinel policy results in JSON format. Refer to [View Sentinel JSON results](/terraform/enterprise/policy-enforcement/view-results/json) for additional information. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/test-sentinel.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/test-sentinel.mdx new file mode 100644 index 0000000000..91be1391fe --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/test-sentinel.mdx @@ -0,0 +1,277 @@ +--- +page_title: Generate mock Sentinel data with Terraform Enterprise +description: >- + Learn how to generate mock Sentinel data to test your policies with Terraform + Enterprise. +source: terraform-docs-common +--- + +# Generate mock Sentinel data with Terraform + +We recommend that you test your Sentinel policies extensively before deploying +them within HCP Terraform. An important part of this process is mocking +the data that you wish your policies to operate on. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Due to the highly variable structure of data that can be produced by an +individual Terraform configuration, HCP Terraform provides the ability to +generate mock data from existing configurations. This can be used to create +sample data for a new policy, or data to reproduce issues in an existing one. + +Testing policies is done using the [Sentinel +CLI](/sentinel/docs/commands). More general information on +testing Sentinel policies can be found in the [Testing +section](/sentinel/docs/writing/testing) of the [Sentinel +runtime documentation](https://docs.hashicorp.com/sentinel). + +~> **Be careful!** Mock data generated by HCP Terraform directly exposes any +and all data within the configuration, plan, and state. Terraform attempts to +scrub sensitive data from these mocks, but we do not guarantee 100% accuracy. +Treat this data with care, and avoid generating mocks with live sensitive data +when possible. Access to this information requires [permission to download +Sentinel mocks](/terraform/enterprise/users-teams-organizations/permissions) for the +workspace where the data was generated. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Generating Mock Data Using the UI + +Mock data can be generated using the UI by expanding the plan status section of +the run page, and clicking on the **Download Sentinel mocks** button. + +![sentinel mock generate ui](/img/docs/download-mocks.png) + +For more information on creating a run, see the +[Terraform Runs and Remote Operations](/terraform/enterprise/run/remote-operations) section of the docs. + +If the button is not visible, then the plan is ineligible for mock generation or +the user doesn't have the necessary permissions. See [Mock Data +Availability](#mock-data-availability) for more details. + +## Generating Mock Data Using the API + +Mock data can also be created with the [Plan Export +API](/terraform/enterprise/api-docs/plan-exports). + +Multiple steps are required for mock generation. The export process is +asynchronous, so you must monitor the request to know when the data is generated +and available for download. + +1. Get the plan ID for the run that you want to generate the mock for by + [getting the run details](/terraform/enterprise/api-docs/run#get-run-details). + Look for the `id` of the `plan` object within the `relationships` section of + the return data. +2. [Request a plan + export](/terraform/enterprise/api-docs/plan-exports#create-a-plan-export) using the + discovered plan ID. Supply the Sentinel export type `sentinel-mock-bundle-v0`. +3. Monitor the export request by [viewing the plan + export](/terraform/enterprise/api-docs/plan-exports#show-a-plan-export). When the + status is `finished`, the data is ready for download. +4. Finally, [download the export + data](/terraform/enterprise/api-docs/plan-exports#download-exported-plan-data). + You have up to an hour from the completion of the export request - after + that, the mock data expires and must be re-generated. + +## Using Mock Data + +-> **Note:** The v2 mock files are only available on Terraform 0.12 and higher. + +Mock data is supplied as a bundled tarball, containing the following files: + + mock-tfconfig.sentinel # tfconfig mock data + mock-tfconfig-v2.sentinel # tfconfig/v2 mock data + mock-tfplan.sentinel # tfplan mock data + mock-tfplan-v2.sentinel # tfplan/v2 mock data + mock-tfstate.sentinel # tfstate mock data + mock-tfstate-v2.sentinel # tfstate/v2 mock data + mock-tfrun.sentinel # tfrun mock data + sentinel.hcl # sample configuration file + +The sample `sentinel.hcl` file contains mappings to the mocks so that you +can get started testing with `sentinel apply` right away. For `sentinel test`, +however, we recommend a more detailed layout. + +We recommend placing the files for `sentinel test` in a subdirectory +of the repository holding your policies, so they don't interfere with the +command's automatic policy detection. While the test data is Sentinel code, it's +not a policy and will produce errors if evaluated like one. + + . + ├── foo.sentinel + ├── sentinel.hcl + ├── test + │   └── foo + │   ├── fail.hcl + │   └── pass.hcl + └── testdata + ├── mock-tfconfig.sentinel + ├── mock-tfconfig-v2.sentinel + ├── mock-tfplan.sentinel + ├── mock-tfplan-v2.sentinel + ├── mock-tfstate.sentinel + ├── mock-tfstate-v2.sentinel + └── mock-tfrun.sentinel + +Each configuration that needs access to the mock should reference the mock data +files within the `mock` block in the Sentinel configuration file. + +For `sentinel apply`, this path is relative to the working directory. Assuming +you always run this command from the repository root, the `sentinel.hcl` +configuration file would look like: + +```hcl +mock "tfconfig" { + module { + source = "testdata/mock-tfconfig.sentinel" + } +} + +mock "tfconfig/v1" { + module { + source = "testdata/mock-tfconfig.sentinel" + } +} + +mock "tfconfig/v2" { + module { + source = "testdata/mock-tfconfig-v2.sentinel" + } +} + +mock "tfplan" { + module { + source = "testdata/mock-tfplan.sentinel" + } +} + +mock "tfplan/v1" { + module { + source = "testdata/mock-tfplan.sentinel" + } +} + +mock "tfplan/v2" { + module { + source = "testdata/mock-tfplan-v2.sentinel" + } +} + +mock "tfstate" { + module { + source = "testdata/mock-tfstate.sentinel" + } +} + +mock "tfstate/v1" { + module { + source = "testdata/mock-tfstate.sentinel" + } +} + +mock "tfstate/v2" { + module { + source = "testdata/mock-tfstate-v2.sentinel" + } +} + +mock "tfrun" { + module { + source = "testdata/mock-tfrun.sentinel" + } +} +``` + +For `sentinel test`, the paths are relative to the specific test configuration +file. For example, the contents of `pass.hcl`, asserting that the result of the +`main` rule was `true`, would be: + + mock "tfconfig" { + module { + source = "../../testdata/mock-tfconfig.sentinel" + } + } + + mock "tfconfig/v1" { + module { + source = "../../testdata/mock-tfconfig.sentinel" + } + } + + mock "tfconfig/v2" { + module { + source = "../../testdata/mock-tfconfig-v2.sentinel" + } + } + + mock "tfplan" { + module { + source = "../../testdata/mock-tfplan.sentinel" + } + } + + mock "tfplan/v1" { + module { + source = "../../testdata/mock-tfplan.sentinel" + } + } + + mock "tfplan/v2" { + module { + source = "../../testdata/mock-tfplan-v2.sentinel" + } + } + + mock "tfstate" { + module { + source = "../../testdata/mock-tfstate.sentinel" + } + } + + mock "tfstate/v1" { + module { + source = "../../testdata/mock-tfstate.sentinel" + } + } + + mock "tfstate/v2" { + module { + source = "../../testdata/mock-tfstate-v2.sentinel" + } + } + + mock "tfrun" { + module { + source = "../../testdata/mock-tfrun.sentinel" + } + } + + test { + rules = { + main = true + } + } + +## Mock Data Availability + +The following factors can prevent you from generating mock data: + +- You do not have permission to download Sentinel mocks for the workspace. + ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + Permission is required to protect the possibly sensitive data which can be + produced via mock generation. +- The run has not progressed past the planning stage, or did not create a plan + successfully. +- The run progressed past the planning stage prior to July 23, 2021. Prior to this date, HCP Terraform only kept JSON plans for 7 days. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If a plan cannot have its mock data exported due to any of these reasons, the +**Download Sentinel mocks** button within the plan status section of the UI will +not be visible. + +-> **Note:** Only a successful plan is required for mock generation. Sentinel can still generate the data if apply or policy checks fail. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/view-results/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/view-results/index.mdx new file mode 100644 index 0000000000..9c744110c5 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/view-results/index.mdx @@ -0,0 +1,74 @@ +--- +page_title: View policy enforcement results in Terraform Enterprise +description: >- + Learn how to view and override policy enforcement results in Terraform + Enterprise. +source: terraform-docs-common +--- + +# View policy enforcement results + +When you add [policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) to a workspace, HCP Terraform enforces those policy sets on every Terraform run. HCP Terraform displays the policy enforcement results in the UI for each run. Depending on each policy’s [enforcement level](/terraform/enterprise/policy-enforcement/manage-policy-sets#policy-enforcement-levels), policy failures can also stop the run and prevent Terraform from provisioning infrastructure. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +## Policy Evaluation Run Stages + +HCP Terraform only evaluates policies for successful plans. HCP Terraform evaluates Sentinel and OPA policy sets separately and at different points in the run. + +- Sentinel policy checks occur after Terraform completes the plan and after both [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) and [cost estimation](https://terraform.io/cloud-dodcs/cost-estimation). This order lets you write Sentinel policies to restrict costs based on the data in the cost estimates. +- Sentinel policy evaluations occur after Terraform completes the plan and after any run tasks. HCP Terraform evaluates Sentinel policy evaluations immediately before cost estimation. +- OPA policy evaluations occur after Terraform completes the plan and after any run tasks. HCP Terraform evaluates OPA policies immediately before cost estimation. + +Refer to [Run States and Stages](/terraform/enterprise/run/states) for more details. + +## View Policy Results + +To view the policy results for both Sentinel and OPA policies: + +1. Go to your workspace and navigate to the **Runs** page. +2. Click a run to view its details. + +HCP Terraform displays a timeline of the run’s events. For workspaces with both Sentinel and OPA policy sets, the run details page displays two separate run events: **OPA policies** for OPA policy sets and **Policy check** for Sentinel policy sets. + +Click a policy evaluation event to view policy results and details about any failed policies. + +-> **Note:** For Sentinel, the Terraform CLI also prints policy results for [CLI-driven runs](/terraform/enterprise/run/cli). CLI support for policy results is not available for OPA. + +## Override Policies + +You need [manage policy overrides](/terraform/enterprise/users-teams-organizations/permissions#manage-policy-overrides) permissions to override failed Sentinel and OPA policies. + +Sentinel and OPA have different policy enforcement levels that determine when you need to override failed policies to allow a run to continue. +To override failed policies, go to the run details page and click **Override and Continue** at the bottom. + +For Sentinel only, you can also override `soft-mandatory` policies with the Terraform CLI. Run the `terraform apply` command and then enter `override` when prompted. + +-> **Note:** HCP Terraform does not allow policy overrides for [no-operation plans containing no infrastructure changes](/terraform/enterprise/run/modes-and-options#allow-empty-apply), unless you choose the **Allow empty apply** option when starting the run. + +### Sentinel + +#### Policy checks + +Policies with an `advisory` enforcement level never stop runs. If they fail, HCP Terraform displays a warning in the policy results and the run continues. + +You can override `soft-mandatory` policies to allow the run to continue. Overriding failed policies on a run does not affect policy evaluations on future runs in that workspace. + +You cannot override `hard-mandatory` policies, and all of these policies must pass for the run to continue. + +#### Policy evaluations + +Policies with an `advisory` enforcement level never stop runs. If they fail, HCP Terraform displays a warning in the policy results and the run continues. + +When running Sentinel policies as policy evaluations, `soft-mandatory` and `hard-mandatory` enforcement levels are internally converted to `mandatory` enforcement level. +You can override `mandatory` policies to allow the run to continue. + +### OPA + +Policies with an `advisory` enforcement level never stop runs. If they fail, HCP Terraform displays a warning in the policy results and the run continues. + +You can override `mandatory` policies to allow the run to continue. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/view-results/json.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/view-results/json.mdx new file mode 100644 index 0000000000..c0fa9f3707 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/policy-enforcement/view-results/json.mdx @@ -0,0 +1,59 @@ +--- +page_title: View and filter Sentinel JSON data +description: Learn how to view and filter Sentinel JSON data. +source: terraform-docs-common +--- + +# View and filter Sentinel JSON data + +When using the HCP Terraform UI, Sentinel policy check results are available +both in a human-readable log form, and in a more detailed, lower-level JSON +form. While the logs may suppress some output that would make the logs harder +to read, the JSON output exposes the lower-level output directly to you. Being +able to parse this data in its entirety is especially important when working +with [non-boolean rule +data](/sentinel/docs/language/rules#non-boolean-values) in +a policy designed to work with Sentinel 0.17.0 and higher. + + + +@include 'tfc-package-callouts/policies.mdx' + + + +-> The JSON data exposed is the same as you would see when using the [policy +checks API](/terraform/enterprise/api-docs/policy-checks), with the data starting at the +`sentinel` key. + +## Viewing JSON Data + +To view the JSON data, expand the policy check on the [runs +page](/terraform/enterprise/run/manage) if it is not already expanded. The logs are +always displayed first, so click the **View JSON Data** button to view the JSON +data. You can click the **View Logs** button to switch back to the log view. + +![viewing json data](/img/docs/sentinel-view-json.png) + +## Filtering JSON Data + +The JSON data is filterable using a [jq](https://stedolan.github.io/jq/)-subset +filtering language. See the [JSON +filtering](/terraform/enterprise/workspaces/json-filtering) page for more details on +the filtering language. + +Filters are entered by putting the filter in the aptly named **filter** box in +the JSON viewer. After entering the filter, pressing **Apply** or the enter key +on your keyboard will apply the filter. The filtered results, if any, are +displayed in result box. Clearing the filter will restore the original JSON +data. + +![entering a json filter](/img/docs/sentinel-json-enter-filter.png) + +### Quick-Filtering `main` Rules + +Clicking the **Filter "main" rules** button will quickly apply a filter that +shows you the results of the `main` rule for every policy in the policy set. You +can use this to quickly get the results of each policy in the set, without +having navigate through the rest of the policy result data. + +![using the quick filter](/img/docs/sentinel-json-quick-filter.png) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/projects/best-practices.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/projects/best-practices.mdx new file mode 100644 index 0000000000..b1b60daf38 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/projects/best-practices.mdx @@ -0,0 +1,40 @@ +--- +page_title: Best Practices - Projects - Terraform Enterprise +description: >- + Best practices to structure your configuration and Terraform Enterprise + projects +source: terraform-docs-common +--- + +# Project Best Practices + +Projects let you group and scope access to your workspaces. You can group related workspaces into projects and give teams more permissive access to individual projects rather than granting them permissions to the entire organization. + +Projects offer several advantages to help you further develop your workspace strategy: + +- **Focused workspace view**: You can scope which workspaces HCP Terraform displays by project, allowing for a more organized view. +- **Simplified workspace management**: You can create project-level permissions and variable sets that apply to all current and future workspaces in the project. For example, you can create a project variable set containing your cloud provider credentials for all workspaces in the project to access. +- **Reduced risk with centralized control**: You can scope project permissions to only grant teams administrator access to the projects and workspaces they need. + +## Recommendations + +When using projects, we recommend the following: + +- **Automate with Terraform**: Automate the creation of projects, variable sets, and teams together using the [TFE provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs). +- **Designate a landing zone project**: Landing zone projects contain workspaces used to create all other projects, teams, and workspaces. This lets you have a variable set that includes the organization token, which the TFE provider can use to create other resources in your organization. You can also create a [Sentinel policy](/terraform/enterprise/policy-enforcement) to prevent users in other projects from accessing the organization token. +- **Maintain least privilege**: Restrict the number of project administrators to maintain the principal of least privilege. + +## Project boundaries + +Finally, decide on the logical boundaries for your projects. Some considerations to keep in mind include: + +- **Provider boundaries**: For smaller organizations, creating one project per cloud account may make it easier to manage access. Projects can use [dynamic credentials](/terraform/tutorials/cloud/dynamic-credentials) by configuring a project variable set to avoid hard-coding long-lived static credentials. +- **Least privilege**: You can create teams and grant them access to projects with workspaces of similar areas of ownership. For example, a production networking workspace should be in a separate project from a development compute workspace. +- **Use variable sets**: Project-wide variable sets let you configure and reuse values such as default tags for cost-codes, owners, and support contacts. Projects can own variable sets, enabling you to separate management and access to sets between projects. +- **Practitioner efficiency**: Consider if it makes sense for a practitioner to need to visit multiple projects to complete a deployment. + +## Next steps + +This article introduces some considerations to keep in mind as your organization matures their project usage. Being deliberate about how you use these to organize your infrastructure will ensure smoother and safer operations. To learn more about HCP Terraform and Terraform Enterprise best practices, refer to [Workspace Best Practices](/terraform/enterprise/workspaces/best-practices). To learn best practices for writing Terraform configuration, refer to the [Terraform Style Guide](/terraform/language/style). + +[HCP Terraform](/terraform/tutorials/cloud-get-started) provides a place to try these concepts hands-on, and you can [get started for free](https://app.terraform.io/public/signup/account). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/projects/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/projects/index.mdx new file mode 100644 index 0000000000..62f7b9a260 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/projects/index.mdx @@ -0,0 +1,51 @@ +--- +page_title: Projects - Terraform Enterprise +description: >- + Use projects to organize and group workspaces and create ownership boundaries + across your infrastructure. +source: terraform-docs-common +--- + +# Overview + + + +@include 'tfc-package-callouts/project-permissions.mdx' + + + +Projects let you organize your workspaces and scope access to workspace +resources. Each project has a separate permissions set that you can use to grant +teams access to all workspaces in the project, defining access control +boundaries for teams and their resources. Project-level permissions are more +granular than organization-level permissions, but more specific than individual +workspace-level grants. + +When deciding how to structure your projects, consider which groups of resources +need distinct access rules. You may wish to define projects by business units, +departments, subsidiaries, or technical teams. + +> **Hands On:** Try our [Managing +> Projects](/terraform/tutorials/cloud/projects) +> tutorial. + +## Default Project + +Every workspace must belong to exactly one project. By default, all workspaces +belong to an organization's **Default Project**. You can rename the default +project, but you cannot delete it. You can specify a workspace's project at the +time of creation and move it to a different project later. + +The “Manage Workspaces” team permission lets users create and manage workspaces. +Users with this permission can read and manage all workspaces, but new +workspaces are automatically added to the “Default Project” and users cannot +access the metadata for other projects. To create workspaces under other +projects, users also need the "Manage Projects & Workspaces" permission or the +admin role for the project they wish to use. + +## Managing Projects + +The "Manage all Projects" team permission lets users manage projects. Users with +this permission can view, edit, delete, and assign team access to all of an +organization's projects. Refer to [Managing +Projects](/terraform/enterprise/projects/manage) for more details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/projects/manage.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/projects/manage.mdx new file mode 100644 index 0000000000..3ad84ad7e5 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/projects/manage.mdx @@ -0,0 +1,124 @@ +--- +page_title: Manage projects in Terraform Enterprise +description: |- + Use projects to organize and group workspaces and create ownership boundaries + across your infrastructure. +source: terraform-docs-common +--- + +# Manage projects + +This topic describes how to create and manage projects in HCP Terraform and Terraform Enterprise. A project is a folder containing one or more workspaces. + +## Requirements + +You must have the following permissions to manage projects: + +- You must be a member of a team with the **Manage all Projects** permissions enabled to create a project. Refer to [Organization Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for additional information. +- You must be a member of a team with the **Visible** option enabled under **Visibility** in the organization settings to configure a new team's access to the project. Refer to [Team Visibility](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) for additional information. +- You must be a member of a team with update and delete permissions to be able to update and delete teams respectively. + +To delete tags on a project, you must be member of a team with the **Admin** permission group enabled for the project. + +To create tags for a project, you must be member of a team with the **Write** permission group enabled for the project. + +## View a project + +To view your organization's projects: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select **Projects** from the sidebar. +2. Search for a project that you want to view. You can use the following methods: + - Sort by column header. + - Use the search bar to search on the name of a project or a tag. +3. Click on a project's name to view more details. + +## Create a project + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select **Projects** from the sidebar. +2. Click **+ New project**. +3. Specify a name for the project. The name must be unique within the organization and can only include letters, numbers, inner spaces, hyphens, and underscores. +4. Add a description for the project. This field is optional. +5. Open the **Add key value tags** menu to add tags to your project. Workspaces you create within the project inherit project tags. Refer to [Define project tags](#define-project-tags) for additional information. +6. Click **+Add tag** and specify a tag key and tag value. If your organization has defined reserved tag keys, they appear in the **Tag key** field as suggestions. Refer to [Create and manage reserved tags](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for additional information. +7. Click **+ Add tag** to attach any additional tags. +8. Click **Create** to finish creating the project. + +HCP Terraform returns a new project page displaying all the project +information. + +## Edit a project + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select **Projects** from the sidebar. +2. Click on a project name of the project you want to edit. +3. Choose **Settings** from the sidebar. + +On this **General settings** page, you can update the project name, project +description, and delete the project. On the **Team access** page, you can modify +team access to the project. + +## Automatically destroy inactive workspaces + + + +@include 'tfc-package-callouts/ephemeral-workspaces.mdx' + + + +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 +time period. + +If you configure a project to auto-destroy its infrastructure when inactive, +any run that updates Terraform state further delays the scheduled auto-destroy +time by the length of your designated timeframe. + + + +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: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the project with workspaces you want to destroy. +2. Choose **Settings** from the sidebar, then **Auto-destroy Workspaces**. +3. Click **Set up default**. +4. Select or customize a desired timeframe of inactivity. +5. Click **Confirm default**. + +You can configure an individual workspace's auto-destroy settings to override +this default configuration. Refer to [automatically destroy workspaces](/terraform/enterprise/workspaces/settings/deletion#automatically-destroy) for more information. + +## Delete a project + +You can only delete projects that do not contain stacks or workspaces. + +To delete an empty project: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Click **Projects**. +3. Search for a project that you want to review by scrolling down the table or + searching for a project name in the search bar above the project table. +4. Choose **Settings** from the sidebar. +5. Click the **Delete** button. A **Delete project** modal appears. +6. Click the **Delete** button to confirm the deletion. + +HCP Terraform returns to the **Projects** view with the deleted project +removed from the list. + +## Define project tags + +You can define tags stored as key-value pairs to help you organize your projects and track resource consumption. Workspaces created in the project automatically inherit the tags, but workspace administrators with appropriate permissions can attach new key-value pairs to their workspaces to override inherited tags. Refer to [Create workspace tags](/terraform/enterprise/workspaces/tags) for additional information about using tags in workspaces. + +The following rules apply to tag keys and values: + +- Tags must be one or more characters. +- Tags have a 255 character limit. +- Tags can include letters, numbers, colons, hyphens, and underscores. +- Tag values are optional. +- You can create up to 10 unique tags per workspace and 10 unique tags per project. As a result, each workspace can have up to 20 tags. +- You cannot use the following strings at the beginning of a tag key: + - `hcp` + - `hc` + - `ibm` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/add.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/add.mdx new file mode 100644 index 0000000000..50b3130f06 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/add.mdx @@ -0,0 +1,79 @@ +--- +page_title: Add public providers and modules to the Terraform Enterprise private registry +description: >- + Learn how to add providers and modules from the public Terraform registry to + your organization's private registry. +source: terraform-docs-common +--- + +[vcs]: /terraform/enterprise/vcs + +# Add public providers and modules to the HCP Terraform private registry + +You can add providers and modules from the public [Terraform Registry](/terraform/registry) to your HCP Terraform private registry. The private registry stores a pointer to these public providers and modules so that you can view their data from within HCP Terraform. This lets you clearly designate which public providers and modules are recommended for the organization and makes their supporting documentation and examples centrally accessible. + +-> **Note:** Your Terraform Enterprise instance must allow access to `registry.terraform.io` and `https://yy0ffni7mf-dsn.algolia.net/`. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +You can add providers and modules through the UI as detailed below or through the [Registry Providers API](/terraform/enterprise/api-docs/private-registry/providers) and the [Registry Modules API](/terraform/enterprise/api-docs/private-registry/modules#create-a-module-with-no-vcs-connection-). + +## Permissions + +All members of an organization can view and use public providers and modules. Members of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) and teams with [Manage Private Registry permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) can add and delete them from the private registry. + +## Adding a Public Provider or Module + +> **Hands-on:** Try the [Add Public Providers and Modules to your Private Registry](/terraform/tutorials/modules/private-registry-add) tutorial and [Share Modules in the Private Registry](/terraform/tutorials/modules/module-private-registry-share) tutorials. + +To add a public provider or module: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to add a public provider or module to. + +2. Select **Registry** from the sidebar. The organization's private registry appears with a list of available providers and modules. + +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. + +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**. + - Click the provider or module to view its details and then click **Add to HCP Terraform**. + +6. Click **Add to organization** in the dialog box. Members of your organization can now begin using it from the private registry. + +## Enabling and Disabling No-Code Provisioning + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +You can enable no-code provisioning for public modules after adding them to your registry. + +To support the auto-apply workflow, ensure that downstream users can automatically load provider credentials into their new no-code workspaces. You can enable access by either creating a [global or project-scoped variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) with the credentials for the module's provider, or by accessing outputs with credentials from other workspaces. Refer to [Provider Credentials](/terraform/enterprise/no-code-provisioning/module-design#provider-credentials) for more details. + +To enable no-code provisioning: + +1. Verify that the module meets the [requirements for no-code provisioning](/terraform/enterprise/no-code-provisioning/module-design#requirements). +2. Click the module to view its details. +3. Select **Enable no-code provisioning** from the **Manage Module for Organization** dropdown. + +Your module’s details page now has a **No-Code Ready** badge to indicate that it supports no-code provisioning. + +To disable no-code provisioning, select **Disable no-code provisioning** from the **Manage Module for Organization** dropdown. Disabling also removes the **No-Code Ready** badge from the module’s details page. + +## Removing a Public Provider or Module + +Removing a public provider or module from a private registry does not remove it from the public Terraform Registry. Users in the organization can still use the removed provider or module without changing their configurations. + +To remove a public provider or module from an organization's private registry: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization whose registry you want to remove a provider or module from. + +2. Select **Registry** from the sidebar. The organization's private registry appears with a list of available providers and modules. + +3. Select the provider or module to view its details, open the **Manage for Organization** menu, and click **Remove from organization** (providers) or **Delete module** (modules). + +4. Enter the provider or module name in the dialog box to confirm and then click **Remove** (providers) or **Delete** (modules). The provider or module no longer appears in the organization's private registry. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/design.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/design.mdx new file mode 100644 index 0000000000..935081361e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/design.mdx @@ -0,0 +1,64 @@ +--- +page_title: Use the configuration designer in Terraform Enterprise +description: >- + Learn how to outline a configuration with private modules and define variables + with the Terraform Enterprise configuration designer. +source: terraform-docs-common +--- + +# Use the configuration designer + +HCP Terraform's private registry includes a configuration designer that can help you spend less time writing boilerplate code in a module-centric Terraform workflow. + +The configuration designer lets you outline a configuration for a new workspace by choosing any number of private modules. It then lists those modules' variables as a fillable HTML form, with a helper interface for finding values that you can interpolate. When you are finished, the designer returns the text of a `main.tf` configuration. This is the same Terraform code you would have written in your text editor. + +## Accessing the Configuration Designer + +Go to your organization's private registry, and then click **<> Design Configuration**. + +The **Select Modules** page appears. + +## Adding Modules + +Filter and search the left side of the **Select Modules** page to find private modules that you can add to your configuration. + +Click **Add Module** for all of the modules you want to use in your configuration. These modules appear in the **Selected Modules** list on the right side of the page. + +### Setting Versions + +Selecting a module adds its most recent version to the configuration. To specify a different version: + +1. Click the module's version number from the **Selected Modules** list on the right. +2. Select an alternate version from the menu. + +## Setting Variables + +When you finish selecting modules, click **Next »** to go to the **Set Variables** page. + +The left side of this page lists your chosen modules, and the right side lists all variables for the currently selected module. Each variable is labeled as required or optional. + +You can switch between modules without losing your work; click a module's **Configure** button to switch to its variable list. + +Once you set a value for all of a module's required variables, its **Configure** button changes to a green **Configured** button. + +### Interpolation Searching + +Variable values can be literal strings, or can interpolate other values. When you start typing an interpolation token (`${`), the designer displays a help message. As you continue typing, it searches the available outputs in your other selected modules, as well as outputs from workspaces where you are authorized to read state outputs. You can select one of these search results, or type a full name if you need to reference a value HCP Terraform does not know about. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Deferring Variables + +Sometimes, configuration users should be able to set certain variables according to their use cases. + +Select the **Deferred** checkbox to delegate a variable to configuration users. This ties the variable's value to a new top-level Terraform variable with no default value. All users that create a workspace from your configuration will have to provide a value for that variable. + +## The Output Configuration + +When all modules are configured, click **Next »**. + +The **Publish** page appears. Use the **Preview configuration** menu to review the generated code. + +The configuration designer does not create any repositories or workspaces. To create workspaces with the configuration, you must download the generated code, save it as the `main.tf` file in a new directory, and commit it to version control. After you download the code, you can make any necessary changes or additions. For example, you may want to add non-module resources. + +When you are sure you have downloaded the results, click **Done** to discard the configuration. HCP Terraform does not save output from previous configuration designer runs. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/index.mdx new file mode 100644 index 0000000000..0405c24452 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/index.mdx @@ -0,0 +1,27 @@ +--- +page_title: Terraform Enterprise private registry overview +description: >- + The Terraform Enterprise private registry lets you share private modules and + providers across your organization. +source: terraform-docs-common +--- + +# HCP Terraform private registry overview + +HCP Terraform's private registry works similarly to the [public Terraform Registry](/terraform/registry) and helps you share [Terraform providers](/terraform/language/providers) and [Terraform modules](/terraform/language/modules) across your organization. It includes support for versioning and a searchable list of available providers and modules. + +> **Hands-on:** Try the [Add Public Providers and Modules to your Private Registry](/terraform/tutorials/modules/private-registry-add) tutorial and [Share Modules in the Private Registry](/terraform/tutorials/modules/module-private-registry-share) tutorials. + +## Public Providers and Modules + +[Public modules and providers](/terraform/enterprise/registry/add) are hosted on the public Terraform Registry and HCP Terraform can automatically synchronize them to an organization's private registry. This lets you clearly designate which public providers and modules are recommended for the organization and makes their supporting documentation and examples centrally accessible. + +-> **Note:** Your Terraform Enterprise instance must allow access to `registry.terraform.io` and `https://yy0ffni7mf-dsn.algolia.net/`. + +## Private Providers and Modules + +[Private providers](/terraform/enterprise/registry/publish-providers) and [private modules](/terraform/enterprise/registry/publish-modules) are hosted on an organization's private registry and are only available to members of that organization. In Terraform Enterprise, private providers and modules are also available to other organizations that are [configured to share](/terraform/enterprise/admin/application/registry-sharing) with that organization. + +## Managing Usage + +You can create [Sentinel policies](/terraform/enterprise/policy-enforcement) to manage how members of your organization can use modules from the private registry. For example, you can mandate that all non-root modules in Terraform configurations must be private or public modules from your own private registry. You can also apply a policy that requires all modules to use recent versions. Refer to our [example policy on GitHub](https://github.com/hashicorp/terraform-sentinel-policies/blob/main/cloud-agnostic/http-examples/use-recent-versions-from-pmr.sentinel). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/manage-module-versions.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/manage-module-versions.mdx new file mode 100644 index 0000000000..2c83eeefec --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/manage-module-versions.mdx @@ -0,0 +1,218 @@ +--- +page_title: Manage module versions in Terraform Enterprise +description: >- + 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 +--- + +# Manage module versions + +<>{/* 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. + + + +@include "tfc-package-callouts/manage-module-versions.mdx" + + + +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. + +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. + + + +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](/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 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. + +### Deprecation warnings + +After you deprecate a module version, consumers of that version receive warnings in their operation outputs urging them to update that version in both HCP Terraform and the Terraform CLI. + +~> **Note**: Only workspaces in the [remote or agent execution modes](/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: + + + +```shell +Found the following deprecated module versions, consider using an updated version. + +``` + + + +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, 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. + +<>{/* 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/v000011-1/docs/enterprise/registry/publish-modules.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/publish-modules.mdx new file mode 100644 index 0000000000..657f740572 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/publish-modules.mdx @@ -0,0 +1,165 @@ +--- +page_title: Publish private modules to the Terraform Enterprise private registry +description: >- + Use the Terraform Enterprise private registry to publish and share private + modules across your organization. +source: terraform-docs-common +--- + +[vcs]: /terraform/enterprise/vcs + +# Publish private modules to the HCP Terraform private registry + +> **Hands-on:** Try the [Share Modules in the Private Module Registry](/terraform/tutorials/modules/module-private-registry-share) tutorial. + +In addition to [adding modules from the Terraform Registry](/terraform/enterprise/registry/add), you can publish private modules to an organization's HCP Terraform private registry. The registry handles downloads and controls access with HCP Terraform API tokens, so consumers do not need access to the module's source repository, even when running Terraform from the command line. + +The private registry uses your configured [Version Control System (VCS) integrations][vcs] and defers to your VCS provider for most management tasks. For example, your VCS provider handles new version releases. The only manual tasks are adding a new module and deleting module versions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Permissions + +Private modules are only available to members of the organization where you add them. In Terraform Enterprise, they are also available to organizations that you configure to [share modules](/terraform/enterprise/admin/application/registry-sharing) with that organization. + +Members of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) and teams with [Manage Private Registry permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) can publish and delete modules from the private registry. + +## Preparing a Module Repository + +After you configure at least one [connection to a VCS provider][vcs], you can publish a new module by specifying a properly formatted VCS repository (details below). The registry automatically detects the rest of the information it needs, including the module's name and its available versions. + +A module repository must meet all of the following requirements before you can add it to the registry: + +- **Location and permissions:** The repository must be in one of + your configured [VCS providers][vcs], and HCP Terraform's VCS user account must have admin access to the repository. The registry needs admin access to create the webhooks to import new module versions. GitLab repositories must be in the main organization or group, and not in any subgroups. + +- **Named `terraform--`:** Module repositories must use this + three-part name format, where `` reflects the type of infrastructure + the module manages and `` is the main provider where it creates that + infrastructure. The `` segment must be all lowercase. The `` + segment can contain additional hyphens. Examples: `terraform-google-vault` or + `terraform-aws-ec2-instance`. + +- **Standard module structure:** The module must adhere to the + [standard module structure](/terraform/language/modules/develop/structure). + This allows the registry to inspect your module and generate documentation, + track resource usage, and more. + +## Publishing a New Module + +You can publish modules through the UI as shown below or with the [Registry Modules API](/terraform/enterprise/api-docs/private-registry/modules). The API also supports publishing modules without a VCS repo as the source, which is not possible in the UI. + +To publish a new module: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to publish a module. + +2. Select **Registry** from the sidebar. + +3. Click **Publish** and select **Module**. + + The **Add Module** page appears with a list of available repositories. + +4. Select the repository containing the module you want to publish. + + You can search the list by typing part or all of a repository name into the filter field. Remember that VCS providers use `/` strings to locate repositories. The namespace is an organization name for most providers, but Bitbucket Data Center, not Bitbucket Cloud, uses project keys, like `INFRA`. + +5. When prompted, choose either the **Tag** or **Branch** module publishing type. + +6. (Optional) If this module is a [no-code ready module](/terraform/enterprise/no-code-provisioning/module-design), select the **Add Module to no-code provision allowlist** checkbox. + +7. Click **Publish module**. + + HCP Terraform displays a loading page while it imports the module versions and then takes you to the new module's details page. On the details page, you can view available versions, read documentation, and copy a usage example. + + + +@include 'tfc-package-callouts/nocode.mdx' + + + +### Tag-based publishing considerations + +When using the **Tag** module publishing type, the registry uses `x.y.z` formatted release tags to identify module versions. Your repository must contain at least one release tag for you to publish a module. Release tag names must be a [semantic version](http://semver.org), which you can optionally prefix with a `v`. For example, `v1.0.4` and `0.9.2`. The registry ignores tags that do not match these formats. + + + +### Branch-based publishing considerations + +When using the **Branch** module publishing type, you must provide the name of an existing branch in your VCS repository and give the module a **Module version**. Your VCS repository does not need to contain a matching tag or release. + +You can only enable testing on modules published using branch-based publishing. Refer to the [test-integrated modules](/terraform/enterprise/registry/test) documentation for more information. + + + +## Releasing New Versions of a Module + + + +The process to release a new module version differs between the tag-based and branch-based publishing workflows. + +### Tag-Based Publishing Workflow + + + +To release a new version of a module in the tag-based publishing workflow, push a new release tag to its VCS repository. The registry automatically imports the new version. + +Refer to [Preparing a Module Repository](#preparing-a-module-repository) for details about release tag requirements. + + + +### Branch-Based Publishing Workflow + +To release a new version of a module using the branch-based publishing workflow, navigate to the module overview screen, then click the **Publish New Version** button. Select the commit SHA that the new version will point to, and assign a new module version. You cannot re-use an existing module version. + +## Update Publish Settings + +After publishing your module, you can change between tag-based and branch-based publishing. To update your module's publish settings, navigate to the the module overview page, click the **Manage Module for Organization** dropdown, and then click **Publish Settings**. + +- To change from tag-based to branch-based publishing, you must configure a **Module branch** and [create a new module version](#branch-based-publishing-workflow), as HCP Terraform will not automatically create one. + +- To change from branch-based publishing to tag-based publishing, you must create at least one tag in your VCS repository. + + + +## Deleting Versions and Modules + +-> **Note:** Deleting a tag from your VCS repository does not automatically remove the version from the private registry. + +You can delete individual versions of a module or the entire module. If deleting a module version would leave a module with no versions, HCP Terraform removes the entire module. To delete a module or version: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the module's details page. + +2. If you want to delete a single version, use the **Versions** menu to select it. + +3. Click **Delete module**. + +4. Select an action from the menu: + + - **Delete only this module version:** Deletes only the version of the module you were viewing when you clicked **Delete module**. + - **Delete all versions for this provider for this module:** Deletes the entire module for a single provider. This action is important if you have modules with the same name but with different providers. For example, if you have module repos named `terraform-aws-appserver` and `terraform-azure-appserver`, the registry treats them as alternate providers of the same `appserver` module. + - **Delete all providers and versions for this module:** Deletes all modules with this name, even if they are from different providers. For example, this action deletes both `terraform-aws-appserver` and `terraform-azure-appserver`. + +5. Type the module name and click **Delete**. + +### Restoring a Deleted Module or Version + +Deletion is permanent, but there are ways to restore deleted modules and module versions. + +- To restore a deleted module, re-add it as a new module. +- To restore a deleted version, either delete the corresponding tag from your VCS and push a new tag with the same name, or delete the entire module from the registry and re-add it. + +## Sharing Modules Across Organizations + +HCP Terraform does not typically allow one organization's workspaces to use private modules from a different organization. This restriction is because HCP Terraform gives Terraform temporary credentials to access modules that are only valid for that workspace's organization. Although it is possible to mix modules from multiple organizations when you run Terraform on the command line, we strongly recommend against it. + +Instead, you can share modules across organizations by sharing the underlying VCS repository. Grant each organization access to the module's repository, and then add the module to each organization's registry. When you push tags to publish new module versions, both organizations update accordingly. + +Terraform Enterprise administrators can configure [module sharing](/terraform/enterprise/admin/application/registry-sharing) to allow organizations to use private modules from other organizations. + +## Generating Module Tests (Beta) + +You can generate and run generated tests for your module with [the `terraform test` command](/terraform/cli/commands/test). + +Before you can generate tests for a module, it must have at least one version published. Tests can only be generated once per module and are intended to be reviewed by the module's authors before being checked into version control and maintained with the rest of the module's content. If the module's configuration files exceed 128KB in total size, HCP Terraform will not be able to generate tests for that module. + +You must have [permission to manage registry modules](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) and [permission to manage module test generation](/terraform/enterprise/users-teams-organizations/permissions#manage-module-test-generation-beta) to generate tests. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/publish-providers.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/publish-providers.mdx new file mode 100644 index 0000000000..a7a1d6f811 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/publish-providers.mdx @@ -0,0 +1,266 @@ +--- +page_title: Publish private providers to the Terraform Enterprise private registry +description: >- + Use the Terraform Enterprise private registry to publish and share private + providers across your organization. +source: terraform-docs-common +--- + +# Publish private providers to the HCP Terraform private registry + +In addition to [curating public providers from the Terraform Registry](/terraform/enterprise/registry/add), you can publish private providers to an organization's HCP Terraform private registry. Once you have published a private provider through the API, members of your organization can search for it in the private registry UI and use it in configurations. + +## Requirements + +Review the following before publishing a new provider or provider version. + +### Permissions + +Users must be members of an organization to access its registry and private providers. In Terraform Enterprise, providers are also available to organizations that you configure to [share registry access](/terraform/enterprise/admin/application/registry-sharing). + +You must be a member of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) or a team with [Manage Private Registry permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) to publish and delete private providers from the private registry. + +### Release files + +You must publish at least one version of your provider that follows [semantic versioning format](http://semver.org). For each version, you must upload the `SHA256SUMS` file, `SHA256SUMS.sig` file, and one or more provider binaries. Using GoReleaser to [create a release on GitHub](/terraform/registry/providers/publishing#creating-a-github-release) or [create a release locally](/terraform/registry/providers/publishing#using-goreleaser-locally) generates these files automatically. The private registry does not have strict naming conventions, but we recommend using GoReleaser file naming schemes for consistency. + +Private providers do not currently support documentation. + +### Signed releases + +GPG signing is required for private providers, and you must upload the public key of the GPG keypair used to sign the release. Refer to [Preparing and Adding a Signing Key](/terraform/registry/providers/publishing#preparing-and-adding-a-signing-key) for more details. Unlike the public Terraform Registry, the private registry does not automatically upload new releases. You must manually add new provider versions and the associated release files. + +-> **Note**: If you are using the [provider API](/terraform/enterprise/api-docs/private-registry/providers) to upload an official HashiCorp public provider into your private registry, use [HashiCorp's public PGP key](https://www.hashicorp.com/.well-known/pgp-key.txt). You do not need to upload this public key, and it is automatically included in Terraform Enterprise version v202309-1 and newer. + +## Publishing a provider + +Before consumers can use a private provider, you must do the following: + +1. [Create the provider](#create-the-provider) +2. [Upload a GPG signing key](#add-your-public-key) +3. [Create at least one version](#create-a-version) +4. [Create at least one platform for that version](#create-a-provider-platform) +5. [Upload release files](#upload-provider-binary) + +### Create the provider + +Create a file named `provider.json` with the following contents. Replace `PROVIDER_NAME` with the name of your provider and replace `ORG_NAME` with the name of your organization. + +```json +{ + "data": { + "type": "registry-providers", + "attributes": { + "name": "PROVIDER_NAME", + "namespace": "ORG_NAME", + "registry-name": "private" + } + } +} +``` + +Use the [Create a Provider endpoint](/terraform/enterprise/api-docs/private-registry/providers#create-a-provider) to create the provider in HCP Terraform. Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token and replace `ORG_NAME` with the name of your organization. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @provider.json \ + https://app.terraform.io/api/v2/organizations/ORG_NAME/registry-providers +``` + +The provider is now available in your organization’s HCP Terraform private registry, but consumers cannot use it until you add a version and a platform. + +To create a version and a platform, you need the following resources: + +- The Provider binaries +- A public GPG signing key +- A `SHA256SUMS` file +- A `SHA256SUMS.sig` file from at least one release + +### Add your public key + +-> **Note**: If you are uploading an official HashiCorp public provider into your private registry, skip this step and instead use [HashiCorp's public PGP key](https://www.hashicorp.com/.well-known/pgp-key.txt) in the the [create a version](#create-a-version) step. The key ID for HashiCorp's public ID is `34365D9472D7468F`, and you can verify the ID by [importing the public key locally](/terraform/tutorials/cli/verify-archive#download-and-import-hashicorp-s-public-key). + +Create a file named `key.json` with the following contents. Replace `ORG_NAME` with the name of your organization, and input your public key in an RSA or DSA format in the `ascii-armor` field. + +```hcl +{ + "data": { + "type": "gpg-keys", + "attributes": { + "namespace": "ORG_NAME", + "ascii-armor": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nmQINB...=txfz\n-----END PGP PUBLIC KEY BLOCK-----\n" + } } +} +``` + +Use the [Add a GPG key endpoint](/terraform/enterprise/api-docs/private-registry/gpg-keys#add-a-gpg-key) to add the public key that matches the signing key for the release. Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @key.json \ + https://app.terraform.io/api/registry/private/v2/gpg-keys +``` + +The response contains a `key-id` that you will use to create a provider version. + +```json +"key-id": "34365D9472D7468F" +``` + +### Create a version + +Create a file named `version.json` with the following contents. Replace the value of the `version` field with the version of your provider, and replace the `key-id` field with the id of the GPG key that you created in the [Add your public key](#add-your-public-key) step. If you are uploading an official HashiCorp public provider, use the value `34365D9472D7468F` for your `key-id`. + +```hcl +{ + "data": { + "type": "registry-provider-versions", + "attributes": { + "version": "5.14.0", + "key-id": "34365D9472D7468F", + "protocols": ["5.0"] + } + } +} +``` + +Use the [Create a Provider Version endpoint](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-version) to create a version for your provider. Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token, and replace both instances of `ORG_NAME` with the name of your organization. If are not using the `aws` provider, then replace `aws` with your provider's name. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @version.json \ + https://app.terraform.io/api/v2/organizations/ORG_NAME/registry-providers/private/ORG_NAME/aws/versions +``` + + The response includes URL links that you will use to upload the `SHA256SUMS` and `SHA256.sig` files. + +```json +"links": { + "shasums-upload": "https://archivist.terraform.io/v1/object/dmF1b64hd73ghd63", + "shasums-sig-upload": "https://archivist.terraform.io/v1/object/dmF1b37dj37dh33d" + } +``` + +### Upload signatures + +Upload the `SHA256SUMS` and `SHA256SUMS.sig` files to the URLs [returned in the previous step](#create-a-version). The example command below uploads the files from your local machine. First upload the `SHA256SUMS` file to the URL returned in the `shasums-upload` field. + +```shell-session +$ curl \ + -T terraform-provider-aws_5.14.0_SHA256SUMS \ + https://archivist.terraform.io/v1/object/dmF1b64hd73ghd63... +``` + +Next, upload the `SHA256SUMS.sig` file to the URL returned in the `shasums-sig-upload` field. + +```shell-session +$ curl \ + -T terraform-provider-aws_5.14.0_SHA256SUMS.72D7468F.sig \ + https://archivist.terraform.io/v1/object/dmF1b37dj37dh33d... +``` + +### Create a provider platform + +First, calculate the SHA256 hash of the provider binary that you intend to upload. This should match the SHA256 hash of the file listed in the `SHA256SUMS` file. + +```shell-session +$ shasum -a 256 terraform-provider-aws_5.14.0_linux_amd64.zip +f1d83b3e5a29bae471f9841a4e0153eac5bccedbdece369e2f6186e9044db64e terraform-provider-aws_5.14.0_linux_amd64.zip +``` + +Next, create a file named `platform.json`. Replace the `os`, `arch`, `filename`, and `shasum` fields with the values that match the provider you intend to upload. + +```json +{ + "data": { + "type": "registry-provider-version-platforms", + "attributes": { + "os": "linux", + "arch": "amd64", + "shasum": "f1d83b3e5a29bae471f9841a4e0153eac5bccedbdece369e2f6186e9044db64e", + "filename": "terraform-provider-aws_5.14.0_linux_amd64.zip" + } + } +} +``` + +Use the [Create a Provider Platform endpoint](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms#create-a-provider-platform) to create a platform for the version. Platforms are binaries that allow the provider to run on a particular operating system and architecture combination (e.g., Linux and AMD64). Replace `TOKEN` in the `Authorization` header with your HCP Terraform API token and replace both instances of `ORG_NAME` with the name of your organization. + +```shell-session +$ curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @platform.json \ + https://app.terraform.io/api/v2/organizations/ORG_NAME/registry-providers/private/ORG_NAME/aws/versions/5.14.0/platforms +``` + +The response includes a `provider-binary-upload` URL that you will use to upload the binary file for the platform. + +```json +"links": { + "provider-binary-upload": "https://archivist.terraform.io/v1/object/dmF1b45c367djh45nj78" + } +``` + +### Upload provider binary + +Upload the platform binary file to the `provider-binary-upload` URL returned in the [previous step](#create-a-version). The example command below uploads the binary from your local machine. + +```shell-session +$ curl -T local-example/terraform-provider-random_5.14.0_linux_amd64.zip + https://archivist.terraform.io/v1/object/dmF1b45c367djh45nj78 +``` + +The version is available in the HCP Terraform user interface. Consumers can now begin using this provider version in configurations. You can repeat these steps starting from [Create a provider platform](#create-a-provider-platform) to add additional platform binaries for the release. + +## Checking Release Files + +Consumers cannot use a private provider version until you upload all required [release files](#release-files). To determine whether these files have been uploaded: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to publish a private provider. +2. Click **Registry** and click the private provider to go to its details page. +3. Use the version menu to navigate to the version you want to check. The UI shows a warning banner for versions that do not have all required release files. +4. Open the **Manage Provider** menu and select **Show release files**. The **Release Files** page appears containing lists of uploaded and missing files for the current version. + +## Managing private providers + +Use the HCP Terraform API to create, read, update, and delete the following: + +- [GPG keys](/terraform/enterprise/api-docs/private-registry/gpg-keys) +- [Private providers](/terraform/enterprise/api-docs/private-registry/providers) +- [Provider versions and platforms](/terraform/enterprise/api-docs/private-registry/provider-versions-platforms) + +## Deleting private providers and versions + +In addition to the [Registry Providers API](/terraform/enterprise/api-docs/private-registry/providers#delete-a-provider), you can delete providers and provider versions through the HCP Terraform UI. To delete providers and versions in the UI: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization whose private registry you want to delete a provider or provider version from. + +2. Click **Registry** and click the private provider to go to its details page. + +3. If you want to delete a single version, use the **Versions** menu to select it. + +4. Open the **Manage Provider** menu and select **Delete Provider**. The **Delete Provider from Organization** box appears. + +5. Select an action from the menu: + + - **Delete only this provider version:** Deletes only the version of the provider you are currently viewing. + - **Delete all versions for this provider:** Deletes the entire provider and all associated versions. + +6. Type the provider name into the confirmation box and click **Delete**. + +The provider version or entire provider has been deleted from this organization's private registry and its data has been removed. Consumers will no longer be able to reference it in configurations. + +### Restoring a deleted provider + +Deletion is permanent, but you can restore a deleted private provider by re-adding it to your organization and recreating its versions and platforms. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/test.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/test.mdx new file mode 100644 index 0000000000..377e7f3402 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/test.mdx @@ -0,0 +1,69 @@ +--- +page_title: Test private modules in the Terraform Enterprise private registry +description: Use the Terraform Enterprise private registry to run module tests. +source: terraform-docs-common +--- + +# Test private modules in the HCP Terraform private registry + +You can configure HCP Terraform to automatically run tests for modules in your private registry. When enabled, HCP Terraform will run tests for every commit to the designated branch. This lets you verify that it is safe to publish new module versions. + +## Enable testing + +If your module uses the [branch-based publishing workflow](/terraform/enterprise/registry/publish-modules#branch-based-publishing) and its source code includes [tests](/terraform/language/v1.6.x/tests), you can enable testing at any time. + +To enable testing when you publish your module: + +- Choose the **Branch** module publishing type +- Assign a branch and a module version +- Under testing, click the **Enable testing for module** checkbox +- Click **Publish module** + +To enable testing after you publishing your branch-based module: + +- Navigate to the module overview screen +- Click **Configure Tests** to open the **Tests Settings** screen +- Click **Enable testing for 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. + +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 +``` + +## 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. + +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**. +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. + + + +## Generated module tests + +@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. + +To generate tests for your module: + +1. On the module overview screen, click **Generate tests**. +2. Click **Confirm**. It will take a few minutes to generate your module tests. +3. HCP Terraform displays generated configuration. To download all of the test files, click **Download generated tests**. +4. Create a `tests` directory in your configuration. +5. Unzip the downloaded files into the new `tests` directory. + +Generated test files remain available on the module overview page for later retrieval. Click **View test files** to view and download any previously generated tests. + +Organization owners can control this feature on the organization's [General Settings](/terraform/enterprise/users-teams-organizations/organizations#organization-settings) page. + + diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/registry/using.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/registry/using.mdx new file mode 100644 index 0000000000..98542f2bd7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/registry/using.mdx @@ -0,0 +1,149 @@ +--- +page_title: Use providers and modules from the Terraform Enterprise private registry +description: >- + Learn how to use providers and modules from the Terraform Enterprise private + registry in your Terraform configuration. +source: terraform-docs-common +--- + +# Use providers and modules from the HCP Terraform private registry + +All users in an organization can view the HCP Terraform private registry and use the available providers and modules. A private registry has some key requirements and differences from the [public Terraform Registry](/terraform/registry): + +- **Location:** Search for providers, modules, and usage examples in the HCP Terraform private registry UI. +- **Provider and Module block `source` argument:** Private providers and modules use a [different format](/terraform/enterprise/registry/using#using-private-providers-and-modules-in-configurations). +- **Terraform version:** HCP Terraform workspaces using version 0.11 and higher can automatically access your private modules during Terraform runs, and workspaces using version 0.13 and higher can also automatically access private providers. +- **Authentication:** If you run Terraform on the command line, you must [authenticate](/terraform/enterprise/registry/using#authentication) to HCP Terraform or your instance to use providers and modules in your organization’s private registry. + +HCP Terraform supports using modules in written configuration or through the [no-code provisioning workflow](/terraform/enterprise/no-code-provisioning/provisioning). + +## Finding Providers and Modules + +To find available providers and modules, click the **Registry** button. The **Registry** page appears. + +Click **Providers** and **Modules** to toggle back and forth between lists of available providers and modules in the private registry. You can also use the search field to filter for titles that contain a specific keyword. The search does not include READMEs or resource details. + +### Shared Providers and Modules - Terraform Enterprise + +On Terraform Enterprise, your [registry sharing](/terraform/enterprise/admin/application/registry-sharing) configuration may grant you access to another organization's providers and modules. Providers and modules that are shared with your current organization have a **Shared** badge in the private registry (below). Providers and modules in your current organization that are shared with other organizations have a badge that says **Sharing**. + +### Viewing Provider and Module Details and Versions + +Click a provider or module to view its details page. Use the **Versions** menu in the upper right to switch between the available versions, and use the **Readme**, **Inputs**, **Outputs**, **Dependencies**, and **Resources** tabs to view more information about the selected version. + +### Viewing Nested Modules and Examples + +Use the **Submodules** menu to navigate to the detail pages for any nested modules. Use the **Examples** menu to navigate to the detail pages for any available example modules. + +## Provisioning Infrastructure from No-Code Ready Modules + +You can use modules marked **No-Code Ready** to create a new workspace and automatically provision the module's resources without writing any Terraform configuration. Refer to [Provisioning No-Code Infrastructure](/terraform/enterprise/no-code-provisioning/provisioning) for details. + +## Using Public Providers and Modules in Configurations + +> **Hands-on:** Try the [Use Modules from the Registry](/terraform/tutorials/modules/module-use) tutorial. + +The syntax for public providers in a private registry is the same as for providers that you use directly from the public Terraform Registry. The syntax for the [provider block](/terraform/language/providers/configuration#provider-configuration-1) `source` argument is `/`. + +```hcl +terraform { + required_providers { + google = { + source = "hashicorp/google" + version = "4.0.0" + } + } +``` + +The syntax for referencing public modules in the [module block](/terraform/language/modules/syntax) `source` argument is `//`. + +```hcl +module "subnets" { + source = "hashicorp/subnets/cidr" + version = "1.0.0" +} +``` + +## Using Private Providers and Modules in Configurations + +The syntax for referencing private providers in the [provider block](/terraform/language/providers/configuration#provider-configuration-1) `source` argument is `//`. For the SaaS version of HCP Terraform, the hostname is `app.terraform.io`. + +```hcl +terraform { + required_providers { + random = { + source = "app.terraform.io/demo-custom-provider/random" + version = "1.1.0" + } + } +``` + +The syntax for referencing private modules in the [module block](/terraform/language/modules/syntax) `source` argument is `///`. + +- **Hostname:** For the SaaS version of HCP Terraform, use `app.terraform.io`. In Terraform Enterprise, use the hostname for your instance or the [generic hostname](/terraform/enterprise/registry/using#generic-hostname-terraform-enterprise). +- **Organization:** If you are using a shared module with Terraform Enterprise, the module's organization name may be different from your organization's name. Check the source string at the top of the module's registry page to find the proper organization name. + +```hcl +module "vpc" { + source = "app.terraform.io/example_corp/vpc/aws" + version = "1.0.4" +} +``` + +### Generic Hostname - HCP Terraform and Terraform Enterprise + +You can use the generic hostname `localterraform.com` in module sources to reference modules without modifying the HCP Terraform or Terraform Enterprise instance. When you run Terraform, it automatically requests any `localterraform.com` modules from the instance it runs on. + +```hcl +module "vpc" { + source = "localterraform.com/example_corp/vpc/aws" + version = "1.0.4" +} +``` + +~> **Important**: CLI-driven workflows require Terraform CLI v1.4.0 or above. + +To test configurations on a developer workstation without the remote backend configured, you must replace the generic hostname with a literal hostname in all module sources and then change them back before committing to VCS. We are working on making this workflow smoother, but we only recommend `localterraform.com` for large organizations that use multiple Terraform Enterprise instances. + +### Provider and Module Availability + +A workspace can only use private providers and modules from its own organization's registry. When using providers or modules from multiple organizations in the same configuration, we recommend: + +- **HCP Terraform:** [Add providers and modules to the registry](/terraform/enterprise/registry/publish-modules#sharing-modules-across-organizations) for each organization that requires access. + +- **Terraform Enterprise:** Check your site's [registry sharing](/terraform/enterprise/admin/application/registry-sharing) configuration. Workspaces can also use private providers and modules from organizations that are sharing with the workspace's organization. + +## Running Configurations with Private Providers and Modules + +### Version Requirements + +Terraform version 0.11 or later is required to use private modules in HCP Terraform workspaces and to use the CLI to apply configurations with private modules. Terraform version 0.13 and later is required to use private providers in HCP Terraform workspaces and apply configurations with private providers. + +### Authentication + +To authenticate with HCP Terraform, you can use either a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or a [team token](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens). The type of token you choose may grant different permissions. + +- **User Token**: Allows you to access providers and modules from any organization in which you are a member. You are a member of an organization if you belong to any team in that organization. You can also access modules from any organization that is sharing modules with any of your organizations. + + -> **Note:** When SAML SSO is enabled, there is a [session timeout for user API tokens](/terraform/enterprise/saml/login#api-token-expiration), requiring you to periodically re-authenticate through the web UI. Expired tokens produce a _401 Unauthorized_ error. A SAML SSO account with [IsServiceAccount](/terraform/enterprise/saml/attributes#isserviceaccount) is treated as a service account and will not have the session timeout. + +- **Team Token**: Allows you to access the private registry of that team's organization and the registries from any other organizations that have configured sharing. + +_Permissions Example_ + +A user belongs to three organizations (1, 2, and 3), and organizations 1 and 2 share access with each other. In this case, the user's token gives them access to the private registries for all of the organizations they belong to: 1, 2, and 3. However, a team token from a team in organization 1 only gives the user access to the private registry in organizations 1 and 2. + +#### Configure Authentication + +To configure authentication to HCP Terraform or your Terraform Enterprise instance, you can: + +- (Terraform 0.12.21 or later) Use the [`terraform login`](/terraform/cli/commands/login) command to obtain and save a user API token. +- Create a token and [manually configure credentials in the CLI config file][cli-credentials]. + +Make sure the hostname matches the hostname you use in provider and module sources because if the same HCP Terraform server is available at two hostnames, Terraform will not know that they reference the same server. To support multiple hostnames for provider and module sources, use the `terraform login` command multiple times and specify a different hostname each time. + +[user-token]: /terraform/enterprise/users-teams-organizations/users#api-tokens + +[cli-credentials]: /terraform/cli/config/config-file#credentials + +[permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/api.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/api.mdx new file mode 100644 index 0000000000..eaf923fce2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/api.mdx @@ -0,0 +1,197 @@ +--- +page_title: The API-driven run workflow in Terraform Enterprise +description: >- + Use Terraform Enterprise's API-driven run workflow to enable external tools to + upload Terraform configurations and trigger new runs. +source: terraform-docs-common +--- + +# The API-driven run workflow + +HCP Terraform has three workflows for managing Terraform runs. + +- The [UI/VCS-driven run workflow](/terraform/enterprise/run/ui), which is the primary mode of operation. +- The API-driven run workflow described below, which is more flexible but requires you to create some tooling. +- The [CLI-driven run workflow](/terraform/enterprise/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +## Summary + +In the API-driven workflow, workspaces are not directly associated with a VCS repo, and runs are not driven by webhooks on your VCS provider. + +Instead, one of your organization's other tools is in charge of deciding when configuration has changed and a run should occur. Usually this is something like a CI system, or something else capable of monitoring changes to your Terraform code and performing actions in response. + +Once your other tooling has decided a run should occur, it must make a series of calls to HCP Terraform's `runs` and `configuration-versions` APIs to upload configuration files and perform a run with them. For the exact series of API calls, see the [pushing a new configuration version](#pushing-a-new-configuration-version) section. + +The most significant difference in this workflow is that HCP Terraform _does not_ fetch configuration files from version control. Instead, your own tooling must upload the configurations as a `.tar.gz` file. This allows you to work with configurations from unsupported version control systems, automatically generate Terraform configurations from some other source of data, or build a variety of other integrations. + +~> **Important:** The script below is provided to illustrate the run process, and is not intended for production use. If you want to drive HCP Terraform runs from the command line, please see the [CLI-driven run workflow](/terraform/enterprise/run/cli). + +## Pushing a New Configuration Version + +Pushing a new configuration to an existing workspace is a multi-step process. This section walks through each step in detail, using an example bash script to illustrate. + +You need queue plans permission to create new configuration versions for the workspace. Refer to the [permissions](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) documentation for more details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### 1. Define Variables + +To perform an upload, a few user parameters must be set: + +- **path_to_content_directory** is the folder with the terraform configuration. There must be at least one `.tf` file in the root of this path. +- **organization** is the organization name (not ID) for your HCP Terraform organization. +- **workspace** is the workspace name (not ID) in the HCP Terraform organization. +- **$TOKEN** is the API Token used for [authenticating with the HCP Terraform API](/terraform/enterprise/api-docs#authentication). + +This script extracts the `path_to_content_directory`, `organization`, and `workspace` from command line arguments, and expects the `$TOKEN` as an environment variable. + +```bash +#!/bin/bash + +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Usage: $0 /" + exit 0 +fi + +CONTENT_DIRECTORY="$1" +ORG_NAME="$(cut -d'/' -f1 <<<"$2")" +WORKSPACE_NAME="$(cut -d'/' -f2 <<<"$2")" +``` + +### 2. Create the File for Upload + +The [configuration version API](/terraform/enterprise/api-docs/configuration-versions) requires a `tar.gz` file to use the configuration version for a run, so you must package the directory containing the Terraform configuration into a `tar.gz` file. + +~> **Important:** The configuration directory must be the root of the tar file, with no intermediate directories. In other words, when the tar file is extracted the result must be paths like `./main.tf` rather than `./terraform-appserver/main.tf`. + +```bash +UPLOAD_FILE_NAME="./content-$(date +%s).tar.gz" +tar -zcvf "$UPLOAD_FILE_NAME" -C "$CONTENT_DIRECTORY" . +``` + +### 3. Look Up the Workspace ID + +The first step identified the organization name and the workspace name; however, the [configuration version API](/terraform/enterprise/api-docs/configuration-versions) expects the workspace ID. As such, the ID has to be looked up. If the workspace ID is already known, this step can be skipped. This step uses the [`jq` tool](https://stedolan.github.io/jq/) to parse the JSON output and extract the ID value into the `WORKSPACE_ID` variable. + +```bash +WORKSPACE_ID=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/$ORG_NAME/workspaces/$WORKSPACE_NAME \ + | jq -r '.data.id')) +``` + +### 4. Create a New Configuration Version + +Before uploading the configuration files, you must create a `configuration-version` to associate uploaded content with the workspace. This API call performs two tasks: it creates the new configuration version and it extracts the upload URL to be used in the next step. + +```bash +echo '{"data":{"type":"configuration-versions"}}' > ./create_config_version.json + +UPLOAD_URL=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @create_config_version.json \ + https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/configuration-versions \ + | jq -r '.data.attributes."upload-url"')) +``` + +### 5. Upload the Configuration Content File + +Next, upload the configuration version `tar.gz` file to the upload URL extracted from the previous step. If a file is not uploaded, the configuration version will not be usable, since it will have no Terraform configuration files. + +HCP Terraform automatically creates a new run with a plan once the new file is uploaded. If the workspace is configured to auto-apply, it will also apply if the plan succeeds; otherwise, an apply can be triggered via the [Run Apply API](/terraform/enterprise/api-docs/run#apply). If the API token used for the upload lacks permission to apply runs for the workspace, the run can't be auto-applied. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +```bash +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @"$UPLOAD_FILE_NAME" \ + $UPLOAD_URL +``` + +### 6. Delete Temporary Files + +In the previous steps a few files were created; they are no longer needed, so they should be deleted. + +```bash +rm "$UPLOAD_FILE_NAME" +rm ./create_config_version.json +``` + +### Complete Script + +Combine all of the code blocks into a single file, `./terraform-enterprise-push.sh` and give execution permission to create a combined bash script to perform all of the operations. + +```shell +chmod +x ./terraform-enterprise-push.sh +./terraform-enterprise-push.sh ./content my-organization/my-workspace +``` + +**Note**: This script does not have error handling, so for a more robust script consider adding error checking. + +**`./terraform-enterprise-push.sh`:** + +```bash +#!/bin/bash + +# Complete script for API-driven runs. + +# 1. Define Variables + +if [ -z "$1" ] || [ -z "$2" ]; then + echo "Usage: $0 /" + exit 0 +fi + +CONTENT_DIRECTORY="$1" +ORG_NAME="$(cut -d'/' -f1 <<<"$2")" +WORKSPACE_NAME="$(cut -d'/' -f2 <<<"$2")" + +# 2. Create the File for Upload + +UPLOAD_FILE_NAME="./content-$(date +%s).tar.gz" +tar -zcvf "$UPLOAD_FILE_NAME" -C "$CONTENT_DIRECTORY" . + +# 3. Look Up the Workspace ID + +WORKSPACE_ID=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + https://app.terraform.io/api/v2/organizations/$ORG_NAME/workspaces/$WORKSPACE_NAME \ + | jq -r '.data.id')) + +# 4. Create a New Configuration Version + +echo '{"data":{"type":"configuration-versions"}}' > ./create_config_version.json + +UPLOAD_URL=($(curl \ + --header "Authorization: Bearer $TOKEN" \ + --header "Content-Type: application/vnd.api+json" \ + --request POST \ + --data @create_config_version.json \ + https://app.terraform.io/api/v2/workspaces/$WORKSPACE_ID/configuration-versions \ + | jq -r '.data.attributes."upload-url"')) + +# 5. Upload the Configuration Content File + +curl \ + --header "Content-Type: application/octet-stream" \ + --request PUT \ + --data-binary @"$UPLOAD_FILE_NAME" \ + $UPLOAD_URL + +# 6. Delete Temporary Files + +rm "$UPLOAD_FILE_NAME" +rm ./create_config_version.json +``` + +## Advanced Use Cases + +For advanced use cases refer to the [Terraform Enterprise Automation Script](https://github.com/hashicorp/terraform-guides/tree/master/operations/automation-script) repository for automating interactions with HCP Terraform, including the creation of a workspace, uploading code, setting variables, and triggering the `plan` and `apply` operations. + +In addition to uploading configurations and starting runs, you can use HCP Terraform's APIs to create and modify workspaces, edit variable values, and more. See the [API documentation](/terraform/enterprise/api-docs) for more details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/cli.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/cli.mdx new file mode 100644 index 0000000000..87c74d475f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/cli.mdx @@ -0,0 +1,299 @@ +--- +page_title: The CLI-driven remote run workflow for Terraform Enterprise +description: >- + Configure the Terraform CLI to trigger remote runs in Terraform Enterprise + from your terminal. +source: terraform-docs-common +--- + +[private]: /terraform/enterprise/registry + +[speculative plan]: /terraform/enterprise/run/remote-operations#speculative-plans + +[tfe-provider]: https://registry.terraform.io/providers/hashicorp/tfe/latest/docs + +# The CLI-driven remote run workflow + +> **Hands-on:** Try the [Log in to HCP Terraform from the CLI](/terraform/tutorials/0-13/cloud-login) tutorial. + +HCP Terraform has three workflows for managing Terraform runs. + +- The [UI/VCS-driven run workflow](/terraform/enterprise/run/ui), which is the primary mode of operation. +- The [API-driven run workflow](/terraform/enterprise/run/api), which is more flexible but requires you to create some tooling. +- The CLI-driven run workflow described below, which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +## Summary + +The [CLI integration](/terraform/cli/cloud) brings HCP Terraform's collaboration features into the familiar Terraform CLI workflow. It offers the best of both worlds to developers who are already comfortable with using the Terraform CLI, and it can work with existing CI/CD pipelines. + +You can start runs with the standard `terraform plan` and `terraform apply` commands and then watch the progress of the run from your terminal. These runs execute remotely in HCP Terraform, use variables from the appropriate workspace, enforce any applicable [Sentinel or OPA policies](/terraform/enterprise/policy-enforcement), and can access HCP Terraform's [private registry][private] and remote state inputs. + +HCP Terraform offers a few types of CLI-driven runs, to support different stages of your workflow: + +- `terraform plan` starts a [speculative plan][] in an HCP Terraform workspace, using configuration files from a local directory. You can quickly check the results of edits (including compliance with Sentinel policies) without needing to copy sensitive variables to your local machine. + + Speculative plans work with all workspaces, and can co-exist with the [VCS-driven workflow](/terraform/enterprise/run/ui). + +- `terraform apply` starts a standard plan and apply in an HCP Terraform workspace, using configuration files from a local directory. + + Remote `terraform apply` is for workspaces without a linked VCS repository. It replaces the VCS-driven workflow with a more traditional CLI workflow. + +- `terraform plan -out ` and `terraform apply ` perform a two-part [saved plan run](/terraform/enterprise/run/modes-and-options/#saved-plans) in an HCP Terraform workspace, using configuration files from a local directory. The first command performs and saves the plan, and the second command applies it. You can use `terraform show ` to inspect a saved plan. + + Like remote `terraform apply`, remote saved plans are for workspaces without a linked VCS repository. + + Saved plans require at least Terraform CLI v1.6.0. + +To supplement these remote operations, you can also use the optional [Terraform Enterprise Provider][tfe-provider], which interacts with the HCP Terraform-supported resources. This provider is useful for editing variables and workspace settings through the Terraform CLI. + +## Configuration + +To enable the CLI-driven workflow, you must: + +1. Create an account or sign in to [HCP Terraform](https://app.terraform.io/). + +2. Run `terraform login` to authenticate with HCP Terraform. Alternatively, you can manually configure credentials in the CLI config file or through environment variables. Refer to [CLI Configuration](/terraform/cli/config/config-file#environment-variable-credentials) for details. + +3. Add the `cloud` block to your Terraform configuration. You can define its arguments directly in your configuration file or supply them through environment variables, which can be useful for [non-interactive workflows](#non-interactive-workflows). Refer to [Using HCP Terraform](/terraform/cli/cloud) for configuration details. + + The following example shows how to map CLI workspaces to HCP Terraform workspaces with a specific tag. + + terraform { + cloud { + organization = "my-org" + workspaces { + tags = ["networking"] + } + } + } + + -> **Note:** The `cloud` block is available in Terraform v1.1 and later. Previous versions can use the [`remote` backend](/terraform/language/settings/backends/remote) to configure the CLI workflow and migrate state. + +4. Run `terraform init`. + + $ terraform init + + Initializing HCP Terraform... + + Initializing provider plugins... + - Reusing previous version of hashicorp/random from the dependency lock file + - Using previously-installed hashicorp/random v3.0.1 + + HCP Terraform has been successfully initialized! + + You may now begin working with HCP Terraform. Try running "terraform plan" + to see any changes that are required for your infrastructure. + + If you ever set or change modules or Terraform Settings, + run "terraform init" again to reinitialize your working directory. + +### Implicit Workspace Creation + +If you configure the `cloud` block to use a workspace that doesn't yet exist in your organization, HCP Terraform will create a new workspace with that name when you run `terraform init`. The output of `terraform init` will inform you when this happens. + +Automatically created workspaces might not be immediately ready to use, so use HCP Terraform's UI to check a workspace's settings and data before performing any runs. In particular, note that: + +- No Terraform variables or environment variables are created by default, unless your organization has configured one or more [global variable sets](/terraform/enterprise/workspaces/variables#scope). HCP Terraform will use `*.auto.tfvars` files if they are present, but you will usually still need to set some workspace-specific variables. +- The execution mode defaults to "Remote," so that runs occur within HCP Terraform's infrastructure instead of on your workstation. +- New workspaces are not automatically connected to a VCS repository and do not have a working directory specified. +- A new workspace's Terraform version defaults to the most recent release of Terraform at the time the workspace was created. + +### Implicit Project Creation + +If you configure the [`workspaces` block](/terraform/cli/cloud/settings#workspaces) to use a [project](/terraform/cli/cloud/settings#project) that does not yet exist in your organization, HCP Terraform will attempt to create a new project with that name when you run `terraform init` and notify you in the command output. + +If you specify both the `project` argument and [`TF_CLOUD_PROJECT`](/terraform/cli/cloud/settings#tf_cloud_project) environment variable, the `project` argument takes precedence. + +## Variables in CLI-Driven Runs + +Remote runs in HCP Terraform use: + +- Run-specific variables set through the command line or in your local environment. Terraform can use shell environment variables prefixed with `TF_VAR_` as input variables for the run, but you must still set all required environment variables, like provider credentials, inside the workspace. +- Workspace-specific Terraform and environment variables set in the workspace. +- Any variable sets applied globally, on the project containing the workspace, or on the workspace itself. +- Terraform variables from any `*.auto.tfvars` files included in the configuration. + +Refer to [Variables](/terraform/enterprise/workspaces/variables) for more details about variable types, variable scopes, variable precedence, and how to set run-specific variables through the command line. + +## Remote Working Directories + +If you manage your Terraform configurations in self-contained repositories, the remote working directory always has the same content as the local working directory. + +If you use a combined repository and [specify a working directory on workspaces](/terraform/enterprise/workspaces/settings#terraform-working-directory), you can run Terraform from either the real working directory or from the root of the combined configuration directory. In both cases, Terraform will upload the entire combined configuration directory. + +## Excluding Files from Upload + +-> **Version note:** `.terraformignore` support was added in Terraform 0.12.11. + +CLI-driven runs upload an archive of your configuration directory +to HCP Terraform. If the directory contains files you want to exclude from upload, +you can do so by defining a [`.terraformignore` file in your configuration directory](/terraform/cli/cloud/settings). + +## Remote Speculative Plans + +You can run speculative plans in any workspace where you have [permission to queue plans](/terraform/enterprise/users-teams-organizations/permissions). Speculative plans use the configuration code from the local working directory, but will use variable values from the specified workspace. + +To run a [speculative plan][] on your configuration, use the `terraform plan` command. The plan will run in HCP Terraform, and the logs will stream back to the command line along with a URL to view the plan in the HCP Terraform UI. + + $ terraform plan + + Running plan in HCP Terraform. Output will stream here. Pressing Ctrl-C + will stop streaming the logs, but will not stop the plan running remotely. + + Preparing the remote plan... + + To view this run in a browser, visit: + https://app.terraform.io/app/hashicorp-learn/docs-workspace/runs/run-cfh2trDbvMU2Rkf1 + + Waiting for the plan to start... + + [...] + + Plan: 1 to add, 0 to change, 0 to destroy. + + Changes to Outputs: + + pet_name = (known after apply) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Remote Applies + +In workspaces that are not connected to a VCS repository, users with [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) can use the CLI to trigger remote applies. Remote applies use the configuration code from the local working directory, but use the variable values from the specified workspace. + +~> **Note:** You cannot run remote applies in workspaces that are linked to a VCS repository, since the repository serves as the workspace’s source of truth. To apply changes in a VCS-linked workspace, merge your changes to the designated branch. + +When you are ready to apply configuration changes, use the `terraform apply` command. HCP Terraform will plan your changes, and the command line will prompt you for approval before applying them. + + $ terraform apply + + Running apply in HCP Terraform. Output will stream here. Pressing Ctrl-C + will cancel the remote apply if it's still pending. If the apply started it + will stop streaming the logs, but will not stop the apply running remotely. + + Preparing the remote apply... + + To view this run in a browser, visit: + https://app.terraform.io/app/hashicorp-learn/docs-workspace/runs/run-Rcc12TkNW1PDa7GH + + Waiting for the plan to start... + + [...] + + Plan: 1 to add, 0 to change, 0 to destroy. + + Changes to Outputs: + + pet_name = (known after apply) + + Do you want to perform these actions in workspace "docs-workspace"? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. + + Enter a value: yes + + [...] + + Apply complete! Resources: 1 added, 0 changed, 0 destroyed. + +### Non-Interactive Workflows + +> **Hands On:** Try the [Deploy Infrastructure with HCP Terraform and CircleCI](/terraform/tutorials/automation/circle-ci) tutorial. + +External systems cannot run the traditional apply workflow because Terraform requires console input from the user to approve plans. We recommend using the [API-driven Run Workflow](/terraform/enterprise/run/api) for non-interactive workflows when possible. + +If you prefer to use the CLI in a non-interactive environment, we recommend first running a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) to preview the changes Terraform will make to your infrastructure. Then, use one of the following approaches with the `-auto-approve` flag based on the [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) of your workspace. The [`-auto-approve`](/terraform/cli/commands/apply#auto-approve) flag skips prompting you to approve the plan. + +- **Local Execution:** Save the approved speculative plan and then run `terraform apply -auto-approve` with the saved plan. +- **Remote Execution:** HCP Terraform does not support uploading saved plans for remote execution, so we recommend running `terraform apply -auto-approve` immediately after approving the speculative plan to prevent the plan from becoming stale. + + !> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize the risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Remote Saved Plans + +-> **Version note:** Saved plans require at least Terraform CLI v1.6.0. + +In workspaces that support `terraform apply`, you also have the option of performing the plan and apply as separate steps, using the standard variations of the relevant Terraform commands: + +- `terraform plan -out ` performs and saves a plan. +- `terraform apply ` applies a previously saved plan. +- `terraform show ` (and `terraform show -json `) inspect a plan you previously saved. + +Saved plan runs are halfway between [speculative plans](#remote-speculative-plans) and standard [plan and apply runs](#remote-applies). They allow you to: + +- Perform cheap exploratory plans while retaining the option of applying a specific plan you are satisfied with. +- Perform other tasks in your terminal between the plan and apply stages. +- Perform the plan and apply operations on separate machines (as is common in continuous integration workflows). + +Saved plans become _stale_ once the state Terraform planned them against is no longer valid (usually due to someone applying a different run). In HCP Terraform, stale saved plan runs are automatically detected and discarded. When examining a remote saved plan, the `terraform show` command (without the `-json` option) informs you if a plan has been discarded or is otherwise unable to be applied. + +### File Contents and Permissions + +You can only apply remote saved plans in the same remote HCP Terraform workspace that performed the plan. Additionally, you can not apply locally executed saved plans in a remote workspace. + +In order to abide by HCP Terraform's permissions model, remote saved plans do not use the same local file format as locally executed saved plans. Instead, remote saved plans are a thin reference to a remote run, and the Terraform CLI relies on authenticated network requests to inspect and apply remote plans. This helps avoid the accidental exposure of credentials or other sensitive information. + +The `terraform show -json` command requires [workspace admin permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) to inspect a remote saved plan; this is because the [machine-readable JSON plan format](/terraform/internals/json-format) contains unredacted sensitive information (alongside redaction hints for use by systems that consume the format). The human-readable version of `terraform show` only requires the read runs permission, because it uses pre-redacted information. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Policy Enforcement + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policies are rules that HCP Terraform enforces on Terraform runs. You can use two policy-as-code frameworks to define fine-grained, logic-based policies: Sentinel and Open Policy Agent (OPA). + +If the specified workspace uses policies, HCP Terraform runs those policies against all speculative plans and remote applies in that workspace. Failed policies can pause or prevent an apply, depending on the enforcement level. Refer to [Policy Enforcement](/terraform/enterprise/policy-enforcement) for details. + +For Sentinel, the Terraform CLI prints policy results for CLI-driven runs. CLI support for policy results is not available for OPA. + +The following example shows Sentinel policy output in the terminal. + + $ terraform apply + + [...] + + Plan: 1 to add, 0 to change, 1 to destroy. + + ------------------------------------------------------------------------ + + Organization policy check: + + Sentinel Result: false + + Sentinel evaluated to false because one or more Sentinel policies evaluated + to false. This false was not due to an undefined value or runtime error. + + 1 policies evaluated. + ## Policy 1: my-policy.sentinel (soft-mandatory) + + Result: false + + FALSE - my-policy.sentinel:1:1 - Rule "main" + + Do you want to override the soft failed policy check? + Only 'override' will be accepted to override. + + Enter a value: override + +## Options for Plans and Applies + +[Run Modes and Options](/terraform/enterprise/run/modes-and-options) contains more details about the various options available for plans and applies when you use the CLI-driven workflow. + +## Networking/Connection Issues + +Sometimes during a CLI-driven run, errors relating to network connectivity issues arise. Examples of these kinds of errors include: + +- `Client.Timeout exceeded while awaiting headers` +- `context deadline exceeded` +- `TLS handshake timeout` + +Sometimes there are network problems beyond our control. If you have network errors, verify your network connection is operational. Then, check the following common configuration settings: + +- Determine if any firewall software on your system blocks the `terraform` command and explicitly approve it. +- Verify that you have a valid DNS server IP address. +- Remove any expired TLS certificates for your system. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/install-software.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/install-software.mdx new file mode 100644 index 0000000000..31ff8d5b1c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/install-software.mdx @@ -0,0 +1,111 @@ +--- +page_title: Install software in the HCP Terrafrom run environment +description: >- + Learn how to install Terraform providers, cloud CLIs, or configuration + management tools and software on Terraform Enterprise workers. +source: terraform-docs-common +--- + +# Install software in the run environment + +Terraform relies on provider plugins to manage resources. In most cases, Terraform can automatically download the required plugins, but there are cases where plugins must be managed explicitly. + +In rare cases, it might also be necessary to install extra software on the Terraform worker, such as a configuration management tool or cloud CLI. + +## Installing Terraform Providers + +The mechanics of provider installation changed in Terraform 0.13, thanks to the introduction of the [Terraform Registry][registry] for providers which allows custom and community providers to be installed via `terraform init`. Prior to Terraform 0.13, Terraform could only automatically install providers distributed by HashiCorp. + +### Terraform 0.13 and later + +#### Providers From the Terraform Registry + +The [Terraform Registry][registry] allows anyone to publish and distribute providers which can be automatically downloaded and installed via `terraform init`. + +Terraform Enterprise instances must be able to access `registry.terraform.io` to use providers from the public registry; otherwise, you can install providers using [the `terraform-bundle` tool][bundle]. + +[registry]: https://registry.terraform.io/browse/providers + +#### In-House Providers + +If you have a custom provider that you'd rather not publish in the public Terraform Registry, you have a few options: + +- Add the provider binary to the VCS repo (or manually-uploaded configuration version). Place the compiled `linux_amd64` version of the plugin at `terraform.d/plugins/////linux_amd64`, relative to the root of the directory. + + The source host and namespace will need to match the source given in the `required_providers` block within the configuration, but can otherwise be arbitrary identifiers. For instance, if your `required_providers` block looks like this: + + terraform { + required_providers { + custom = { + source = "my-host/my-namespace/custom" + version = "1.0.0" + } + } + } + + HCP Terraform will be able to use your compiled provider if you place it at `terraform.d/plugins/my-host/my-namespace/custom/1.0.0/linux_amd64/terraform-provider-custom`. + +- Use a privately-owned provider registry service which implements the [provider registry protocol](/terraform/internals/provider-registry-protocol) to distribute custom providers. Be sure to include the full [source address](/terraform/language/providers/requirements#source-addresses), including the hostname, when referencing providers. + +- **Terraform Enterprise only:** Use [the `terraform-bundle` tool][bundle] to add custom providers. + +-> **Note:** Using a [network mirror](/terraform/internals/provider-network-mirror-protocol) to host custom providers for installation is not currently supported in HCP Terraform, since the network mirror cannot be activated without a [`provider_installation`](/terraform/cli/config/config-file#explicit-installation-method-configuration) block in the CLI configuration file. + +### Terraform 0.12 and earlier + +#### Providers Distributed by HashiCorp + +HCP Terraform can automatically install providers distributed by HashiCorp. Terraform Enterprise instances can do this as well as long as they can access `releases.hashicorp.com`. + +If that isn't feasible due to security requirements, you can manually install providers. Use [the `terraform-bundle` tool][bundle] to build a custom version of Terraform that includes the necessary providers, and configure your workspaces to use that bundled version. + +[bundle]: https://github.com/hashicorp/terraform/tree/master/tools/terraform-bundle#installing-a-bundle-in-on-premises-terraform-enterprise + +#### Custom and Community Providers + +To use community providers or your own custom providers with Terraform versions prior to 0.13, you must install them yourself. + +There are two ways to accomplish this: + +- Add the provider binary to the VCS repo (or manually-uploaded configuration version) for any workspace that uses it. Place the compiled `linux_amd64` version of the plugin at `terraform.d/plugins/linux_amd64/` (as a relative path from the root of the working directory). The plugin name should follow the [naming scheme](/terraform/language/v1.1.x/configuration-0-11/providers#plugin-names-and-versions) and the plugin file must have read and execute permissions. (Third-party plugins are often distributed with an appropriate filename already set in the distribution archive.) + + You can add plugins directly to a configuration repo, or you can add them as Git submodules and symlink the executable files into `terraform.d/plugins/`. Submodules are a good choice when many workspaces use the same custom provider, since they keep your repos smaller. If using submodules, enable the ["Include submodules on clone" setting](/terraform/enterprise/workspaces/settings/vcs#include-submodules-on-clone) on any affected workspace. + +- **Terraform Enterprise only:** Use [the `terraform-bundle` tool][bundle] to add custom providers to a custom Terraform version. This keeps custom providers out of your configuration repos entirely, and is easier to update when many workspaces use the same provider. + +## Installing Additional Tools + +### Avoid Installing Extra Software + +Whenever possible, don't install software on the worker. There are a number of reasons for this: + +- Provisioners are a last resort in Terraform; they greatly increase the risk of creating unknown states with unmanaged and partially-managed infrastructure, and the `local-exec` provisioner is especially hazardous. [The Terraform CLI docs on provisioners](/terraform/language/resources/provisioners/syntax#provisioners-are-a-last-resort) explain the hazards in more detail, with more information about the preferred alternatives. (In summary: use Packer, use cloud-init, try to make your infrastructure more immutable, and always prefer real provider features.) +- We don't guarantee the stability of the operating system on the Terraform build workers. It's currently the latest version of Ubuntu LTS, but we reserve the right to change that at any time. +- The build workers are disposable and are destroyed after each use, which makes managing extra software even more complex than when running Terraform CLI in a persistent environment. Custom software must be installed on every run, which also increases run times. + +### Only Install Standalone Binaries + +HCP Terraform does not allow you to elevate a command's permissions with `sudo` during Terraform runs. This means you cannot install packages using the worker OS's normal package management tools. However, you can install and execute standalone binaries in Terraform's working directory. + +You have two options for getting extra software into the configuration directory: + +- Include it in the configuration repository as a submodule. (Make sure the workspace is configured to clone submodules.) +- Use `local-exec` to download it with `curl`. For example: + + ```hcl + resource "aws_instance" "example" { + ami = "${var.ami}" + instance_type = "t2.micro" + provisioner "local-exec" { + command = < **Note:** Terraform Enterprise instances can be configured to allow `sudo` commands during Terraform runs. However, even when `sudo` is allowed, using the worker OS's package tools during runs is still usually a bad idea. You will have a much better experience if you can move your provisioner actions into a custom provider or an immutable machine image. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/manage.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/manage.mdx new file mode 100644 index 0000000000..2594b81dae --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/manage.mdx @@ -0,0 +1,78 @@ +--- +page_title: Manage and view runs in Terraform Enterprise +description: >- + Learn how to view and interact with runs in Terraform Enterprise, and how to + unlock and lock workspaces to prevent new runs. +source: terraform-docs-common +--- + +# Manage and view runs + +Each workspace in HCP Terraform includes a list of its current, pending, and historical runs. You can view and interact with these runs in the UI. You can also lock workspaces to temporarily prevent new runs. + +## API + +Refer to the [Runs API](/terraform/enterprise/api-docs/run) and [lock a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#lock-a-workspace). + +## Navigating Runs + +Go to the workspace and click the **Runs** tab to review a list of all current and past Terraform runs. + +Click a run to go to its details page. The details page contains the following information: + +- The current status of the run. +- The code commit associated with the run. +- How the run initiated, when, and which user initiated it (if applicable). +- A timeline of events related to the run. +- The output from both the `terraform plan` and `terraform apply` commands, if applicable. This output defaults to visible if the command is currently running and hidden if the command has finished. + +## Interacting with Runs + +In workspaces where you have [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions), you can interact with a run at the bottom of its details page. + +The following options are available, depending on the state of the run: + +| Button | Available when: | +| ------------------- | --------------------------------------------------------------------------------------------------------------- | +| Add Comment | Always. | +| Confirm & Apply | A plan needs confirmation. | +| Override & Continue | A soft-mandatory policy failed. Requires permission to manage policy overrides for the organization. | +| Discard Run | A plan needs confirmation or a soft-mandatory policy failed. | +| Cancel Run | A plan or apply is currently running. | +| Force Cancel Run | A plan or apply canceled, but HCP Terraform was unable to end the run. Requires admin access to the workspace. | +| Retry Run | A plan-only run has finished. You can also change which Terraform version to use when retrying a plan-only run. | + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If a plan needs confirmation (with [manual apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) enabled) or a soft-mandatory policy failed, the run remains paused until a user with appropriate permissions uses these buttons to continue or discard the run. Refer to [Run States and Stages](/terraform/enterprise/run/states) for more details. + +### Canceling Runs + +If a run is currently planning or applying, users with [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) for the workspace can click **Cancel Run** to stop the run before it finishes. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Canceling a run is roughly equivalent to typing `ctrl+c` during a Terraform plan or apply on the CLI. The running Terraform process is sent an INT signal, which instructs Terraform to end its work, update state for any resources that have already been changed, and wrap up in the safest way possible. + +In rare cases, a canceled run can fail to end, continuing to lock the workspace. You can forcefully cancel these runs, which immediately terminates the running Terraform process and unlocks the workspace. + +Force-canceling requires admin access to the workspace because it can have dangerous side-effects, including loss of state and orphaned resources. Additionally, the **Force Cancel Run** button only appears after you click **Cancel Run** and HCP Terraform has time to terminate the run safely. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Locking Workspaces (Preventing Runs) + +You can lock the workspace to temporarily stop runs from proceeding. Locking a workspace requires [permission to lock and unlock the workspace](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions), and requires that the workspace is not currently locked by an in-progress run. + +A lock prevents HCP Terraform from performing any applies in the workspace, and also prevents many kinds of plans. New runs remain in the **Pending** state until the workspace unlocks. + +Locking **does not** affect [plan-only runs](/terraform/enterprise/run/remote-operations#speculative-plans) or the planning stages of [saved plan runs](/terraform/enterprise/run/cli#remote-saved-plans). Terraform allows these types of runs because they can not affect infrastructure resources, do not attempt to lock the workspace themselves, and might provide important information about tasks to perform before removing the lock. Note that you can not _apply_ saved-plan runs while the workspace is locked, and HCP Terraform automatically discards these runs if the workspace's state is changed before they can be applied. Terraform Enterprise does not yet support saved plans. + +HCP Terraform shows the lock status in the workspace's header, next to the **Actions** menu. + +To lock or unlock a workspace, do one of the following: + +- Open the **Actions** menu and select **Lock workspace** or **Unlock workspace**. +- Go to **Settings > Locking**. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/modes-and-options.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/modes-and-options.mdx new file mode 100644 index 0000000000..9a1e6a0f8d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/modes-and-options.mdx @@ -0,0 +1,123 @@ +--- +page_title: Run modes and options in Terraform Enterprise +description: >- + Learn about the different run modes and options available in Terraform + Enterprise to customize behavior during runs. +source: terraform-docs-common +--- + +# Run modes and options + +HCP Terraform runs support many of the same modes and options available in the Terraform CLI. + +## 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 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. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Plan and apply (standard)** as the run type. +- **VCS:** When a workspace is connected to a VCS repository, HCP Terraform automatically starts a standard plan and apply when you add new commits to the selected branch of that repository. + +## Destroy Mode + +[Destroy mode](/terraform/cli/commands/plan#planning-modes) instructs Terraform to create a plan which destroys all objects, regardless of configuration changes. + +- **CLI:** Use `terraform plan -destroy` or `terraform destroy` +- **API:** Use the `is-destroy` option. +- **UI:** Use a workspace's **Destruction and Deletion** settings page. + +## Plan Only/Speculative Plan + +This option creates a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans). The speculative plan shows a set of possible changes and checks them against Sentinel policies, but Terraform can _not_ apply this plan. + +You can create speculative plans with a different Terraform version than the one currently selected for a workspace. This lets you check whether your configuration is compatible with a newer Terraform version without changing the workspace settings. + +Plan-only runs ignore the per-workspace run queue. Plan-only runs can proceed even if another run is in progress, can not become the workspace's current run, and do not block progress on a workspace's other runs. + +- **API:** Set the `plan-only` option to `true` and specify an available terraform version using the `terraform-version` field. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Plan only** as the run type. +- **VCS:** When a workspace is connected to a VCS repository, HCP Terraform automatically starts a speculative plan when someone opens a pull request (or merge request) against the selected branch of that repository. The pull/merge request view in your VCS links to the speculative plan, and you can also find it in the workspace's run list. + +## Saved Plans + +-> **Version note:** Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0. + +Saved plan runs are very similar to standard plan and apply runs: they perform a plan and then optionally apply it. There are three main differences: + +1. _No wait for planning._ Saved plan runs ignore the per-workspace run queue during their plan and checks. Like plan-only runs, saved plans can begin planning even if another run is in progress, without blocking progress on other runs. +2. _No auto-apply._ Saved plan runs are never auto-applied, even if you enabled auto-apply for the workspace. Saved plans only apply if you confirm them. +3. _Automatic discard for stale plans._ If another run is applied (or the state is otherwise modified) before a saved plan run is confirmed, HCP Terraform automatically discards that saved plan. HCP Terraform may also automatically discard saved plans if they are not confirmed within a few weeks. + +Saved plans are ideal for interactive CLI workflows, where you can perform many exploratory plans and then choose one to apply, or for custom continuous integration workflows where the default run queue behavior isn't suitable. + +- **CLI:** Use `terraform plan -out ` to perform and save a plan, then use `terraform apply ` to apply the saved plan. Use `terraform show ` to inspect a saved plan before applying it. +- **API:** Use the `save-plan` option when creating a run. If you create a new configuration version for a saved plan run, use the `provisional` option so that it will not become the workspace's current configuration version until you decide to apply the run. + +## Allow Empty Apply + +A no-operation (empty) apply enables HCP Terraform to apply a run from a plan that contains no infrastructure changes. During apply, Terraform can upgrade the state version if required. You can use this option to upgrade the state in your HCP Terraform workspace to a new Terraform version. Only some Terraform versions require this, most notably 0.13. + +To make such upgrades easier, empty apply runs will always auto-apply if their plan contains no changes. + +~> **Warning:** HCP Terraform cannot guarantee that a plan in this mode will produce no changes. We recommend checking the plan for drift before proceeding to the apply stage. + +- **API:** Set the `allow-empty-apply` field to `true`. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Allow empty apply** as the run type. + +## Refresh-Only Mode + +> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. + +-> **Version note:** Refresh-only support requires a workspace using at least Terraform CLI v0.15.4. + +[Refresh-only mode](/terraform/cli/commands/plan#planning-modes) instructs Terraform to create a plan that updates the Terraform state to match changes made to remote objects outside of Terraform. This is useful if state drift has occurred and you want to reconcile your state file to match the drifted remote objects. Applying a refresh-only run does not result in further changes to remote objects. + +- **CLI:** Use `terraform plan -refresh-only` or `terraform apply -refresh-only`. +- **API:** Use the `refresh-only` option. +- **UI:** From the workspace's overview page, click **+ New run**, and then choose **Refresh state** as the run type. + +## Skipping Automatic State Refresh + +The [`-refresh=false` option](/terraform/cli/commands/plan#refresh-false) is used in normal planning mode to skip the default behavior of refreshing Terraform state before checking for configuration changes. + +- **CLI:** Use `terraform plan -refresh=false` or `terraform apply -refresh=false`. +- **API:** Use the `refresh` option. + +## Replacing Selected Resources + +-> **Version note:** Replace support requires a workspace using at least Terraform CLI v0.15.2. + +The [replace option](/terraform/cli/commands/plan#replace-address) instructs Terraform to replace the object with the given resource address. + +- **CLI:** Use `terraform plan -replace=ADDRESS` or `terraform apply -replace=ADDRESS`. +- **API:** Use the `replace-addrs` option. +- **UI:** Click **+ New run** and select the **Plan and apply (standard)** run type. Then click **Additional planning options** to reveal the **Replace resources** option. Type the address of the resource that you want to replace. You can replace multiple resources. + +## Targeted Plan and Apply + +[Resource Targeting](/terraform/cli/commands/plan#resource-targeting) is intended for exceptional circumstances only and should not be used routinely. + +- **CLI:** Use `terraform plan -target=ADDRESS` or `terraform apply -target=ADDRESS`. +- **API:** Use the `target-addrs` option. + +The usual caveats for targeting in local operations imply some additional limitations on HCP Terraform features for remote plans created with targeting: + +- [Sentinel](/terraform/enterprise/policy-enforcement) policy checks for targeted plans will see only the selected subset of resource instances planned for changes in [the `tfplan` import](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2) and [the `tfplan/v2` import](/terraform/enterprise/policy-enforcement/import-reference/tfplan-v2), which may cause an unintended failure for any policy that requires a planned change to a particular resource instance selected by its address. + +- [Cost Estimation](/terraform/enterprise/cost-estimation) is disabled for any run created with `-target` set, to prevent producing a misleading underestimate of cost due to resource instances being excluded from the plan. + +You can disable or constrain use of targeting in a particular workspace using a Sentinel policy based on [the `tfrun.target_addrs` value](/terraform/enterprise/policy-enforcement/import-reference/tfrun#value-target_addrs). + +## Generating Configuration + +-> **Version note:** Support for `import` blocks and generating configuration requires a workspace using at least Terraform CLI v1.5.0. + +When using [`import` blocks](/terraform/language/import) to import existing resources, Terraform can [automatically generate configuration](/terraform/language/import/generating-configuration) during the plan for any imported resources that don't have an existing `resource` block. This option is enabled by default for runs started from the UI or from a VCS webhook. + +- **CLI:** Use `terraform plan -generate-config-out=generated.tf`. +- **API:** Use the `allow-config-generation` option. + +You can find generated configuration displayed in the plan UI. If you're using the CLI workflow, Terraform will write generated configuration to the file you specify when running `terraform plan`. + +Once Terraform has generated configuration for you, you'll need to review it, incorporate it in your Terraform configuration (including committing it to version control), then run another plan. If you try to directly apply a plan with generated configuration, the run will error. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/remote-operations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/remote-operations.mdx new file mode 100644 index 0000000000..8091309a5e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/remote-operations.mdx @@ -0,0 +1,148 @@ +--- +page_title: Remote operations in Terraform Enterprise +description: >- + Terraform Enterprise runs Terraform operations remotely through the UI, API, + or CLI. Learn how HCP Terraform manages runs. +source: terraform-docs-common +--- + +# Remote operations + +> **Hands-on:** Try the [Get Started — HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. + +HCP Terraform provides a central interface for running Terraform within a large collaborative organization. If you're accustomed to running Terraform from your workstation, the way HCP Terraform manages runs can be unfamiliar. + +This page describes the basics of how runs work in HCP Terraform. + +## Remote Operations + +HCP Terraform is designed as an execution platform for Terraform, and can perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment, and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more. + +Terraform runs managed by HCP Terraform are called _remote operations._ Remote runs can be initiated by webhooks from your VCS provider, by UI controls within HCP Terraform, by API calls, or by Terraform CLI. When using Terraform CLI to perform remote operations, the progress of the run is streamed to the user's terminal, to provide an experience equivalent to local operations. + +### Disabling Remote Operations + +[execution_mode]: /terraform/enterprise/workspaces/settings#execution-mode + +Many of HCP Terraform's features rely on remote execution and are not available when using local operations. This includes features like Sentinel policy enforcement, cost estimation, and notifications. + +You can disable remote operations for any workspace by changing its [Execution Mode][execution_mode] to **Local**. This causes the workspace to act only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers. + +### Protecting Private Environments + +[HCP Terraform agents](/terraform/cloud-docs/agents) are a paid feature that allows HCP Terraform to communicate with isolated, private, or on-premises infrastructure. The agent polls HCP Terraform or Terraform Enterprise for any changes to your configuration and executes the changes locally, so you do not need to allow public ingress traffic to your resources. Agents allow you to control infrastructure in private environments without modifying your network perimeter. + +HCP Terraform agents also support running custom programs, called _hooks_, during strategic points of a Terraform run. For example, you may create a hook to dynamically download software required by the Terraform run or send an HTTP request to a system to kick off an external workflow. + +## Runs and Workspaces + +HCP Terraform always performs Terraform runs in the context of a [workspace](/terraform/enterprise/run/remote-operations). The workspace serves the same role that a persistent working directory serves when running Terraform locally: it provides the configuration, state, and variables for the run. + +### Configuration Versions + +Each workspace is associated with a particular Terraform configuration, but that configuration is expected to change over time. Thus, HCP Terraform manages configurations as a series of _configuration versions._ + +Most commonly, a workspace is linked to a VCS repository, and its configuration versions are tied to revisions in the specified VCS branch. In workspaces that aren't linked to a repository, new configuration versions can be uploaded via Terraform CLI or via the API. + +### Ordering and Timing + +Each workspace in HCP Terraform maintains its own queue of runs, and processes those runs in order. + +Whenever a new run is initiated, it's added to the end of the queue. If there's already a run in progress, the new run won't start until the current one has completely finished — HCP Terraform won't even plan the run yet, because the current run might change what a future run would do. Runs that are waiting for other runs to finish are in a _pending_ state, and a workspace might have any number of pending runs. + +There are two exceptions to the run queue, which can proceed at any time and do not block the progress of other runs: + +- Plan-only runs. +- The planning stages of [saved plan runs](/terraform/enterprise/run/modes-and-options/#saved-plans). You can only _apply_ a saved plan if no other run is in progress, and applying that plan blocks the run queue as usual. Terraform Enterprise does not yet support this workflow. + +When you initiate a run, HCP Terraform locks the run to a particular configuration version and set of variable values. If you change variables or commit new code before the run finishes, it will only affect future runs, not runs that are already pending, planning, or awaiting apply. + +### Workspace Locks + +When a workspace is _locked,_ HCP Terraform can create new runs (automatically or manually), but those runs do not begin until you unlock the workspace. + +When a run is in progress, that run locks the workspace, as described above under "Ordering and Timing". + +There are two kinds of run operation that can ignore workspace locking: + +- Plan-only runs. +- The planning stages of [saved plan runs](/terraform/enterprise/run/modes-and-options/#saved-plans). You can only _apply_ a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow. + +A user or team can also deliberately lock a workspace, to perform maintenance or for any other reason. For more details, see [Locking Workspaces (Preventing Runs)](/terraform/enterprise/run/manage#locking-workspaces-preventing-runs-). + +## Starting Runs + +HCP Terraform has three main workflows for managing runs, and your chosen workflow determines when and how Terraform runs occur. For detailed information, see: + +- The [UI/VCS-driven run workflow](/terraform/enterprise/run/ui), which is the primary mode of operation. +- The [API-driven run workflow](/terraform/enterprise/run/api), which is more flexible but requires you to create some tooling. +- The [CLI-driven run workflow](/terraform/enterprise/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +You can use the following methods to initiate HCP Terraform runs: + +- Click the **+ New run** button on the workspace's page +- Implement VCS webhooks +- Run the standard `terraform apply` command when the CLI integration is configured +- Call [the Runs API](/terraform/enterprise/api-docs/run) using any API tool + +## Plans and Applies + +HCP Terraform enforces Terraform's division between _plan_ and _apply_ operations. It always plans first, then uses that plan's output for the apply. + +In the default configuration, HCP Terraform waits for user approval before running an apply, but you can configure workspaces to [automatically apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) successful plans. Some plans can't be auto-applied, like plans queued by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) or by users without permission to apply runs for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If a plan contains no changes, HCP Terraform does not attempt to apply it. Instead, the run ends with a status of "Planned and finished". The [allow empty apply](/terraform/enterprise/run/modes-and-options#allow-empty-apply) run mode can override this behavior. + +### Speculative Plans + +In addition to normal runs, HCP Terraform can run _speculative plans_ to test changes to a configuration during editing and code review. Speculative plans are plan-only runs. They show possible changes, and policies affected by those changes, but cannot apply any changes. + +Speculative plans can begin without waiting for other runs to finish because they don't affect real infrastructure. HCP Terraform lists past speculative plan runs alongside a workspace's other runs. + +There are three ways to run speculative plans: + +- In VCS-backed workspaces, pull requests start speculative plans, and the VCS provider's pull request interface includes a link to the plan. See [UI/VCS Runs: Speculative Plans on Pull Requests](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) for more details. +- With the [CLI integration](/terraform/cli/cloud) configured, running `terraform plan` on the command line starts a speculative plan. The plan output streams to the terminal, and a link to the plan is also included. +- The runs API creates speculative plans whenever the specified configuration version is marked as speculative. See [the `configuration-versions` API](/terraform/enterprise/api-docs/configuration-versions#create-a-configuration-version) for more information. + +#### Retry a speculative plan in the UI + +If a speculative plan fails due to an external factor, you can run it again using the "Retry Run" button on its page: + +Retrying a plan requires permission to queue plans for that workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) Only failed or canceled plans can be retried. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Retrying the run will create a new run with the same configuration version. If it is a VCS-backed workspace, the pull request interface will receive the status of the new run, along with a link to the new run. + +### Saved Plans + +-> **Version note:** Using saved plans from the CLI with HCP Terraform requires at least Terraform CLI v1.6.0. + +HCP Terraform also supports saved plan runs. If you have configured the [CLI integration](/terraform/cli/cloud) you can use `terraform plan -out ` to perform and save a plan, `terraform apply ` to apply a saved plan, and `terraform show ` to inspect a saved plan before applying it. You can also create saved plan runs via the API by using the `save-plan` option. + +Saved plan runs affect the run queue differently from normal runs, and can sometimes be automatically discarded. For more details, refer to [Run Modes and Options: Saved Plans](/terraform/enterprise/run/modes-and-options#saved-plans). + +## Planning Modes and Options + +In addition to the normal run workflows described above, HCP Terraform supports destroy runs, refresh-only runs, and several planning options that can modify the behavior of a run. For more details, see [Run Modes and Options](/terraform/enterprise/run/modes-and-options). + +## Run States + +HCP Terraform shows the progress of each run as it passes through each run state (pending, plan, policy check, apply, and completion). In some states, the run might require confirmation before continuing or ending; see [Managing Runs: Interacting with Runs](/terraform/enterprise/run/manage#interacting-with-runs) for more information. + +In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. (Or, if no run is in progress, the state of the most recent completed run.) + +For full details about the stages of a run, see [Run States and Stages][]. + +[Run States and Stages]: /terraform/enterprise/run/states + +## Import + +We recommend using [`import` blocks](/terraform/language/import), introduced in Terraform 1.5, to import resources in HCP Terraform. + +HCP Terraform does not support remote execution for the `terraform import` command. For this command the workspace acts only as a remote backend for Terraform state, with all execution occurring on your own workstations or continuous integration workers. + +Since `terraform import` runs locally, environment variables defined in the workspace are not available. Any environment variables required by the provider you're importing from must be defined within your local execution scope. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/run-environment.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/run-environment.mdx new file mode 100644 index 0000000000..ccae094a3f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/run-environment.mdx @@ -0,0 +1,131 @@ +--- +page_title: Terraform Enterprise's run environment +description: >- + Learn how Terraform Enterprise's run enviornment manages virtual machines, + network access, concurrency for runs, state access authentication, and + environment variables. +source: terraform-docs-common +--- + +# HCP Terraform's run environment + +HCP Terraform is designed as an execution platform for Terraform, and most of its features are based around its ability to perform Terraform runs in a fleet of disposable worker VMs. This page describes some features of the run environment for Terraform runs managed by HCP Terraform. + +## The Terraform Worker VMs + +HCP Terraform performs Terraform runs in single-use Linux virtual machines, running on an x86_64 architecture. + +The operating system and other software installed on the worker VMs is an internal implementation detail of HCP Terraform. It is not part of a stable public interface, and is subject to change at any time. + +Before Terraform is executed, the worker VM's shell environment is populated with environment variables from the workspace, the selected version of Terraform is installed, and the run's Terraform configuration version is made available. + +Changes made to the worker during a run are not persisted to subsequent runs, since the VM is destroyed after the run is completed. Notably, this requires some additional care when installing additional software with a `local-exec` provisioner; see [Installing Additional Tools](/terraform/enterprise/run/install-software#installing-additional-tools) for more details. + +> **Hands-on:** Try the [Upgrade Terraform Version in HCP Terraform](/terraform/tutorials/cloud/cloud-versions) tutorial. + +## Network Access to VCS and Infrastructure Providers + +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 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. + +## Concurrency and Run Queuing + +HCP Terraform uses multiple concurrent worker VMs, which take jobs from a global queue of runs that are ready for processing. (This includes confirmed applies, and plans that have just become the current run on their workspace.) + +If the global queue has more runs than the workers can handle at once, some of them must wait until a worker becomes available. When the queue is backed up, HCP Terraform gives different priorities to different kinds of runs: + +- Applies that will make changes to infrastructure have the highest priority. +- 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. 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 + +[CLI config file]: /terraform/cli/config/config-file + +[cloud]: /terraform/cli/cloud + +HCP Terraform stores state for its workspaces. + +When you trigger runs via the [CLI workflow](/terraform/enterprise/run/cli), Terraform reads from and writes to HCP Terraform's stored state. HCP Terraform uses [the `cloud` block][cloud] for runs, overriding any existing [backend](/terraform/language/settings/backends/configuration) in the configuration. + +-> **Note:** The `cloud` block is available in Terraform v1.1 and later. Previous versions can use the [`remote` backend](/terraform/language/settings/backends/remote) to configure the CLI workflow and migrate state. + +### Autogenerated API Token + +Instead of using existing user credentials, HCP Terraform generates a unique per-run API token and provides it to the Terraform worker in the [CLI config file][]. When you run Terraform on the command line against a workspace configured for remote operations, you must have [the `cloud` block][cloud] in your configuration and have a user or team API token with the appropriate permissions specified in your [CLI config file][]. However, the run itself occurs within one of HCP Terraform's worker VMs and uses the per-run token for state access. + +The per-run token can read and write state data for the workspace associated with the run, can download modules from the [private registry](/terraform/enterprise/registry), and may be granted access to read state from other workspaces in the organization. (Refer to [cross-workspace state access](/terraform/enterprise/workspaces/state#accessing-state-from-other-workspaces) for more details.) Per-run tokens cannot make any other calls to the HCP Terraform API and are not considered to be user, team, or organization tokens. They become invalid after the run is completed. + +### User Token + +HCP Terraform uses the user token to access a workspace's state when you: + +- Run Terraform on the command line against a workspace that is _not_ configured for remote operations. The user must have permission to read and write state versions for the workspace. + +- Run Terraform's state manipulation commands against an HCP Terraform workspace. The user must have permission to read and write state versions for the workspace. + +Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) for more details about workspace permissions. + +### Provider Authentication + +Runs in HCP Terraform typically require some form of credentials to authenticate with infrastructure providers. Credentials can be provided statically through Environment or Terraform [variables](/terraform/enterprise/workspaces/variables), or can be generated on a per-run basis through [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for certain providers. Below are pros and cons to each approach. + +#### Static Credentials + +##### Pros + +- Simple to setup +- Broad support across providers + +##### Cons + +- Requires regular manual rotation for enhanced security posture +- Large blast radius if a credential is exposed and needs to be revoked + +#### Dynamic Credentials + +##### Pros + +- Eliminates the need for manual rotation of credentials on HCP Terraform +- HCP Terraform metadata - including the run's project, workspace, and run-phase - is encoded into every token to allow for granular permission scoping on the target cloud platform +- Credentials are short-lived, which reduces blast radius of potential credential exposure + +##### Cons + +- More complicated initial setup compared to using static credentials +- Not supported for all providers + +The full list of supported providers and setup instructions can be found in the [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) documentation. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Environment Variables + +HCP Terraform automatically injects the following environment variables for each run: + +| Variable Name | Description | Example | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | +| `TFC_RUN_ID` | A unique identifier for this run. | `run-CKuwsxMGgMd4W7Ui` | +| `TFC_WORKSPACE_NAME` | The name of the workspace used in this run. | `prod-load-balancers` | +| `TFC_WORKSPACE_SLUG` | The full slug of the configuration used in this run. This consists of the organization name and workspace name, joined with a slash. | `acme-corp/prod-load-balancers` | +| `TFC_CONFIGURATION_VERSION_GIT_BRANCH` | The name of the branch that the associated Terraform configuration version was ingressed from. | `main` | +| `TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA` | The full commit hash of the commit that the associated Terraform configuration version was ingressed from. | `abcd1234...` | +| `TFC_CONFIGURATION_VERSION_GIT_TAG` | The name of the tag that the associated Terraform configuration version was ingressed from. | `v0.1.0` | +| `TFC_PROJECT_NAME` | The name of the project used in this run. | `proj-name` | + +They are also available as Terraform input variables by defining a variable with the same name. For example: + +```terraform +variable "TFC_RUN_ID" {} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/states.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/states.mdx new file mode 100644 index 0000000000..a8f444e0a3 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/states.mdx @@ -0,0 +1,218 @@ +--- +page_title: Run states and stages in Terraform Enterprise +description: >- + Learn the run stages of Terraform operations. Understanding run stages and + their states can help you follow a run's progress. +source: terraform-docs-common +--- + +# Run states and stages + +Each plan and apply run passes through several stages of action: pending, plan, cost estimation, policy check, apply, and completion. HCP Terraform shows a run's progress through each stage as a run state. + +In the list of workspaces on HCP Terraform's main page, each workspace shows the state of the run it's currently processing. If no run is in progress, HCP Terraform displays the state of the most recently completed run. + +## The Pending Stage + +_States in this stage:_ + +- **Pending:** HCP Terraform hasn't started action on a run yet. HCP Terraform processes each workspace's runs in the order they were queued, and a run remains pending until every run before it has completed. + +_Leaving this stage:_ + +- If the user discards the run before it starts, the run does not continue (**Discarded** state). +- If the run is first in the queue, it proceeds automatically to the plan stage (**Planning** state). + +## The Fetching Stage + +HCP Terraform may need to fetch the configuration from VCS prior to starting the plan. HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs. + +_States in this stage:_ + +- **Fetching:** If HCP Terraform has not yet fetched the configuration from VCS, the run will go into this state until the configuration is available. + +_Leaving this stage:_ + +- If HCP Terraform encounters an error when fetching the configuration from VCS, the run does not continue (**Plan Errored** state). +- If Terraform successfully fetches the configuration, the run moves to the next stage. + +## The Pre-Plan Stage + +The pre-plan phase only occurs if there are enabled [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) in the workspace that are configured to begin before Terraform creates the plan. HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run. + +All runs can enter this phase, including [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). + +_States in this stage:_ + +- **Pre-plan running:** HCP Terraform is waiting for a response from the configured external system(s). + - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status. + +_Leaving this stage:_ + +- If any mandatory tasks failed, the run skips to completion (**Plan Errored** state). +- If any advisory tasks failed, the run proceeds to the **Planning** state, with a visible warning regarding the failed task. +- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails. +- If a user canceled the run, the run ends in the **Canceled** state. + +## The Plan Stage + +A run goes through different steps during the plan stage depending on whether or not HCP Terraform needs to fetch the configuration from VCS. HCP Terraform automatically archives configuration versions created through VCS when all runs are complete and then re-fetches the files for subsequent runs. + +_States in this stage:_ + +- **Planning:** HCP Terraform is currently running `terraform plan`. +- **Needs Confirmation:** `terraform plan` has finished. Runs sometimes pause in this state, depending on the workspace and organization settings. + +_Leaving this stage:_ + +- If the `terraform plan` command failed, the run does not continue (**Plan Errored** state). +- If a user canceled the plan by pressing the "Cancel Run" button, the run does not continue (**Canceled** state). +- If the plan succeeded with no changes and neither cost estimation nor Sentinel policy checks will be done, HCP Terraform considers the run complete (**Planned and Finished** state). +- If the plan succeeded and requires changes: + - If cost estimation is enabled, the run proceeds automatically to the cost estimation stage. + - If cost estimation is disabled and [Sentinel policies](/terraform/enterprise/policy-enforcement/sentinel) are enabled, the run proceeds automatically to the policy check stage. + - If there are no Sentinel policies and the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + - If there are no Sentinel policies and HCP Terraform cannot auto-apply the plan, the run pauses in the **Needs Confirmation** state until a user with permission to apply runs takes action. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) If an authorized user approves the apply, the run proceeds to the apply stage. If an authorized user rejects the apply, the run does not continue (**Discarded** state). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Note, if you want to directly integrate third-party tools and services between your plan and apply stages, see [Run Tasks](/terraform/enterprise/workspaces/settings/run-tasks). + +## The Post-Plan Stage + +The post-plan phase only occurs if you configure [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) on a workspace to begin after Terraform successfully completes a plan operation. +All runs can enter this phase, including [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). During this phase, HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. + +-> **Note:** The information sent to the configured external system includes the [JSON output](/terraform/internals/json-format) of the Terraform plan. + +_States in this stage:_ + +- **Post-plan running:** HCP Terraform is waiting for a response from the configured external system(s). + - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`, or the timeout will expire and the task will be assumed to be in the `failed` status. + +_Leaving this stage:_ + +- If any mandatory tasks failed, the run skips to completion (**Plan Errored** state). +- If any advisory tasks failed, the run proceeds to the **Applying** state, with a visible warning regarding the failed task. +- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, if there are two advisory tasks that succeed and one mandatory task that failed, the run fails. If one mandatory task succeeds and two advisory tasks fail, the run succeeds with a warning. +- If a user canceled the run, the run ends in the **Canceled** state. + +## The OPA Policy Check Stage + +This stage only occurs if you enabled [Open Policy Agent (OPA) policies](/terraform/enterprise/policy-enforcement/opa) and runs after a successful `terraform plan` and before Cost Estimation. In this stage, HCP Terraform checks whether the plan adheres to the policies in the OPA policy sets for the workspace. + +_States in this stage:_ + +- **Policy Check:** HCP Terraform is checking the plan against the OPA policy sets. +- **Policy Override:** The policy check finished, but a mandatory policy failed. The run pauses, and Terraform cannot perform an apply unless a user manually overrides the policy check failure. Refer to [Policy Results](/terraform/enterprise/policy-enforcement/view-results) for details. +- **Policy Checked:** The policy check succeeded, and Terraform can apply the plan. The run may pause in this state if the workspace is not set up to auto-apply runs. + +_Leaving this stage:_ + +If any mandatory policies failed, the run pauses in the **Policy Override** state. The run completes one of the following workflows: + +- The run stops and enters the **Discarded** state when a user with [permission to apply runs](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions#manage-policy-overrides) discards the run. +- The run proceeds to the **Policy Checked** state when a user with [permission to manage policy overrides](/terraform/enterprise/users-teams-organizations/permissions) overrides the failed policy. The **Policy Checked** state means that no mandatory policies failed or that a user performed a manual override. + +Once the run reaches the **Policy Checked** state, the run completes one of the following workflows: + +- The run proceeds to the **Apply** stage if Terraform can automatically apply the plan. An auto-apply requires that the **Auto apply** setting is enabled on the workspace. +- If Terraform cannot automatically apply the plan, the run pauses in the **Policy Checked** state until a user with permission to apply runs takes action. If the user approves the apply, the run proceeds to the **Apply** stage. If the user rejects the apply, the run stops and enters the **Discarded** state. + +## The Cost Estimation Stage + +This stage only occurs if cost estimation is enabled. After a successful `terraform plan`, HCP Terraform uses plan data to estimate costs for each resource found in the plan. + +_States in this stage:_ + +- **Cost Estimating:** HCP Terraform is currently estimating the resources in the plan. +- **Cost Estimated:** The cost estimate completed. + +_Leaving this stage:_ + +- If cost estimation succeeded or errors, the run moves to the next stage. +- If there are no policy checks or applies, the run does not continue (**Planned and Finished** state). + +## The Sentinel Policy Check Stage + +This stage only occurs if [Sentinel policies](/terraform/enterprise/policy-enforcement/sentinel) are enabled. After a successful `terraform plan`, HCP Terraform checks whether the plan obeys policy to determine whether it can be applied. + +_States in this stage:_ + +- **Policy Check:** HCP Terraform is currently checking the plan against the organization's policies. +- **Policy Override:** The policy check finished, but a soft-mandatory policy failed, so an apply cannot proceed without approval from a user with permission to manage policy overrides for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) The run pauses in this state. +- **Policy Checked:** The policy check succeeded, and Sentinel will allow an apply to proceed. The run sometimes pauses in this state, depending on workspace settings. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +_Leaving this stage:_ + +- If any hard-mandatory policies failed, the run does not continue (**Plan Errored** state). +- If any soft-mandatory policies failed, the run pauses in the **Policy Override** state. + - If a user with permission to manage policy overrides, overrides the failed policy, the run proceeds to the **Policy Checked** state. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + - If a user with permission to apply runs discards the run, the run does not continue (**Discarded** state). ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) +- If the run reaches the **Policy Checked** state (no mandatory policies failed, or soft-mandatory policies were overridden): + - If the plan can be auto-applied, the run proceeds automatically to the apply stage. Plans can be auto-applied if the auto-apply setting is enabled on the workspace and the plan was queued by a new VCS commit or by a user with permission to apply runs. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + - If the plan can't be auto-applied, the run pauses in the **Policy Checked** state until a user with permission to apply runs takes action. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) The run proceeds to the apply stage if they approve the apply, or does not continue (**Discarded** state) if they reject the apply. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## The Pre-Apply Stage + +The pre-apply phase only occurs if the workspace has [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) configured to begin before Terraform creates the apply. HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response to determine whether the run can continue. The information sent to the external system includes the configuration version of the run. + +Only confirmed runs can enter this phase. + +_States in this stage:_ + +- **Pre-apply running:** HCP Terraform is waiting for a response from the configured external system(s). + - External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status. + +_Leaving this stage:_ + +- If any mandatory tasks failed, the run skips to completion. +- If any advisory tasks failed, the run proceeds to the **Applying** state, with a visible warning regarding the failed task. +- If a single run has a combination of mandatory and advisory tasks, Terraform takes the most restrictive action. For example, the run fails if there are two advisory tasks that succeed and one mandatory task that fails. +- If a user canceled the run, the run ends in the **Canceled** state. + +## The Apply Stage + +_States in this stage:_ + +- **Applying:** HCP Terraform is currently running `terraform apply`. + +_Leaving this stage:_ + +After applying, the run proceeds automatically to completion. + +- If the apply succeeded, the run ends in the **Applied** state. +- If the apply failed, the run ends in the **Apply Errored** state. +- If a user canceled the apply by pressing **Cancel Run**, the run ends in the **Canceled** state. + +## The Post-Apply Stage + +The post-apply phase only occurs if you configure [run tasks](/terraform/enterprise/workspaces/settings/run-tasks) on a workspace to begin after Terraform successfully completes an apply operation. During this phase, HCP Terraform sends information about the run to the configured external system and waits for a `passed` or `failed` response. However, unlike other stages in the run task process, a failed outcome does not halt the run since HCP Terraform has already provisioned the infrastructure. + +_States in this stage:_ + +- **Post-apply running:** HCP Terraform is waiting for a response from the configured external system(s). +- External systems must respond initially with a `200 OK` acknowledging the request is in progress. After that, they have 10 minutes to return a status of `passed`, `running`, or `failed`. If the timeout expires, HCP Terraform assumes that the run tasks is in the `failed` status. + +_Leaving this stage:_ + +- There are only advisory tasks on this stage. +- If any advisory tasks failed, the run proceeds to the **Applied** state, with a visible warning regarding the failed task. +- If a user cancels the run, the run ends in the **Canceled** state. + +## Completion + +A run is complete if it finishes applying, if any part of the run fails, if there is nothing to do, or if a user chooses not to continue. Once a run completes, the next run in the queue can enter the plan stage. + +_States in this stage:_ + +- **Applied:** The run was successfully applied. +- **Planned and Finished:** `terraform plan`'s output already matches the current infrastructure state, so `terraform apply` doesn't need to do anything. +- **Apply Errored:** The `terraform apply` command failed, possibly due to a missing or misconfigured provider or an illegal operation on a provider. +- **Plan Errored:** The `terraform plan` command failed (usually requiring fixes to variables or code), or a hard-mandatory Sentinel policy failed. The run cannot be applied. +- **Discarded:** A user chose not to continue this run. +- **Canceled:** A user interrupted the `terraform plan` or `terraform apply` command with the "Cancel Run" button. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/run/ui.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/run/ui.mdx new file mode 100644 index 0000000000..36fb9b192b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/run/ui.mdx @@ -0,0 +1,140 @@ +--- +page_title: UI and VCS-driven run workflow in Terraform Enterprise +description: >- + Use Terraform Enterprise's UI and VCS-driven run workflow to automatically + queue runs when merging new commits to the VCS repository branch associated + with a workspace. +source: terraform-docs-common +--- + +# UI and VCS-driven run workflow + +HCP Terraform has three workflows for managing Terraform runs. + +- The UI/VCS-driven run workflow described below, which is the primary mode of operation. +- The [API-driven run workflow](/terraform/enterprise/run/api), which is more flexible but requires you to create some tooling. +- The [CLI-driven run workflow](/terraform/enterprise/run/cli), which uses Terraform's standard CLI tools to execute runs in HCP Terraform. + +## Summary + +In the UI and VCS workflow, every workspace is associated with a specific branch of a VCS repo of Terraform configurations. HCP Terraform registers webhooks with your VCS provider when you create a workspace, then automatically queues a Terraform run whenever new commits are merged to that branch of workspace's linked repository. + +HCP Terraform also performs a [speculative plan][] when a pull request is opened against that branch. HCP Terraform posts a link to the plan in the pull request, and re-runs the plan if the pull request is updated. + +[speculative plan]: /terraform/enterprise/run/remote-operations#speculative-plans + +The Terraform code for a normal run always comes from version control, and is always associated with a specific commit. + +## Automatically Starting Runs + +In a workspace linked to a VCS repository, runs start automatically when you merge or commit changes to version control. + +If you use GitHub as your VCS provider and merge a PR changing 300 or more files, HCP Terraform automatically triggers runs for every workspace connected to that repository. The GitHub API has a limit of 300 reported changed files for a PR merge. To address this, HCP Terraform initiates workspace runs proactively, preventing oversight of file changes beyond this limit. + +A workspace is linked to one branch of a VCS repository and ignores changes to other branches. You can specify which files and directories within your repository trigger runs. HCP Terraform can also automatically trigger runs when you create Git tags. Refer to [Automatic Run Triggering](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering) for details. + +-> **Note:** A workspace with no runs will not accept new runs via VCS webhook. At least one run must be manually queued to confirm that the workspace is ready for further runs. + +A workspace will not process a webhook if the workspace previously processed a webhook with the same commit SHA and created a run. To trigger a run, create a new commit. If a workspace receives a webhook with a previously processed commit, HCP Terraform will add a new event to the [VCS Events](/terraform/enterprise/vcs#viewing-events) page documenting the received webhook. + +## Manually Starting Runs + +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. +2. Click **+ New run**, opening the **Start a new run** dialog. +3. Select the run mode and provide an optional message. + +Review the [run modes documentation](/terraform/enterprise/run/modes-and-options) for more detail on supported options. + +Run modes that have a plan phase support debugging mode. This is equivalent to setting the `TF_LOG` environment variable to `TRACE` for this run only. To enable debugging, click **Additional planning options** under the run mode and click **Enable debugging mode**. See [Debugging Terraform](/terraform/internals/debugging) for more information. + +To [replace](/terraform/enterprise/run/modes-and-options#replacing-selected-resources) specific resources as part of a standard plan and apply run, expand the **Additional planning options** section and select the resources to replace. + +Manually starting a run requires permission to queue plans for the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If the workspace has a plan that is still in the [plan stage](/terraform/enterprise/run/states#the-plan-stage) when a new plan is queued, you can either wait for it to complete, or visit the **Current Run** page and click **Run this plan now**. Be aware that this action terminates the current plan and unlocks the workspace, which can lead to anomalies in behavior, but can be useful if the plans are long-running and the current plan does not have all the desired changes. + +## Automatically cancel plan-only runs triggered by outdated commits + +Refer to [Automatically cancel plan-only runs triggered by outdated commits](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management) for additional information. + +## Confirming or Discarding Plans + +By default, run plans require confirmation before HCP Terraform will apply them. Users with permission to apply runs for the workspace can navigate to a run that has finished planning and click the "Confirm & Apply" or "Discard Plan" button to finish or cancel a run. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) If necessary, use the "View Plan" button for more details about what the run will change. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +![confirm button](/img/docs/runs-confirm.png) + +Users can also leave comments if there's something unusual involved in a run. + +Note that once the plan stage is completed, until you apply or discard a plan, HCP Terraform can't start another run in that workspace. + +### Auto apply + +If you would rather automatically apply plans that don't have errors, you can [enable auto apply](/terraform/enterprise/workspaces/settings#auto-apply-and-manual-apply) on the workspace's "General Settings" page. Some plans can't be auto-applied, like plans queued by [run triggers](/terraform/enterprise/workspaces/settings/run-triggers) or by users without permission to apply runs. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Speculative Plans on Pull Requests + +To help you review proposed changes, HCP Terraform can automatically run [speculative plans][speculative plan] for pull requests or merge requests. + +### Viewing Pull Request Plans + +You can view speculative plans in a workspace's list of normal runs. Additionally, HCP Terraform adds a link to the run in the pull request itself, along with an indicator of the run's status. + +A single pull request can include links to multiple plans, depending on how many workspaces connect to the destination branch. If you update a pull request, HCP Terraform performs new speculative plans and update the links. + +Although any contributor to the repository can see the status indicators for pull request plans, only members of your HCP Terraform organization with permission to read runs for the affected workspaces can click through and view the complete plan output. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Rules for Triggering Pull Request Plans + +Whenever a pull request is _created or updated,_ HCP Terraform checks whether it should run speculative plans in workspaces connected to that repository, based on the following rules: + +- Only pull requests that originate from within the same repository can trigger speculative plans. + + To avoid executing malicious code or exposing sensitive information, HCP Terraform doesn't run speculative plans for pull requests that originate from forks of a repository. + + -> **Note:** On Terraform Enterprise, administrators can choose to allow speculative plans on pull requests that originate from forks. To learn more about this setting, refer to the [general settings documentation](/terraform/enterprise/admin/application/general#allow-speculative-plans-on-pull-requests-from-forks) + +- Pull requests can only trigger runs in workspaces where automatic speculative plans are allowed. You can [disable automatic speculative plans](/terraform/enterprise/workspaces/settings/vcs#automatic-speculative-plans) in a workspace's VCS settings. + +- A pull request will only trigger speculative plans in workspaces that are connected to that pull request's destination branch. + + The destination branch is the branch that a pull request proposes to make changes to; this is often the repository's main branch, but not always. + +- If a workspace is configured to only treat certain directories in a repository as relevant, pull requests that don't affect those directories won't trigger speculative plans in that workspace. For more information, see [VCS settings: automatic run triggering](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering). + + -> **Note:** If HCP Terraform skips a plan because the changes weren't relevant, it will still post a passing commit status to the pull request. + +- HCP Terraform does not update the status checks on a pull request with the status of an associated apply. This means that a commit with a successful plan but an errored apply will still show the passing commit status from the plan. + +### Contents of Pull Request Plans + +Speculative plans for pull requests use the contents of the head branch (the branch that the PR proposes to merge into the destination branch), and they compare against the workspace's current state at the time of the plan. This means that if the destination branch changes significantly after the head branch is created, the speculative plan might not accurately show the results of accepting the PR. To get a more accurate view, you can rebase the head branch onto a more recent commit, or merge the destination branch into the head branch. + +## Testing Terraform Upgrades with Speculative Plans + +You can start a new [speculative plan][speculative plan] in the UI with the workspace's current configuration version and any Terraform version available to the organization. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to try a new Terraform version in. +2. Click **+ New run**. +3. Select **Plan only** as the run type. +4. Select a version from the **Choose Terraform version** menu. The speculative plan will use this version without changing the workspace's settings. +5. Click **Start run**. + +If the run is successful, you can change the workspace's Terraform version and [upgrade the state](/terraform/enterprise/workspaces/state#upgrading-state). + +## Speculative Plans During Development + +You can also use the CLI to run speculative plans on demand before making a pull request. Refer to the [CLI-driven run workflow](/terraform/enterprise/run/cli#remote-speculative-plans) for more details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/2fa.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/2fa.mdx new file mode 100644 index 0000000000..f9377e882c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/2fa.mdx @@ -0,0 +1,47 @@ +--- +page_title: Configure two-factor authentication +description: Use two-factor authentication to secure access to Terraform Enterprise. +source: terraform-docs-common +--- + +# Configure two-factor authentication + +User accounts can be additionally protected with two-factor authentication (2FA), and an organization owner can make this a requirement for all users. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Setting up Two-factor Authentication + +To reach your user security settings page: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Click the user icon in the upper right corner of the screen. +3. Choose **Account Settings** from the menu. + +Once on this page you can set-up authentication with either a TOTP-compliant application and/or an SMS-enabled phone number. Choose your preferred authentication method and enter a phone number (optional if using an application), then follow the instructions to finish the configuration. If you are using an application, you must scan a QR code to enable it; for either method, you must enter valid authentication codes to verify a successful set-up. + +After you finish, the two-factor authentication settings will change to show your currently configured authentication method. You can click the "Reveal codes" link to view backup codes, or use the "Disable 2FA" button to disable two-factor authentication. + +## Logging in with Two-factor Authentication + +After two-factor authentication has been successfully set-up you will need to enter the code from your TOTP-compliant application or from an SMS sent to your approved SMS-enabled phone number on login. + +If necessary you can also use a backup code by clicking "Use a recovery code". Please remember that each backup code can only be used to log in once. + +## Requiring Two-factor Authentication for All Users + +If you are an organization owner you can require all users within your organization to use two-factor authentication. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Click **Settings** in your organization to reach your organization'a settings page, then click **Authentication**. + +Click the button "Require two-factor". Please remember that all organization owners must have two-factor authentication on before this can be set. + +## 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: + +- **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. +- **SSO**: HCP Terraform does not currently support HCP SSO accounts. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/api-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/api-tokens.mdx new file mode 100644 index 0000000000..5aa5db1023 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/api-tokens.mdx @@ -0,0 +1,129 @@ +--- +page_title: Manage API tokens for Terraform Enterprise +description: >- + Use API tokens to authenticate with Terraform Enterprise and perform API + operations. +source: terraform-docs-common +--- + +# API Tokens + +This topic describes the distinct types of API tokens you can use to authenticate with HCP Terraform. + +Note that HCP Terraform only displays API tokens once when you initially create them and are obfuscated thereafter. If the token is lost, it must be regenerated. + +Refer to [Team Token API](/terraform/enterprise/api-docs/team-tokens) and [Organization Token API](/terraform/enterprise/api-docs/organization-tokens) for additional information about using the APIs. + +## 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#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 Tokens** tab to manage API tokens for a team or create new team tokens. + +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. + +Team API tokens are designed for performing API operations on workspaces. They have the same access level to the workspaces the team has access to. For example, if a team has permission to apply runs on a workspace, the team's token can create runs and configuration versions for that workspace via the API. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Note that the individual members of a team can usually perform actions the team itself cannot, since users can belong to multiple teams, can belong to multiple organizations, and can authenticate with Terraform's `atlas` backend for running Terraform locally. + +If an API token is generated for the "owners" team, then that API token will have all of the same permissions that an organization owner would. + +## Organization API Tokens + +API tokens may be generated for a specific organization. Organization API tokens allow access to the organization-level settings and resources, without being tied to any specific team or user. + +To manage the API token for an organization, go to **Organization settings > API Token** and use the controls under the "Organization Tokens" header. + +Each organization can have **one** valid API token at a time. Only [organization owners](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) can generate or revoke an organization's token. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Organization API tokens are designed for creating and configuring workspaces and teams. We don't recommend using them as an all-purpose interface to HCP Terraform; their purpose is to do some initial setup before delegating a workspace to a team. For more routine interactions with workspaces, use [team API tokens](#team-api-tokens). + +Organization API tokens have permissions across the entire organization. They can perform all CRUD operations on most resources, but have some limitations; most importantly, they cannot start runs or create configuration versions. Any API endpoints that can't be used with an organization API token include a note like the following: + +-> **Note:** This endpoint cannot be accessed with [organization tokens](#organization-api-tokens). You must access it with a [user token](/terraform/enterprise/users-teams-organizations/users#api-tokens) or [team token](#team-api-tokens). + + + +## Audit trail tokens + +You can generate an audit trails token to read an organization's [audit trails](/terraform/enterprise/api-docs/audit-trails). Use this token type to authenticate integrations pulling audit trail data, for example, using the [HCP Terraform for Splunk](/terraform/enterprise/integrations/splunk) app. + +To manage an organization's audit trails token, go to **Organization settings > API Token** and use the settings under the "Audit Token" header. + +Each organization can only have a _single_ valid audit trails token. Only [organization owners](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) can generate or revoke an organization's audit trails token. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + + + +## Agent API Tokens + +[Agent pools](/terraform/cloud-docs/agents) have their own set of API tokens which allow agents to communicate with HCP Terraform, scoped to an organization. These tokens are not valid for direct usage in the HCP Terraform API and are only used by agents. + +## Access Levels + +The following chart illustrates the various access levels for the supported API token types. Some permissions are implicit based on the token type, others are dependent on the permissions of the associated user, team, or organization. + +🔵 = Implicit for token type 🔶 = Requires explicit permission + +| | User tokens | Team tokens | Organization tokens | +| ---------------------------------- | :---------: | :---------: | :-----------------: | +| **Users** | | | | +| Manage account settings | 🔵 | | | +| Manage user tokens | 🔵 | | | +| **Workspaces** | | | | +| Read workspace variables | 🔶 | 🔶 | 🔵 | +| Write workspace variables | 🔶 | 🔶 | 🔵 | +| Plan, apply, upload states | 🔶 | 🔶 | | +| Force cancel runs | 🔶 | 🔶 | | +| Create configuration versions | 🔶 | 🔶 | | +| Create or modify workspaces | 🔶 | 🔶 | 🔵 | +| Remote operations | 🔶 | 🔶 | | +| Manage run triggers | 🔶 | 🔶 | 🔵 | +| Manage notification configurations | 🔶 | 🔶 | | +| Manage run tasks | 🔶 | 🔶 | 🔵 | +| **Teams** | | | | +| Create teams | 🔶 | 🔶 | 🔵 | +| Modify team | 🔶 | 🔶 | 🔵 | +| Read team | 🔶 | 🔶 | 🔵 | +| Manage team tokens | 🔶 | 🔶 | 🔵 | +| Manage team workspace access | 🔶 | 🔶 | 🔵 | +| Manage team membership | 🔶 | 🔶 | 🔵 | +| **Organizations** | | | | +| Create organizations | 🔵 | | | +| Modify organizations | 🔶 | | | +| Manage organization tokens | 🔶 | | | +| View audit trails | | | 🔵 | +| Invite users to organization | 🔶 | 🔶 | 🔵 | +| **Sentinel** | | | | +| Manage Sentinel policies | 🔶 | 🔶 | 🔵 | +| Manage policy sets | 🔶 | 🔶 | 🔵 | +| Override policy checks | 🔶 | 🔶 | | +| **Integrations** | | | | +| Manage VCS connections | 🔶 | 🔶 | 🔵 | +| Manage SSH keys | 🔶 | 🔶 | | +| Manage run tasks | 🔶 | 🔶 | 🔵 | +| **Modules** | | | | +| Manage Terraform modules | 🔶 | 🔵 (owners) | | + +## Token Expiration + +You can create user, team, and organization tokens with an expiration date and time. Once the expiration time has passed, the token is longer treated as valid and may not be used to authenticate to any API. Any API requests made with an expired token will fail. + +HashiCorp recommends setting an expiration on all new authentication tokens. Creating tokens with an expiration date helps reduce the risk of accidentally leaking valid tokens or forgetting to delete tokens meant for a delegated use once their intended purpose is complete. + +You can not modify the expiration of a token once you have created it. The HCP Terraform UI displays tokens relative to the current user's timezone, but all tokens are passed and displayed in UTC in ISO 8601 format through the HCP Terraform API. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/index.mdx new file mode 100644 index 0000000000..543f10aaa0 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/index.mdx @@ -0,0 +1,338 @@ +--- +page_title: Organizations overview +description: >- + Organizations are groups of projects and workspaces that let teams + collaborate. Learn how to create and manage Terraform Enterprise + organizations. +source: terraform-docs-common +--- + +[teams]: /terraform/enterprise/users-teams-organizations/teams + +[users]: /terraform/enterprise/users-teams-organizations/users + +[owners]: /terraform/enterprise/users-teams-organizations/teams#the-owners-team + +# Organizations overview + +This topic provides overview information about how to create and manage organizations in HCP Terraform and Terraform Enterprise. An organization contains one or more projects. + +## Requirements + +The **admin** permission preset must be enabled on your profile to create and manage organizations in the HCP Terraform UI. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for additional information. + +## API and Terraform Enterprise Provider + +In addition to the HCP Terraform UI, you can use the following methods to manage organizations: + +- [Organizations API](/terraform/enterprise/api-docs/organizations) +- The `tfe` provider [`tfe_organization`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/organization) resource + +## Select an organization + +HCP Terraform displays your current organization in the sidebar. To select an organization: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise. +2. Click the current organization name to view a list of all the organizations where you are a member. +3. Click an organization to select it. HCP Terraform displays list of workspaces within that organization. + +## Join an organization + +To join an organization, the organization [owners][] or a user with specific [team management](/terraform/enterprise/users-teams-organizations/permissions#team-management-permissions) permissions must invite you, and you must accept the emailed invitation. [Learn more](#users). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Leave an organization + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and click the Terraform logo in the page header to navigate to the **Organizations** page. +2. Open the **...** ellipses menu next to the organization and select **Leave organization**. + +You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or [delete the organization](/terraform/enterprise/users-teams-organizations/organizations#general). + +## Create an organization + + + +On Terraform Enterprise, administrators can restrict your ability to create organizations. Refer to [Organization Creation](/terraform/enterprise/admin/application/general#organization-creation) for details. + + + +On HCP Terraform, any user can create a new organization. If you do not belong to any organizations, HCP Terraform prompts you to create one the first time you [sign in](https://app.terraform.io/). To create an organization: + +1. Click the current organization name and select **Create new organization**. The **Create a new organization** page appears. +2. Enter a unique **Organization name** Organization names can include numbers, letters, underscores (`_`), and hyphens (`-`). +3. Provide an **Email address** to receive notifications about the organization. +4. Click **Create organization**. + +HCP Terraform shows the new organization and prompts you to create a new workspace. You can also [invite other users](#users) to join the organization. + + + +## Managed resources + +Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces. + +HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each [resource](/terraform/language/resources/syntax) instance in the state equals one managed resource. HCP Terraform includes resources in modules and each resource created with the `count` or `for_each` meta-arguments. HCP Terraform does not include [data sources](/terraform/language/data-sources) in the count. Refer to [Managed Resources Count](/terraform/enterprise/workspaces/state#managed-resources-count) in the workspace state documentation for more details. + +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. + +You can also view single-value tags that may already be attached to projects and workspaces. Refer to [Tags](#tags) in the organization settings reference for additional information. + +## Managing settings + +To view and manage an organization's settings, click **Settings**. + +The contents of the organization settings depends on your permissions within the organization. All users can review the organization's contact email, view the membership of any teams they belong to, and view the organization's authentication policy. [Organization owners][owners] can view and manage the entire list of organization settings. Refer to [Organization Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for details. + +You may be able to manage the following organization settings. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Organization settings + +#### General + +Review the organization name and contact email. Organization owners can choose to change the organization name, contact email, and the default execution mode, or delete the organization. When an organization owner updates the default execution mode, all workspaces configured to [inherit this value](/terraform/enterprise/workspaces/settings#execution-mode) will be affected. + +Organization owners can also choose whether [workspace administrators](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) can delete workspaces that are managing resources. Deleting a workspace with resources under management introduces risk because Terraform can no longer track or manage the infrastructure. The workspace's users must manually delete any remaining resources or [import](/terraform/cli/commands/import) them into another Terraform workspace. + + + +Organization owners using HCP Terraform Plus edition can choose whether members with [module management permissions](/terraform/enterprise/users-teams-organizations/permissions#manage-private-registry) can [generate module tests](/terraform/enterprise/registry/test#generated-module-tests). + + + +##### Renaming an organization + +!> **Warning:** Deleting or renaming an organization can be very disruptive. We strongly recommend against deleting or renaming organizations with active members. + +To rename an organization that manages infrastructure: + +1. Alert all members of the organization about the name change. +2. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to rename. +3. Cancel in progress and pending runs or wait for them to finish. HCP Terraform cannot change the name of an organization with runs in progress. +4. Lock all workspaces to ensure that no new runs will start before you change the name. +5. Rename the organization. +6. Update all components using the HCP Terraform API to the new organization name. This includes Terraform's `cloud` block CLI integration, the `tfe` Terraform provider, and any external API integrations. +7. Unlock workspaces and resume normal operations. + +#### Plan & Billing + +Review the organization's plan and any invoices for previous plan payments. Organization owners can also upgrade to one of HCP Terraform's paid plans, downgrade to a free plan, or begin a free trial of paid features. + +#### Tags + +Click the **Tags** tab in the **Tags Management** screen to view single-value tags that may have already been created in your system. The table on lists the tags in the system, the number of times a tag appears in a project or workspace, and the date the tag was created. + +The only action you can perform in the UI is deleting single-value tags from the system. You can use the following methods to delete single-value tags: + +1. Select one or more tags and click **Delete tags**. +2. Select the **Name** header to select all tags, then click **Delete tags**. +3. Click the trash icon for a tag and confirm that you want to permanently delete it when prompted. + +#### Teams + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +All users in an organization can access the **Teams** page, which displays a list of [teams][] within the organization. + +Organization owners and users with the [include secret teams permission](/terraform/enterprise/users-teams-organizations/permissions#include-secret-teams) can: + +- view all [secret teams](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) +- view each team's membership +- manage team API tokens + +HCP Terraform restricts team creation, team deletion, and management of team API tokens to organization owners and users with the [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permission. Organization owners and users with the [manage membership](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permission can manage team membership. Remember that users must accept their organization invitations before you can add them to a team. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Users + +Organization owners and users with [manage membership](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permissions can invite HCP Terraform users into the organization, cancel invitations, and remove existing members. + +The list of users is separated into one tab for active users and one tab for invited users who have not yet accepted their invitations. For active users, the list includes usernames, email addresses, avatar icons, two-factor authentication status, and current team memberships. Use the **Search by username or email** field to filter these lists. + +User invitations are always sent by email; you cannot invite someone using their HCP Terraform username. To invite a user to an organization: + +1. Click **Invite a user**. The **invite a user** box appears. +2. Enter the user's email address and optionally add them to one or more teams. If the user accepts the invitation, HCP Terraform automatically adds them to the specified teams. + +All permissions in HCP Terraform are managed through teams. Users can join an organization without belonging to any teams, but they cannot use HCP Terraform features until they belong to a team. Refer to [permissions](/terraform/enterprise/users-teams-organizations/permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Variable Sets + +View all of the available variable sets and their variables. Users with [**Manage variable set** permissions](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) can create variable sets and assign them to one or more projects or workspaces. + +Variable sets let you reuse the same variables across multiple workspaces or projects in an organization. For example, you could define a variable set of provider credentials and automatically apply it to several projects or workspaces, rather than manually defining credential variables in each. Changes to variable sets instantly apply to all appropriate workspaces, saving time and reducing errors from manual updates. + +Refer to the [variables overview](/terraform/enterprise/workspaces/variables) documentation for details about variable types, scope, and precedence. Refer to [managing variables](/terraform/enterprise/workspaces/variables/managing-variables) for details about how to create and manage variable sets. + +#### Health + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations: + +- Drift detection determines whether your real-world infrastructure matches your Terraform configuration. Drift detection requires Terraform version 0.15.4+. +- Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. Continuous validation requires Terraform version 1.3.0+. + +You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to [Health](/terraform/enterprise/workspaces/health) in the workspaces documentation for more details. + +#### Runs + +From the Workspaces page, click **Settings** in the sidebar, then **Runs** to view all of the current runs in your organization's workspaces. The **Runs** page displays: + +- The name of the run +- The run's ID +- What triggered the run +- The workspace and project where the run is taking place +- When the latest change in the run occurred +- A button allowing you to cancel that run + +You can apply the following filters to limit the runs HCP Terraform displays: + +- Click **Needs Attention** to display runs that require user input to continue, such as approving a plan or overriding a policy. +- Click **Running** to display runs that are in progress. +- Click **On Hold** to display paused runs. + +For precise filtering, click **More filters** and check the boxes to filter runs by specific [run statuses](/terraform/enterprise/run/states), [run operations](/terraform/enterprise/run/modes-and-options), workspaces, or [agent pools](/terraform/cloud-docs/agents/agent-pools). Click **Apply filters** to list the runs that match your criteria. + +You can dismiss any of your filtering criteria by clicking the **X** next to the filter name above the table displaying your runs. + +For more details about run states, refer to [Run States and Stages](/terraform/enterprise/run/states). + +### Integrations + +#### Cost Estimation + +Enable and disable the [cost estimation](/terraform/enterprise/cost-estimation) feature for all workspaces. + +#### Policies + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Policies let you define and enforce rules for Terraform runs. You can write them using either the [Sentinel](/terraform/enterprise/policy-enforcement/sentinel) or [Open Policy Agent (OPA)](/terraform/enterprise/policy-enforcement/opa) policy-as-code frameworks and then group them into policy sets that you can apply to workspaces in your organization. To create policies and policy sets, you must have [permission to manage policies](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions). + +#### Policy Sets + + + +@include 'tfc-package-callouts/policies.mdx' + + + +Create groups of policies and enforce those policy sets globally or on specific [projects](/terraform/enterprise/projects/manage) and workspaces. You can create policy sets through the Terraform API, by connecting a VCS repository containing policies, or directly in HCP Terraform. To create policies and policy sets, you must have [permission to manage policies](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions). + +Refer to [Managing Policy Sets](/terraform/enterprise/policy-enforcement/manage-policy-sets) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Run Tasks + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +Manage the run tasks that you can add to workspaces within the organization. [Run tasks](/terraform/enterprise/workspaces/settings/run-tasks) let you integrate third-party tools and services at specific stages in the HCP Terraform run lifecycle. + +### Security + +#### Agents + + + +@include 'tfc-package-callouts/agents.mdx' + + + +Create and manage [HCP Terraform agent pools](/terraform/cloud-docs/agents). HCP Terraform agents let HCP Terraform communicate with isolated, private, or on-premises infrastructure. This is useful for on-premises infrastructure types such as vSphere, Nutanix, OpenStack, enterprise networking providers, and infrastructure within a protected enclave. + +#### API Tokens + +Organization owners can set up a special [Organization API Token](/terraform/enterprise/users-teams-organizations/api-tokens) that is not associated with a specific user or team. + +#### Authentication + +Organization owners can determine when users must reauthenticate and require [two-factor authentication](/terraform/enterprise/users-teams-organizations/2fa) for all members of the organization. + +#### SSH Keys + +Manage [SSH keys for cloning Git-based modules](/terraform/enterprise/workspaces/settings/ssh-keys) during Terraform runs. This does not include keys to access a connected VCS provider. + +#### SSO + +Organization owners can set up an SSO provider for the organization. + +### Version Control + +#### VCS General + +Configure [Automatically cancel plan-only runs triggered by outdated commits](/terraform/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management) to manage the setting. + +#### VCS Events + +-> **Note:** This feature is in beta. + +Review the event logs for GitLab.com connections. + +#### VCS Providers + +Configure [VCS providers](/terraform/enterprise/vcs) to use in the organization. You must have [permission to manage VCS settings](/terraform/enterprise/users-teams-organizations/permissions). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Destruction and Deletion + +#### Data Retention Policies + + +Data retention policies are exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +An organization owner can set or override the following data retention policies: + +- **Admin default policy** +- **Do not auto-delete** +- **Auto-delete data** + +Setting the data retention policy to **Admin default policy** disables the other data retention policy settings. + +By default, the **Do not auto-delete** option is enabled for an organization. This option directs Terraform Enterprise to retain data associated with configuration and state versions, but organization owners can define configurable data retention policies that allow Terraform to _soft delete_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can delete the object after a set number of days. + +Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection process begins, you can restore soft deleted objects using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and the [state version documentation](/terraform/enterprise/api-docs/state-versions). Terraform permanently deletes the archivist storage after the garbage collection grace period elapses. + +The organization policy is the default policy applied to all workspaces, but members of individual workspaces can set overriding policies for their workspaces that take precedence over the organization policy. + +## Trial Expired Organizations + +HCP Terraform paid features are available as a free trial. When a free trial has expired, the organization displays a banner reading **TRIAL EXPIRED — Upgrade Required**. + +Organizations with expired trials return to the feature set of a free organization, but they retain any data created as part of paid features. Specifically, HCP Terraform disables the following features: + +- Teams other than `owners` and locks users who do not belong to the `owners` team out of the organization. HCP Terraform preserves team membership and permissions and re-enables them after you upgrade the organization. +- Sentinel policy checks. HCP Terraform preserves existing policies and policy sets and re-enables them after you upgrade the organization. +- Cost estimation. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/manage-reserved-tags.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/manage-reserved-tags.mdx new file mode 100644 index 0000000000..60709f95c5 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/manage-reserved-tags.mdx @@ -0,0 +1,59 @@ +--- +page_title: Create and manage reserved tag keys +description: >- + Reserved tag keys let you organize projects and workspaces and track + consumption. Learn how to create and manage reserved tag keys. +source: terraform-docs-common +--- + +# Create and manage reserved tag keys + +This topic describes how to create and manage reserved tag keys in HCP Terraform. You can use reserved tag keys to help managers consistently label workspaces and projects in your organization. + +## Introduction + +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. Doing so helps you standardize tag keys and prevent duplicates that affect your ability to track resources. + +Refer to the following topics for information about creating and managing tags attached to projects and workspaces: + +- [Create a project](/terraform/enterprise/projects/manage#create-a-project) +- [Create workspace tags](/terraform/enterprise/workspaces/tags) + +## Requirements + +The **admin** permission preset must be enabled on your profile to create and manage reserved tags. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for additional information. + +## Define a reserved tag key + +You can define reserved tag keys for your organization so that project and workspace managers can use consistent labels. + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to define a reserved tag for. +2. Choose **Settings** from the sidebar, then **Tags**. +3. Click on the **Reserved Keys** tab. +4. Click **New reserved tag key** and specify a key value when prompted. Keys are unique and can have up to 128 characters. You can use letters, numbers, spaces, and the following special characters: `.`, `=`, `+`, `-`, `@`, `:`, `-`, and `_`. +5. You can enable the **Disable overrides** option to prevent project and workspace managers from overriding the key. Refer to [Disable overrides for project tags](#disable-overrides-for-project-tags) for additional information. +6. Click **Save** to finish adding the key. + +## Delete a reserved key + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to delete a reserved tag. +2. Choose **Settings** from the sidebar, then **Tags**. +3. Click on the **Reserved Keys** tab. +4. Open the ellipses menu and choose **Delete <key-name>**. +5. Click **Yes, delete reserved key** when prompted. + +To re-add a key, you must manually complete the steps described in [Define a reserved tag key](#define-a-reserved-tag-key). + +## Edit a reserved key + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to edit a reserved tag. +2. Choose **Settings** from the sidebar, then **Tags**. +3. Click on the **Reserved Keys** tab. +4. Open the ellipses menu and choose **Edit <key-name>**. +5. Specify your changes and click **Save**. + +## Disable overrides for project tags + +Enable the **Disable overrides** option when creating or editing a reserved tag key to prevent project and workspace managers from overriding the tag keys. + +This option is not retroactive. When a workspace contains keys that were overridden before you enabled the **Disable overrides** option, you must first remove the tags from the workspace. You can then re-apply the keys to the workspace so that HCP Terraform can allow future updates to the workspace tag bindings. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management.mdx new file mode 100644 index 0000000000..8945635223 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/vcs-speculative-plan-management.mdx @@ -0,0 +1,45 @@ +--- +page_title: Automatically cancel plan-only runs triggered by outdated commits +description: >- + Learn how to configure Terraform Enterprise to automatically cancel Terraform + plan operations triggered by pull requests when new commits are pushed to the + VCS. +source: terraform-docs-common +--- + +# Automatically cancel plan-only runs + +This topic describes how to configure HCP Terraform to automatically cancel plan-only Terraform run triggered by pull requests in the VCS. + +## Introduction + +When connected to a VCS, HCP Terraform can automatically start a Terraform run that performs a `terraform plan` operation when someone creates a pull request (PR) in the repository. Refer to [Connecting to VCS](/terraform/enterprise/vcs) for additional information. + +When team members push new commits to the same branch, HCP Terraform starts new run that performs a `terraform plan` operation. But as team members push new commits, the queue of Terraform runs can cause delays and reduce efficiency. + +You can enable the **Automatically cancel speculative plans for outdated commits** option in the organization's settings screen so that HCP Terraform automatically cancel unfinished plan-only runs in VCS workflows. + +## Configure automatic cancellation + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select your organization. +2. Choose **Settings** from the sidebar. +3. Under the **Version Control** group of settings, click **General**. +4. Enable the **Automatically cancel speculative plans for outdated commits** option under the **Manage speculative plans** section. +5. Click **Update settings**. + +After enabling the option, HCP Terraform cancels ongoing or pending speculative plans when new commits are received on the same branch. + +## Automated cancellation notifications + +When the **Automatically cancel speculative plans for outdated commits** option is enabled, HCP Terraform notifies you about plan-only runs that are canceled as a result of the setting. Notifications appear in the following screens: + +- **Run details page**. Refer to [Viewing and Managing Runs](/terraform/enterprise/run/manage) for additional information. + +- **VCS status checks**. When the **Non-aggregated status checks** option is enabled in the version control settings, the notification explicitly states when a plan has been canceled automatically. + + When the **Aggregated status checks** option is enabled, HCP Terraform includes canceled plans in the result and identifies them separately from manually canceled plans. + + Refer to [VCS Status Checks](/terraform/enterprise/users-teams-organizations/organizations/vcs-status-checks) for additional information. + + +- **Aggregated status page**. HCP Terraform prints the cancellation message in the aggregated status page in the **Resources to be changed** section. The section may not reflect a complete result if all runs associated with the commit reach completion. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/vcs-status-checks.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/vcs-status-checks.mdx new file mode 100644 index 0000000000..4b1983ef17 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/organizations/vcs-status-checks.mdx @@ -0,0 +1,49 @@ +--- +page_title: Configure VCS status checks +description: >- + VCS status checks send notifications to your version control provider. Learn + how to configure VCS status checks in Terraform Enterprise. +source: terraform-docs-common +--- + +# Configure VCS status checks + +Status checks are notifications sent to your version control system's VCS provider, providing details about specific commits, including the present status of the HCP Terraform run. Please refer to your VCS provider's documentation regarding status checks (e.g., [GitHub Status Checks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks)). + +## Permissions + +To modify VCS Status Checks settings, you must have [Manage VCS Settings](/terraform/enterprise/users-teams-organizations/permissions#manage-vcs-settings) permissions. + +## Managing organization VCS status check settings + +Organization owners can choose between _aggregated_ (default) and _non-aggregated_ status checks. This setting determines whether detailed information and links are accessed directly from the VCS provider or HCP Terraform. + +This setting also determines the number of status checks directly sent to the VCS Provider in response to actions such as pull or merge requests. + +To view and manage an organization’s VCS Status Check settings, click **Settings** then **Version Control**. + +### Aggregated status checks + +Aggregated status checks offer a streamlined experience if you have a single repository containing configuration for many workspaces (a.k.a., a monorepo). + +When aggregated status checks are enabled, HCP Terraform sends one VCS status check for all runs triggered by a VCS event. If multiple workspaces rely on a shared repository, HCP Terraform aggregates the status checks for these workspaces into one summary. This summary is unique to the workspace's organization and VCS client connection. + +You can access additional information about an aggregated status check in HCP Terraform by clicking the **Details** link a status check provides. This link directs you to an HCP Terraform page that offers the consolidated status check results across multiple workspaces, highlighting details such as resource changes and issues that require attention. + +![Screenshot: Organization Aggregated status checks](/img/docs/organization-vcs-general-aggregated-status-checks.png) + +### Non-aggregated status checks + +Non-aggregated status checks send your VCS provider a status check for each triggered workspace and related run stage in response to a VCS event. For example, a VCS push triggers checks for each related workspace's run stages, including the plan operation, policy checks, cost estimation, run tasks, and more. + +If you have a manageable amount of workspaces and want to visualize status checks on your VCS Provider rather than in HCP Terraform, use non-aggregated status checks. + +![Screenshot: Organization Non-aggregated status checks](/img/docs/organization-vcs-general-non-aggregated-status-checks.png) + +#### Send passing commit statuses + +-> **Note:** Organization owners can only enable the **Send passing commit statuses** setting if the **Aggregated status checks** setting is disabled. + +Workspaces that use part of a shared repository do not typically run plans for changes that do not affect their files. This includes [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans) on pull requests. Since **pending** VCS status checks can block pull requests, workspaces automatically send passing commit statuses for any PRs that do not affect their files. + +You can disable this behavior if it creates too many status checks for your VCS provider. You may want to do this if you have a large number of workspaces sharing one VCS repository. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/permissions.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/permissions.mdx new file mode 100644 index 0000000000..b57deb14a8 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/permissions.mdx @@ -0,0 +1,396 @@ +--- +page_title: Permission model in Terraform Enterprise +description: >- + Use the Terraform Enterprise permission model to manage user access to + organizations, projects, and workspaces. +source: terraform-docs-common +--- + +# Permission model + + + +-> **Note:** Team management is available in HCP Terraform **Standard** Edition. [Learn more about HCP Terraform pricing here](https://www.hashicorp.com/products/terraform/pricing). + + + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +> **Hands-on:** Try the [Manage Permissions in HCP Terraform](/terraform/tutorials/cloud/cloud-permissions?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. + +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 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 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. + +There are also some actions within an organization that are only available to owners. These are generally actions that affect the permissions and membership of other teams, or are otherwise fundamental to the organization's security and integrity. + +Permissions for the owners team include: + +- Manage workspaces (refer to [Organization Permissions][] below; equivalent to admin permissions on every workspace) +- Manage projects (refer to [Organization Permissions][] below; equivalent to admin permissions on every project and workspace) +- Manage policies (refer to [Organization Permissions][] below) +- Manage policy overrides (refer to [Organization Permissions][] below) +- Manage VCS settings (refer to [Organization Permissions][] below) +- Manage the private registry (refer to [Organization Permissions][] below) +- Manage Membership (refer to [Organization Permissions][] below; invite or remove users from the organization itself, and manage the membership of its teams) +- View all secret teams (refer to [Organization Permissions][] below) +- Manage agents (refer to [Organization Permissions][] below) +- Manage organization permissions (refer to [Organization Permissions][] below) +- Manage all organization settings (owners only) +- Manage organization billing (owners only, not applicable to Terraform Enterprise) +- Delete organization (owners only) + +This list is not necessarily exhaustive. + +[Organization Permissions]: #organization-permissions + +## Workspace Permissions + +[workspace]: /terraform/enterprise/workspaces + +Most of HCP Terraform's permissions system is focused on workspaces. In general, administrators want to delegate access to specific collections of infrastructure; HCP Terraform implements this by granting permissions to teams on a per-workspace basis. + +There are two ways to choose which permissions a given team has on a workspace: fixed permission sets, and custom permissions. Additionally, there is a special "admin" permission set that grants the highest level of permissions on a workspace. + +### Implied Permissions + +Some permissions imply other permissions; for example, the run access plan permission also grants permission to read runs. + +If documentation or UI text states that an action requires a specific permission, it is also available for any permission that implies that permission. + +### General Workspace Permissions + +[General Workspace Permissions]: #general-workspace-permissions + +The following workspace permissions can be granted to teams on a per-workspace basis. They can be granted via either fixed permission sets or custom workspace permissions. + +-> **Note:** Throughout the documentation, we refer to the specific permission an action requires (like "requires permission to apply runs") rather than the fixed permission set that includes that permission (like "requires write access"). + +- **Run access:** + - **Read:** — Allows users to view information about remote Terraform runs, including the run history, the status of runs, the log output of each stage of a run (plan, apply, cost estimation, policy check), and configuration versions associated with a run. + - **Plan:** — _Implies permission to read._ Allows users to queue Terraform plans in a workspace, including both speculative plans and normal plans. Normal plans must be approved by a user with permission to apply runs. This also allows users to comment on runs. + - **Apply:** — _Implies permission to plan._ Allows users to approve and apply Terraform plans, causing changes to real infrastructure. +- **Variable access:** + - **No access:** — No access is granted to the values of Terraform variables and environment variables for the workspace. + - **Read:** — Allows users to view the values of Terraform variables and environment variables for the workspace. Note that variables marked as sensitive are write-only, and can't be viewed by any user. + - **Read and write:** — _Implies permission to read._ Allows users to edit the values of variables in the workspace. +- **State access:** + + - **No access:** — No access is granted to the state file from the workspace. + - **Read outputs only:** — Allows users to access values in the workspace's most recent Terraform state that have been explicitly marked as public outputs. Output values are often used as an interface between separate workspaces that manage loosely coupled collections of infrastructure, so their contents can be relevant to people who have no direct responsibility for the managed infrastructure but still indirectly use some of its functions. This permission is required to access the [State Version Outputs](/terraform/enterprise/api-docs/state-version-outputs) API endpoint. + + -> **Note:** **Read state versions** permission is required to use the `terraform output` command or the `terraform_remote_state` data source against the workspace. + - **Read:** — _Implies permission to read outputs only._ Allows users to read complete state files from the workspace. State files are useful for identifying infrastructure changes over time, but often contain sensitive information. + - **Read and write:** — _Implies permission to read._ Allows users to directly create new state versions in the workspace. Applying a remote Terraform run creates new state versions without this permission, but if the workspace's execution mode is set to "local", this permission is required for performing local runs. This permission is also required to use any of the Terraform CLI's state manipulation and maintenance commands against this workspace, including `terraform import`, `terraform taint`, and the various `terraform state` subcommands. +- **Other controls:** + - **Download Sentinel mocks:** — Allows users to download data from runs in the workspace in a format that can be used for developing Sentinel policies. This run data is very detailed, and often contains unredacted sensitive information. + - **Manage Workspace Run Tasks:** — Allows users to associate or dissociate run tasks with the workspace. HCP Terraform creates Run Tasks at the organization level, where you can manually associate or dissociate them with specific workspaces. + - **Lock/unlock workspace:** — Allows users to manually lock the workspace to temporarily prevent runs. When a workspace's execution mode is set to "local", users must have this permission to perform local CLI runs using the workspace's state. + +### Fixed Permission Sets + +Fixed permission sets are bundles of specific permissions for workspaces, which you can use to delegate access to workspaces easily. + +Each permissions set targets a level of authority and responsibility for a given workspace's infrastructure. A permission set can grant permissions that recipients do not require but offer a balance of simplicity and utility. + +#### Workspace Admins + +Much like the owners team has full control over an organization, each workspace has a special "admin" permissions level that grants full control over the workspace. Members of a team with admin permissions on a workspace are sometimes called "workspace admins" for that workspace. + +Admin permissions include the highest level of general permissions for the workspace. There are also some permissions that are only available to workspace admins, which generally involve changing the workspace's settings or setting access levels for other teams. + +Workspace admins have all [General Workspace Permissions](#general-workspace-permissions), as well as the ability to do the following tasks: + +- Read and write workspace settings. This includes general settings, notification configurations, run triggers, and more. +- Set or remove workspace permissions for visible teams. Workspace admins cannot view or manage teams with the [**Secret**](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) visibility option enabled unless they are also organization owners. +- Delete the workspace + - Depending on the [organization's settings](/terraform/enterprise/users-teams-organizations/organizations#general), workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to [Deleting a Workspace With Resources Under Management](/terraform/enterprise/workspaces/settings#deleting-a-workspace-with-resources-under-management) for details. + +#### Write + +The "write" permission set is for people who do most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following workspace permissions: + +- Run access - Apply +- Variable access - Read and write +- State access - Read and write +- Other access - Lock/unlock workspace +- Other access - Download Sentinel mocks + +See [General Workspace Permissions][] above for details about specific permissions. + +#### Plan + +The "plan" permission set is for people who might propose changes to managed infrastructure, but whose proposed changes should be approved before they are applied. Plan access grants the following workspace permissions: + +- Run access - Plan +- Variable access - Read +- State access - Read + +See [General Workspace Permissions][] above for details about specific permissions. + +#### Read + +The "read" permission set is for people who need to view information about the status and configuration of managed infrastructure in order to do their jobs, but aren't responsible for maintaining that infrastructure. Read access grants the following workspace permissions: + +- Run access - Read +- Variable access - Read +- State access - Read + +See [General Workspace Permissions][] above for details about specific permissions. + +### Custom Workspace Permissions + +Custom permissions let you assign specific, finer-grained permissions to a team than the broader fixed permission sets provide. This enables more task-focused permission sets and tighter control of sensitive information. + +You can use custom permissions to assign any of the permissions listed above under [General Workspace Permissions][], with the exception of admin-only permissions. + +The minimum custom permissions set for a workspace is the permission to read runs; the only way to grant a team lower access is to not add them to the workspace at all. + +Some permissions - such as the runs permission - are tiered: you can assign one permission per category, since higher permissions include all of the capabilities of the lower ones. + +## Project Permissions + +You can assign project-specific permissions to teams. + +### Implied Permissions + +Some permissions imply other permissions. For example, permission to update a project also grants permission to read a project. + +If an action states that it requires a specific permission level, you can perform that action if your permissions _imply_ the stated permission level. + +### General Project Permissions + +[General Project Permissions]: #general-project-permissions + +You can grant the following project permissions to teams on a per-project basis. You can grant these with either fixed permission sets or custom project permissions. + +-> **Note:** Throughout the documentation, we refer to the specific permission an action requires (like "requires permission to apply runs") rather than the fixed permission set that includes that permission (like "requires write access"). + +- **Project access:** + - **Read:** — Allows users to view information about the project including the name. + - **Update:** — _Implies permission to read._ Allows users to update the project name. + - **Delete:** — _Implies permission to update._ Allows users to delete the project. + - **Create Workspaces:** — Allow users to create workspaces in the project. This grants read access to all workspaces in the project. + - **Delete Workspaces:** — Allows users to delete workspaces in the project. + - Depending on the [organization's settings](/terraform/enterprise/users-teams-organizations/organizations#general), workspace admins may only be able to delete the workspace if it is not actively managing infrastructure. Refer to [Deleting a Workspace With Resources Under Management](/terraform/enterprise/workspaces/settings#deleting-a-workspace-with-resources-under-management) for details. + - **Move Workspaces:** — Allows users to move workspaces out of the project. A user _must_ have this permission on both the source _and_ destination project to successfully move a workspace from one project to another. +- **Team management:** + - **None:** — No access to view teams assigned to the project. + - **Read:** — Allows users to see teams assigned to the project for visible teams. + - **Manage:** — _Implies permission to read._ Allows users to set or remove project permissions for visible teams. Project admins can not view or manage [secret teams](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility) unless they are also organization owners. +- **Variable sets:** + - **None:** — No access to variable sets owned by the project. However, users with Variable access permissions can view variable sets applied to this project and its workspaces. + - **Read:** — Allows users to view variable sets owned by this project. + - **Manage:** — _Implies permission to read._ Allows users to create, update, and delete variable sets owned by the project. + +See [General Workspace Permissions](#general-workspace-permissions)for the complete list of available permissions for a project's workspaces. + +### Fixed Permission Sets + +Fixed permission sets are bundles of specific permissions for projects, which you can use to delegate access to a project's workspaces easily. + +#### Project Admin + +Each project has an "admin" permissions level that grants permissions for both the project and the workspaces that belong to that project. Members with admin permissions on a project are dubbed that project's "project admins". + +Members of teams with "admin" permissions for a project have [General Workspace Permissions](#general-workspace-permissions) for every workspace in the project, and the ability to: + +- Read and update project settings. +- Delete the project. +- Create workspaces in the project. +- Move workspaces into or out of the project. This also requires project admin permissions for the source or destination project. +- Grant or revoke project permissions for visible teams. Project admins **cannot** view or manage access for teams that are are [Secret](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility), unless those admins are also organization owners. + +#### Maintain + +The "maintain" permission is for people who need to manage existing infrastructure in a single project, while also granting the ability to create new workspaces in that project. Maintain access grants full control of everything in the project, including the following permissions: + +- Admin access for all workspaces in this project. +- Create workspaces in this project. +- Read the project name. +- Lock and unlock all workspaces in this project. +- Read and write variables for all workspaces in this project. +- Access state for all workspaces in this project. +- Approve runs for all workspaces in this project. + +#### Write + +The "write" permission set is for people who do most of the day-to-day work of provisioning and modifying managed infrastructure. Write access grants the following workspace permissions: + +- Read the project name. +- Lock and unlock all workspaces in this project. +- Read and write variables for all workspaces in this project. +- Access state for all workspaces in this project. +- Approve runs for all workspaces in this project. + +#### Read + +The "read" permission set is for people who need to view information about the status and configuration of managed infrastructure for their job function, but are not responsible for maintaining that infrastructure. Read access grants the permissions to: + +- Read the project name. +- Read the workspaces in the project. + +### Custom Project Permissions + +Custom permissions enable you to assign specific and granular permissions to a team. You can use custom permission sets to create task-focused permission sets and control sensitive information. + +You can create a set of custom permissions using any of the permissions listed under [General Project Permissions](#general-project-permissions). + +Some permissions, such as the project access permission, are tiered. You can only assign one permission per category because higher-level permissions include the capabilities of lower levels. + +## Organization Permissions + +Separate from project and workspace permissions, you can grant teams permissions to manage or view certain resources or settings across an organization. To set these permissions for a team, go to your organization's **Settings**. Then click **Teams**, and select the team name from the list. + +The following organization permissions are available: + +### Project permissions + +You must select a level of access for projects. + +#### None + +Members do not have access to projects or workspaces. You can grant permissions to individual projects or workspaces through [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) or [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). + +#### View all projects + +Members can view all projects within the organization. This lets users: + +- View project names in a given organization. + +#### Manage all projects + +Members can create and manage all projects and workspaces within the organization. In addition to the permissions granted by [“Manage all workspaces”](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces), this also lets users: + +- Manage other teams' access to all projects. +- Create, edit, and delete projects (otherwise only available to organization owners). +- Move workspaces between projects. + +### Workspace permissions + +You must select a level of access for workspaces. + +#### None + +Members do not have access to projects or workspaces. You can grant permissions to individual projects or workspaces through [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) or [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions). + +#### View all workspaces + +Members can view all workspaces within the organization. This lets users: + +- View information and features relevant to each workspaces (e.g. runs, state versions, variables). + +#### Manage all workspaces + +Members can create and manage all workspaces within the organization. This lets users: + +- Perform any action that requires admin permissions in those workspaces. +- Create new workspaces within the organization's **Default Project**, an action that is otherwise only available to organization owners. +- Create, update, and delete [Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +### Manage Policies + +Allows members to create, edit, read, list and delete the organization's Sentinel policies. + +This permission implicitly gives permission to read runs on all workspaces, which is necessary to set enforcement of [policy sets](/terraform/enterprise/policy-enforcement/manage-policy-sets). + +### Manage Run Tasks + +Allows members to create, edit, and delete run tasks on the organization. + +### Manage Policy Overrides + +Allows members to override soft-mandatory policy checks. + +This permission implicitly gives permission to read runs on all workspaces, which is necessary to override policy checks. + +### Manage VCS Settings + +Allows members to manage the set of [VCS providers](/terraform/enterprise/vcs) and [SSH keys](/terraform/enterprise/vcs#ssh-keys) available within the organization. + +### Manage Agent Pools + +Allows members to create, edit, and delete agent pools within their organization. + +This permission implicitly grants access to read all workspaces, which is necessary for agent pool management. + +### Manage Private Registry + +Allows members to publish and delete providers, modules, or both providers and modules in the organization's [private registry](/terraform/enterprise/registry). These permissions are otherwise only available to organization owners. + +### 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. + +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. + +#### Manage Membership + +Allows members to invite users to the organization, remove users from the organization, and add or remove users from teams within the organization. + +This permission grants the ability to view the list of users within the organization, and to view the organization access of other visible teams. It does not permit the creation of teams, the ability to modify the settings of existing teams, or the ability to view secret teams. + +In order to modify the membership of a team, a user with Manage Membership permissions must have visibility into the team (i.e. the team must be ["Visible"](/terraform/enterprise/users-teams-organizations/teams/manage#team-visibility), or the user must be on the team). +In order to remove a user from the organization, the holder of this permission must have visibility into all of the teams which the user is a member of. + +~> This permission is intended to allow owners of large organizations to delegate membership management to another trusted team, and should be granted to only teams of trusted users. **Assign with caution:** Users with this permission are able to add themselves to any visible team, and inherit the permissions of any visible team. + +#### Manage Teams + +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. + +The manage teams permission confers all permissions granted by the manage membership permission. + +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**: Users with this permission can update or delete any visible team. Because this permission also confers the manage membership permission, a user with the manage teams permission can add themselves to any visible team. + +#### Manage Organization Access + +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. + +~> **Assign with caution:** Members with this permission can update all organization access settings for any team visible to them. + +### Include Secret Teams + +Allows members access to secret teams at the level permitted by that user's team permissions setting. + +This permission acts as a modifier to existing team management permissions. Members with this permission can access secret teams up to the level permitted by other team management permissions. For example, if a user has permission to include secret teams and [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams), that user can create secret teams. + +### Allow Member Token Management + +Allows owners and members with [manage teams](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permissions to enable and disable team token management for team members. This permission defaults to `true`. + +When member token management is enabled, members will be able to perform actions on team tokens, including generating and revoking a team token. + +When member token management is disabled, members will be unable to perform actions on team tokens, including generating and revoking a team token. + +## Permissions Outside HCP Terraform's Scope + +This documentation only refers to permissions that are managed by HCP Terraform itself. + +Since HCP Terraform integrates with other systems, the permissions models of those systems can also be relevant to the overall security model of your HCP Terraform organization. For example: + +- When a workspace is connected to a VCS repository, anyone who can merge changes to that repository's main branch can indirectly queue plans in that workspace, regardless of whether they have explicit permission to queue plans or are even a member of your HCP Terraform organization. (And when auto-apply is enabled, merging changes will indirectly apply runs.) +- If you use HCP Terraform's API to create a Slack bot for provisioning infrastructure, anyone able to issue commands to that Slack bot can implicitly act with that bot's permissions, regardless of their own membership and permissions in the HCP Terraform organization. +- When a run task sends a request to an integrator, it provides an access token that provides access depending on the run task stage: + - For post-plan, it provides access to the runs plan json and the run task callback + - All access tokens created for run tasks have a lifetime of 10 minutes + +When integrating HCP Terraform with other systems, you are responsible for understanding the effects on your organization's security. An integrated system is able to delegate any level of access that it has been granted, so carefully consider the conditions and events that will cause it to delegate that access. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/index.mdx new file mode 100644 index 0000000000..1be3015653 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/index.mdx @@ -0,0 +1,59 @@ +--- +page_title: Teams overview +description: >- + Teams are a group of users within an organization. Learn about managing teams, + team membership, team permissions, and more. +source: terraform-docs-common +--- + +[organizations]: /terraform/enterprise/users-teams-organizations/organizations + +[organization settings]: /terraform/enterprise/users-teams-organizations/organizations#organization-settings + +[users]: /terraform/enterprise/users-teams-organizations/users + +# Teams overview + +Teams are groups of HCP Terraform [users][] within an [organization][organizations]. If a user belongs to at least one team in an organization, they are considered a member of that organization. + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +An organization can [grant workspace permissions to teams](/terraform/enterprise/users-teams-organizations/teams/manage#managing-workspace-access) that allow its members to start Terraform runs, create workspace variables, read and write state, and more. Teams can only have permissions on workspaces within their organization, although individual users can belong to multiple teams in this and other organizations. + +> **Hands-on:** Try the [Manage Permissions in HCP Terraform](/terraform/tutorials/cloud/cloud-permissions?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. + +## Accessing teams with the API or TFE provider + +In addition to the HCP Terraform UI, you can use the following methods to manage teams: + +- [Teams API](/terraform/enterprise/api-docs/teams) to list, create, update, and delete teams +- [Team Members API](/terraform/enterprise/api-docs/team-members) to add and delete users from teams +- [Team Tokens API](/terraform/enterprise/api-docs/team-tokens) to generate and delete tokens and list an organization's team tokens +- [Team Access API](/terraform/enterprise/api-docs/team-access) to manage team access to one or more workspaces +- The `tfe` provider resources [`tfe_team`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/team), [`tfe_team_members`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/team_members), and `tfe_team_access` + +### API tokens + +Each team can have an API token not associated with a specific user. You can manage a team's API token from the **Organization settings > API Tokens > Team Token** page. You can create, regenerate, and delete team tokens on the API token page. Refer to [Team API Tokens](/terraform/enterprise/users-teams-organizations/api-tokens#team-api-tokens) for details. + +## The owners team + +Every organization has an owners team, and members of the owners team are sometimes called organization owners. An organization's creator is the first member of its owner's team. You can add and remove other members in the same way as you can with other teams. In free organizations, the owner's team is limited to five members. In paid organizations, the size of the owner's team is unlimited. + +You cannot delete or leave the owner's team empty. If only one member in an owner's team exists, you must add another user before removing the current member. + +Refer to [organization owners](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) for more details about owners team permissions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Manage teams + +You can manage many things about teams, including creating and deleting a team, team membership, and team access to workspaces, projects, and organizations. Refer to [Manage teams](/terraform/enterprise/users-teams-organizations/teams/manage) to learn more. + +## Team notifications + +You can set up team notifications to notify team members on external systems whenever a particular action takes place. Refer to [Notifications](/terraform/enterprise/users-teams-organizations/teams/notifications) to learn more. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/manage.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/manage.mdx new file mode 100644 index 0000000000..63e0331297 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/manage.mdx @@ -0,0 +1,109 @@ +--- +page_title: Manage teams +description: >- + Learn how to manage team creation, team deletion, team membership, and team + access to workspaces, projects, and organizations. +source: terraform-docs-common +--- + +# Manage teams + +You can grant team management abilities to members of teams with either one of the manage teams or manage organization access permissions. Refer to [Team Permissions](/terraform/enterprise/users-teams-organizations/permissions#team-permissions) for details. + +[Organization owners](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) can also create teams, assign team permissions, or view the full list of teams. Other users can view any teams marked as visible within the organization, plus any secret teams they are members of. Refer to [Team Visibility](#team-visibility) for details. + +To manage teams, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to manage teams. +2. Choose **Settings** from the sidebar, then **Teams**. The **Team Management** page appears, containing a list of all teams within the organization. +3. Click a team to go to its settings page, which lists the team's settings and current members. Members that have [two-factor authentication](/terraform/enterprise/users-teams-organizations/2fa) enabled have a **2FA** badge. + +You can manage a team on its settings page by adding or removing members, changing its visibility, and controlling access to workspaces, projects, and the organization. + +## Create teams + +To create a new team, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to create a team. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click **Create a team**. +4. Enter a unique team **Name** and click **Create Team**. Team names can include numbers, letters, underscores (`_`), and hyphens (`-`). + +The new team's settings page appears, where you can add new members and grant permissions. + +## Delete teams + +~> **Important:** Team deletion is permanent, and you cannot undo it. + +To delete a team, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to delete a team. +2. Choose **Settings** from the sidebar, then **Teams**. The **Team Management** page appears, containing a list of all teams within the organization. +3. Click the team you want to delete to go to its settings page. +4. Click **Delete [team name]** at the bottom of the page. The **Deleting team "[team name]"** box appears. +5. Click **Yes, delete team** to permanently delete the team and all of its data from HCP Terraform. + +## Manage team membership + +Team structure often resembles your company's organizational structure. + +### Add users + +If the user is not yet in the organization, [invite them to join the organization](/terraform/enterprise/users-teams-organizations/organizations#users) and include a list of teams they should belong to in the invitation. Once the user accepts the invitation, HCP Terraform automatically adds them to those teams. + +To add a user that is already in the organization: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to add a user to a team. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click on a team's name to go to its settings page. +4. Choose a user under **Add a New Team Member**. Use the text field to filter the list by username or email. +5. Click the user to add them to the team. HCP Terraform now displays the user under **Members**. + +### Remove users + +To remove a user from a team: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to remove a user from a team. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click the team to go to its settings page. +4. Click **...** next to the user's name and choose **Remove from team** from the menu. HCP Terraform removes the user from the list of team members. + +## Team visibility + +The settings under **Visibility** allow you to control who can see a team within the organization. To edit a team's visibility: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization where you want to view teams. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Click on a team's name to navigate to its settings page. +4. Enable one of the following settings: + - **Visible:** Every user in the organization can see the team and its membership. Non-members have read-only access. + - **Secret:** The default setting is that only team members and organization owners can view a team and its membership. + +We recommend making the majority of teams visible to simplify workspace administration. Secret teams should only have +[organization-level permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) since workspace admins cannot manage permissions for teams they cannot view. + +## Manage workspace access + +You can grant teams various permissions on workspaces. Refer to [Workspace Permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) for details. + +HCP Terraform uses the most permissive permission level from your teams to determine what actions you can take on a particular resource. For example, if you belong to a team that only has permission to read runs for a workspace and another team with admin access to that workspace, HCP Terraform grants you admin access. + +HCP Terraform grants the most permissive permissions regardless of whether an organization, project, team, or workspace set those permissions. For example, if a team has permission to read runs for a given workspace and has permission to manage that workspace through the organization, then members of that team can manage that workspace. Refer to [organization permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) and [project permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) for additional information. + +Another example is when a team has permission at the organization-level to read runs for all workspaces and admin access to a specific workspace. HCP Terraform grants the more permissive admin permissions to that workspace. + +To manage team permissions on a workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace where you want to set team permissions. +2. Choose **Settings** from the sidebar, then **Team Access**. +3. Click **Add team and permissions** to select a team and assign a pre-built or custom permission set. + +## Manage project access + +You can grant teams permissions to manage a project and the workspaces that belong to it. Refer to [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) for details. + +## Manage organization access + +Organization owners can grant teams permissions to manage policies, projects and workspaces, team and organization membership, VCS settings, private registry providers and modules, and policy overrides across an organization. Refer to [Organization Permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/notifications.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/notifications.mdx new file mode 100644 index 0000000000..f13ba68a18 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/teams/notifications.mdx @@ -0,0 +1,132 @@ +--- +page_title: Manage team notifications +description: >- + Learn how to set up team notifications to notify team members on external + systems whenever a particular action takes place. +source: terraform-docs-common +--- + +# Manage team notifications + +HCP Terraform can use webhooks to notify external systems about run progress, change requests, and other events. Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs. + +@include 'tfc-package-callouts/notifications.mdx' + +You can configure an individual team notification to notify up to twenty teams. To set up notifications for teams using the API, refer to the [Notification API](/terraform/enterprise/api-docs/notification-configurations#team-notification-configuration). + +## Requirements + +To configure team notifications, you need the [**Manage teams**](/terraform/enterprise/users-teams-organizations/permissions#manage-teams) permissions for the team for which you want to configure notifications. + +## View notification configuration settings + +To view your current team notifications, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to view the team notifications of. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Select the team for which you want to view the notifications from your list of teams. +4. Select **Notifications** in the sidebar navigation. + +HCP Terraform displays a list of any notification configurations you have set up. A notification configuration defines how and when you want to send notifications, and once you enable that configuration, it can send notifications. + +### Update and enable notification configurations + +Each notification configuration includes a brief overview of each configuration’s name, type, the events that can trigger the notification, and the last time the notification was triggered. Clicking on a notification configuration opens a page where you can perform the following actions: + +- Enable your configuration to send notifications by toggling the switch. +- Delete a configuration by clicking **Delete notification**, then **Yes, delete notification configuration**. +- Test your notification’s configuration by clicking **Send test**. +- Click **Edit notification** to edit your notification configuration. + +After creating a notification configuration, you can only edit the following aspects of that configuration: + +1. The configuration’s name. +2. Whether this configuration notifies everyone on a team or specific members. +3. The workspace events that trigger notifications. You can choose from: + - **All events** triggers a notification for every event in your workspace. + - **No events** means that no workspace events trigger a notification. + - **Only certain events** lets you specify which events trigger a notification. + +After making any changes, click **Update notification** to save your changes. + +## Create and configure a notification + +To configure a new notification for a team or a user, perform the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the organization you want to create a team notification in. +2. Choose **Settings** from the sidebar, then **Teams**. +3. Select the team you want to view the notifications for from your list of teams. +4. Select **Notifications** in the sidebar navigation. +5. Click **Create a notification**. + +You must complete the following fields for all new notification configurations: + +1. The **Destination** where HCP Terraform should deliver either a generic or a specifically formatted payload. Refer to [Notification payloads](#notification-payloads) for details. +2. The display **Name** for this notification configuration. +3. If you configure an email notification, you can optionally specify which **Email Recipients** will receive this notification. +4. If you choose to configure a webhook, you must also specify: + - A **Webhook URL** for the destination of your webhook payload. Your URL must accept HTTP or HTTPS `POST` requests and be able to use the chosen payload type. + - You can optionally configure a **Token** as an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to [Notification authenticity](#notification-authenticity) for details. You cannot view the token after you save the notification configuration. +5. If you choose to specify either a **Slack** or **Microsoft Teams** notification, you must also configure your webhook URL for either service. For details, refer to Slack's documentation on [creating an incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook) and Microsoft's documentation on [creating a workflow from a channel in teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e). +6. Specify which [**Workspace events**](#workspace-events) should trigger this notification. +7. After you finish configuring your notification, click **Create a notification**. + +Note that if you are create an email notification, you must have [**Manage membership**](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permissions on a team to select users from that team as email recipients. + +### Workspace events + +HCP Terraform can send notifications for all workspace events, no workspace events, or specific events. The following events are available for you to specify: + +| Event | Description | +| :-------------- | :-------------------------------------------------------------------------------------------------------------------------- | +| Change Requests | HCP Terraform will notify this team whenever someone creates a change request on a workspace to which this team has access. | + +## Enable and verify a notification + +To configure HCP Terraform to stop sending notifications for a notification configuration, disable the **Enabled** setting on a configuration's detail page . + +HCP Terraform enables notifications for email configurations by default. Before enabling any webhook notifications, HCP Terraform attempts to verify the notification’s configuration by sending a test message. If the test succeeds, HCP Terraform enables the notification. + +To verify a notification configuration, the destination must respond with a `2xx` HTTP code. If verification fails, HCP Terraform does not enable the configuration and displays an error message. + +For successful and unsuccessful verifications, click the **Last Response** box to view more information about the verification results. You can also send additional test messages by clicking **Send a Test**. + +## Notification Payloads + +Notification payloads contain different attributes depending on the integration you specified when configuring that notification. + +### Slack + +Notifications to Slack contain the following information: + +- Information about the change request, including the username and avatar of the person who created the change request. +- The event that triggered the notification and the time that event occurred. + +### Microsoft Teams + +Notifications to Microsoft Teams contain the following information: + +- Information about the change request, including the username and avatar of the person who created the change request. +- The event that triggered the notification and the time that event occurred. + +### Email + +Email notifications contain the following information: + +- Information about the change request, including the username and avatar of the person who created the change request. +- The event that triggered the notification and the time that event occurred. + +### Generic + +A generic notification contains information about the event that triggered it and the time that the event occurred. You can refer to the complete generic notification payload in the [API documentation](/terraform/enterprise/api-docs/notification-configurations#notification-payload). + +You can use some of the values in the payload to retrieve additional information through the API, such as: + +- The [workspace ID](/terraform/enterprise/api-docs/workspaces#list-workspaces) +- The [organization name](/terraform/enterprise/api-docs/organizations#show-an-organization) + +## Notification Authenticity + +Slack notifications use Slack's own protocols to verify HCP Terraform's webhook requests. + +Generic notifications can include a signature to verify the request. For notification configurations that include a secret token, HCP Terraform's webhook requests include an `X-TFE-Notification-Signature` header containing an HMAC signature computed from the token using the SHA-512 digest algorithm. The notification’s receiving service is responsible for validating the signature. For more information and an example of how to validate the signature, refer to the [API documentation](/terraform/enterprise/api-docs/notification-configurations#notification-payload). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/users.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/users.mdx new file mode 100644 index 0000000000..aa24a43750 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/users-teams-organizations/users.mdx @@ -0,0 +1,215 @@ +--- +page_title: Create and manage users in Terraform Enterprise +description: Learn how to create and manage users in Terraform Enterprise. +source: terraform-docs-common +--- + +[organizations]: /terraform/enterprise/users-teams-organizations/organizations + +[teams]: /terraform/enterprise/users-teams-organizations/teams + +[invite]: /terraform/enterprise/users-teams-organizations/organizations#users + +[owners]: /terraform/enterprise/users-teams-organizations/teams#the-owners-team + +# Create and manage users + +User accounts belong to individual people. Each user can be part of one or more [teams](/terraform/enterprise/users-teams-organizations/teams), which are granted permissions on workspaces within an organization. A user can be a member of multiple [organizations][]. + +## API + +Use the [Account API](/terraform/enterprise/api-docs/account) to get account details, update account information, and change your password. + + + +## Log in with a HashiCorp Cloud Platform account + +We recommend using a [HashiCorp Cloud Platform (HCP)](https://portal.cloud.hashicorp.com/sign-up) account to log in to HCP Terraform. Your HCP Account grants access to every HashiCorp product and the Terraform Registry. If you use an HCP Account, you manage account settings like multi-factor authentication and password resets from within HCP instead of the HCP Terraform UI. + +To log in with your HCP account, navigate to [HCP Terraform](https://app.terraform.io/) and click **Continue with HCP account**. HCP Terraform may ask if you want to link your account. + +### Linking HCP and HCP Terraform accounts + +The first time you log in with your HCP credentials, HCP Terraform searches for an existing HCP Terraform account with the same email address. If you have an unlinked account, HCP Terraform asks if you want to link it to your HCP account. Otherwise, if no account matches your HCP account's email address, HCP Terraform creates and automatically links a new HCP Terraform account to your HCP account. + +> **Note**: You can only log in with your HCP credentials after linking your HCP and HCP Terraform accounts. We do not recommend linking your account if you use an SSO provider to log in to HCP Terraform because linking your account may conflict with your existing SSO configuration. + +The only way to log in with your old HCP Terraform credentials is to unlink your HCP Terraform and HCP accounts. If HCP Terraform generated an account for you, you cannot unlink that account from your HCP account. You can unlink a pre-existing HCP Terraform account on the [HCP Account Linking page](#hcp-account-linking) in your **Account settings**. + + + +## Creating an account + +To use HCP Terraform or Enterprise, you must create an account through one of the following methods: + +- **Invitation Email:** When a user sends you an invitation to join an existing HCP Terraform organization, the email includes a sign-up link. After you create an account, you can automatically join that organization and can begin using HCP Terraform. +- **Sign-Up Page:** Creating an account requires a username, an email address, and a password. [Sign up on HCP Terraform](https://app.terraform.io/public/signup/account) or if you have a Terraform Enterprise instance, go to `https:///public/signup/account`. + +After you create an account, you do not belong to any organizations. To begin using HCP Terraform, you can either [create an organization](/terraform/enterprise/users-teams-organizations/organizations#creating-organizations) or ask an organization owner to send you an invitation email to join their organization. + + + +We recommend logging into HCP Terraform [with your HCP account](#log-in-with-your-hashicorp-cloud-platform-account) instead of creating a separate HCP Terraform account. + + + +## Joining organizations and teams + +An organization owner or a user with [**Manage Membership**](/terraform/enterprise/users-teams-organizations/permissions#manage-membership) permissions enabled must [invite you to join their organization](/terraform/enterprise/users-teams-organizations/organizations#users) and [add you to one or more teams](/terraform/enterprise/users-teams-organizations/teams/manage#manage-team-membership). + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +HCP Terraform sends user invitations by email. If the invited email address matches an existing HCP Terraform account, the invitee can join the organization with that account. Otherwise, they must create a new account and then join the organization. + +## Site admin permissions + +On Terraform Enterprise instances, some user accounts have a special site admin permission that allows them to administer the entire instance. + +Admin permissions are distinct from normal organization-level permissions, and they apply to a different set of UI controls and API endpoints. Admin users can administer any resource across the instance when using the site admin pages or the [admin API](/terraform/enterprise/api-docs/admin), but they have normal user permissions when using an organization's standard UI controls and API endpoints. These normal user permissions are determined by team membership. + +Refer to [Administering Terraform Enterprise](/terraform/enterprise/admin) for more details. + +## Account settings + +To view your settings page, click your user icon and select **Account settings**. Your **Profile** page appears, showing your username, email address, and avatar. + +### Profile + +Click **Profile** in the sidebar to view and edit the username and email address associated with your HCP Terraform account. + +~> **Important:** HCP Terraform includes your username in URL paths to resources. If external systems make requests to these resources, you must update them before you change your username. + +HCP Terraform uses [Gravatar](http://en.gravatar.com) to display a user icon if you have associated one with your email address. Refer to the [Gravatar documentation](http://en.gravatar.com/support/) for details about changing your user icon. + +### Sessions + +Click **Sessions** in the sidebar to view a list of sessions associated with your HCP Terraform account. You can revoke any sessions you do not recognize. + + + +There are two types of Terraform accounts, standalone HCP Terraform accounts and HCP Terraform accounts linked to HCP accounts. + +### Idle session timeout + +HCP Terraform automatically terminates user sessions if there has been no end-user activity for a certain time period: + +- Standalone HCP Terraform accounts can stay idle and valid for up to 14 days by default +- HCP Terraform accounts linked to an HCP account follow the HCP defaults and can stay idle for 1 hour by default + +After HCP Terraform terminates a session, you can resume it by logging back in through the HCP Terraform portal. This is a security measure to prevent unauthorized access to unmonitored devices. + +-> **Note:** HCP Terraform organization owners can reduce the idle session timeout for an organization in the authentication settings for standalone HCP Terraform accounts, but cannot modify settings for HCP Terraform accounts linked to HCP accounts. + +### Forced re-authentication + +Forced re-authentication (e.g., “remember for”) makes a user re-authenticate, regardless of activity. This is a security measure to force a new identity verification to access sensitive IT and data managed by HCP Terraform. In this case, the user must re-authenticate their credentials and may be asked to verify 2FA/MFA again. + +- By default, standalone HCP Terraform accounts are forced to re-authenticate every 14 days +- By default, HCP Terraform accounts linked to an HCP account follow the HCP defaults and are forced to re-authenticate every 48 hours + +-> **Note:** HCP Terraform organization owners can reduce the idle session timeout for standalone HCP Terraform accounts, but cannot modify settings for HCP Terraform accounts linked to HCP accounts. + +### Impact to user experience + +The default re-authentication defaults force users to re-authenticate at the beginning of each work week (Monday through Friday). Note that several actions immediately terminate active sessions, including: + +- Manually logging out of the HCP or HCP Terraform portals +- Clearing browser session/cookies +- Closing all active browser windows + +Any of these actions requires you to re-authenticate regardless of session timeout settings. + + + +### Organizations + +Click **Organizations** in the sidebar to view a list of the organizations where you are a member. If you are on the [owners team][owners], the organization is marked with an **OWNER** badge. + +To leave an organization, click the ellipses (**...**) next to the organization and select **Leave organization**. You do not need permission from the owners to leave an organization, but you cannot leave if you are the last member of the owners team. Either add a new owner and then leave, or [delete the organization](/terraform/enterprise/users-teams-organizations/organizations#general). + +### Password + +Click **Password** in the sidebar to change your password. + +-> **Note:** Password management is not available if your Terraform Enterprise instance uses [SAML single sign on](/terraform/enterprise/saml/configuration). +-> **Note:** Passwords must be at least 10 characters in length, and you can use any type of character. Password management is not available if your Terraform Enterprise instance uses [SAML single sign on](/terraform/enterprise/saml/configuration). + +### Two-factor authentication + +Click **Two Factor Authentication** in the sidebar to enable two-factor authentication. Two-factor authentication requires a TOTP-compliant application or an SMS-capable phone number. An organization can set policies that require two-factor authentication. + +Refer to [Two-Factor Authentication](/terraform/enterprise/users-teams-organizations/2fa) for details. + + + +### HCP account linking + +Click **HCP Account Linking** in the sidebar to unlink your HCP Terraform from your HCP Account. You cannot unlink an account that HCP Terraform autogenerated during the linking process. Refer to [Linked HCP and HCP Terraform Accounts](#linked-hcp-and-hcp-terraform-accounts) for more details. + +After you unlink, you can begin using your HCP Terraform credentials to log in. You cannot log in with your HCP account again unless you re-link it to your HCP Terraform account. + +### SSO identities + +Click **SSO Identities** in the sidebar to review and [remove SSO identity links](/terraform/enterprise/users-teams-organizations/single-sign-on/linking-user-account#remove-sso-identity-link) associated with your account. + +You have an SSO identity for every SSO-enabled HCP Terraform organization. HCP Terraform links each SSO identity to a single HCP Terraform user account. This link determines which account you can use to access each organization. + + + +### Tokens + +Click **Tokens** in the sidebar to create, manage, and revoke API tokens. HCP Terraform has three kinds of API tokens: user, team, and organization. Users can be members of multiple organizations, so user tokens work with any organization where the associated user is a member. Refer to [API Tokens](/terraform/enterprise/users-teams-organizations/api-tokens) for details. + +API tokens are required for the following tasks: + +- Authenticating with the [HCP Terraform API](/terraform/enterprise/api-docs). API calls require an `Authorization: Bearer ` HTTP header. +- Authenticating with the [HCP Terraform CLI integration](/terraform/cli/cloud/settings) or the [`remote` backend](/terraform/language/settings/backends/remote). These require a token in the CLI configuration file or in the backend configuration. +- Using [private modules](/terraform/enterprise/registry/using) in command-line runs on local machines. This requires [a token in the CLI configuration file](/terraform/enterprise/registry/using#authentication). + +Protect your tokens carefully because they contain the same permissions as your user account. For example, if you belong to a team with permission to read and write variables for a workspace, another user could use your API token to authenticate as your user account and also edit variables in that workspace. Refer to [permissions](/terraform/enterprise/users-teams-organizations/permissions) for more details. + +We recommend protecting your tokens by creating them with an expiration date and time. Refer to [API Token Expiration](/terraform/enterprise/users-teams-organizations/api-tokens#token-expiration) for details. + +#### Creating a token + + To create a new token: + +1. Click **Create an API token**. The **Create API token** box appears. +2. Enter a **Description** that explains what the token is for and click **Create API token**. +3. You can optionally enter the token's expiration date or time, or create a token that never expires. The UI displays a token's expiration date and time in your current time zone. +4. Copy your token from the box and save it in a secure location. HCP Terraform only displays the token once, right after you create it. If you lose it, you must revoke the old token and create a new one. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +#### Revoking a token + +To revoke a token, click the **trash can** next to it. That token will no longer be able to authenticate as your user account. + +~> **Note**: HCP Terraform does not revoke a user API token's access to an organization when you remove the user from an SSO Identity Provider as the user may still be a member of the organization. To remove access to a user's API token, remove the user from the organization in the UI or with the [Terraform Enterprise provider](https://registry.terraform.io/providers/hashicorp/tfe/latest). + +### GitHub app OAuth token + +Click **Tokens** in the sidebar to manage your GitHub App token. This token lets you connect a workspaces to an available GitHub App installation. + +~> **Note:** Only an HCP Terraform user can own a GitHub App token. Team and Organization API tokens are not able to own a GitHub App token. + +A GitHub App token lets you: + +- Connect workspaces, policy sets, and registry modules to a GitHub App installation with the [HCP Terraform API](/terraform/enterprise/api-docs) and UI. +- View available GitHub App installations with the [HCP Terraform API](/terraform/enterprise/api-docs) and UI. + +After generating this token, you can use it to view information about your available installations for the Terraform Cloud GitHub App. + +#### Creating a GitHub app token + +To create a GitHub App token, click **Create a GitHub App token**. The **GitHub App authorization pop-up window** appears requesting authorization of the Terraform Cloud GitHub App. + +~> **Note:** This does not grant HCP Terraform access to repositories. + +#### Revoking a GitHub app token + +To revoke the GitHub App token, click the **ellipses button (...)**. The dropdown menu appears. Click the **Delete Token** option. This triggers a confirmation window to appear, which asks you to confirm that you want to revoke the token. Once confirmed, the token is revoked and you can no longer view GitHub App installations. + +#### Additional resources + +- [GitHub App permissions in HCP Terraform](/terraform/enterprise/vcs/github-app#github-permissions) diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-server.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-server.mdx new file mode 100644 index 0000000000..1995aa8bc4 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-server.mdx @@ -0,0 +1,94 @@ +--- +page_title: Set up the Azure DevOps Server VCS provider +description: >- + 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 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). + +## 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 + +### 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: + +- [IIS Basic Authentication must be disabled](https://docs.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/iis-basic-auth?view=azure-devops) on your Azure DevOps Server instance in order to use personal access tokens. +- Personal access tokens eventually expire, with a maximum allowed lifetime of one year. If HCP Terraform's token expires, it will be unable to connect to Azure DevOps Server until the token is replaced. To avoid a gap in service, do one of the following before the token expires: + - Update the expiration date of the existing token within Azure DevOps Server. + - Create a new token, and edit HCP Terraform's VCS connection to use it. + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +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 Server** from the menu. The page moves to the next step. + +5. On the "Set up provider" step there are three textboxes. Enter an optional **Name** for this VCS connection. Enter the instance URL for your Azure DevOps Server in **HTTP URL** and **API URL** textboxes. Click the "Continue" button to continue to the next step. + +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: On Azure DevOps Server, Create a New Personal Access Token + +1. In a new browser tab, open your Azure DevOps Server instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have Project Collection Administrator access** to any projects containing repositories of Terraform configurations, since creating webhooks requires these permissions. It is not possible to create custom access roles with lower levels of privilege, as Microsoft does not currently allow delegation of this capability. + +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.") + +4. Copy the generated token to your clipboard; you'll paste it in the next step. Leave this page open in a browser tab. + +## Step 3: Add the Personal Access Token on HCP Terraform + +1. On the "Configure settings" step there is one textbox. Enter your Azure DevOps Server **Personal Access Token** from Step 2. Click the "Continue" button to continue to the next step. + +## Step 4: Configure VCS Provider Scope on HCP Terraform (Optional) + +This step is optional. You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. + +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. + +2. Click the **Update VCS Provider** button to save your selections. + +## Step 5: On Workstation, Create an SSH Key for HCP Terraform + +On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Server. The exact command depends on your OS, but is usually something like `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"`. This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. + +This SSH key **must have an empty passphrase.** HCP Terraform cannot use SSH keys that require a passphrase. + +### Important Notes + +- Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Server; generate a new one 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, it retains it and will use it for authenticating to Azure DevOps Server. +- **Protect this private key carefully.** It can read code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +## Step 6: On Azure Devops Server, Add SSH Public Key + +1. Navigate to User settings -> Security -> SSH public keys on your Azure DevOps Server instance. + + ![Azure DevOps Server screenshot: the SSH keys page](/img/docs/azure-devops-server-public-keys.png) + +2. Click the **Add** button. Paste the text of the **SSH public key** you created in step 3 (from the `.pub` file) into the text field, then click the **Add key** button to confirm. + +## Step 7: On HCP Terraform, Add SSH Private Key + +1. Go back to your HCP Terraform browser tab and paste the text of the **SSH private key** you created in step 3 into the **Private SSH Key** text field of the "Set up SSH keypair" step. Click the "Add SSH key" button. + +## Finished + +At this point, Azure DevOps Server access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-services-pat.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-services-pat.mdx new file mode 100644 index 0000000000..1da6dc1123 --- /dev/null +++ b/content/ptfe-releases/v000011-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/v000011-1/docs/enterprise/vcs/azure-devops-services.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-services.mdx new file mode 100644 index 0000000000..023a60d8b7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/azure-devops-services.mdx @@ -0,0 +1,132 @@ +--- +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 using OAuth. +source: terraform-docs-common +--- + +# 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. + +This page explains the four main steps required to connect HCP Terraform to your Azure DevOps Services VCS: + +1. Create a new connection in HCP Terraform and get the callback URL. +2. On your VCS, register your HCP Terraform organization as a new application. Provide the callback URL and get the application ID and key. +3. Provide HCP Terraform with the application ID and key. Then, request VCS access. +4. On your VCS, approve the access request from HCP Terraform. + +~> **Important:** HCP Terraform only supports Azure DevOps connections that use the `dev.azure.com` domain. If your Azure DevOps project uses the older `visualstudio.com` domain, you must migrate using the [steps in the Microsoft documentation](https://docs.microsoft.com/en-us/azure/devops/release-notes/2018/sep-10-azure-devops-launch#switch-existing-organizations-to-use-the-new-domain-name-url). + +## Requirements + +Configuring a new VCS provider requires permission to [manage VCS settings](/terraform/enterprise/users-teams-organizations/permissions#manage-vcs-settings) for the organization. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Before you begin, enable `Third-party application access via OAuth` in Azure DevOps Services settings. + +1. Log in to [Azure DevOps Services](https://dev.azure.com/). +2. Click **Organization settings**. +3. Click **Policies** under **Security**. +4. Enable the **Third-party application access via OAuth** setting. + + ![Azure DevOps Services Screenshot: Policies Third-party application access via Oauth](/img/docs/azure-devops-services-oauth-policies.png) + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +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. + +Leave this page open in a browser tab. You will copy values from this page into Azure DevOps in the next step, and in later steps you will continue configuring HCP Terraform. + +## Step 2: From your Azure DevOps Services Profile, Create a New Application + +1. In a new browser tab, open your [Azure DevOps Services Profile](https://aex.dev.azure.com), and log in to your Azure DevOps Services account if necessary. A page with a list of your organizations appears. + + ~> **Important:** The Azure DevOps Services account you use for connecting HCP Terraform must have Project Collection Administrator access to any projects containing repositories of Terraform configurations, since creating webhooks requires admin permissions. It is not possible to create custom access roles with lower levels of privilege, as Microsoft does not currently allow delegation of this capability. If you're unable to load the link above, you can create a new application for the next step at one of the following links: `https://aex.dev.azure.com/app/register?mkt=en-US` or `https://app.vsaex.visualstudio.com/app/register?mkt=en-US`. + +2. Go into your preferred organization. + +3. Click your user icon and then click the **ellipses (...) ** and select **User settings**. + +4. From the User settings menu, click **Profile**. Your profile page appears. + +5. Click **Authorizations**. The Authorized OAuth Apps page appears. + +6. Click the link to register a new app. A form appears asking for your company and application information. + +7. Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear and includes controls for copying values to your clipboard. Here is an example: + + | Field name | Value | + | -------------------------- | ----------------------------------------------------------------------------- | + | Company name | HashiCorp | + | Application Name | HCP Terraform (``) | + | Application website | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + | Authorization callback URL | `https://app.terraform.io/` | + + In the **Authorized scopes** section, select only **Code (read)** and **Code (status)** and then click **Create Application.** + + ![Azure DevOps Services Screenshot: Required permissions when creating a new application in your Azure DevOps Services Profile](/img/docs/azure-devops-services-application-permissions.png) + + ~> **Important:** Do not add any additional scopes beyond **Code (read)** and **Code (status),** as this can prevent HCP Terraform from connecting. Note that these authorized scopes cannot be updated after the application is created; to fix incorrect scopes you must delete and re-create the application. + +8. After creating the application, the next page displays its details. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **App ID** and **Client Secret** from this page. + + If you accidentally close this details page and need to find it later, you can reach it from the **Applications and Services** links in your profile. + +## Step 3: On HCP Terraform, Set up Your Provider + +1. (Optional) Enter a **Name** for this VCS connection. + +2. Enter your Azure DevOps Services application's **App ID** and **Client Secret**. These can be found in the application's details, which should still be open in the browser tab from Step 2. + +3. Click **Connect and continue.** This takes you to a page on Azure DevOps Services, asking whether you want to authorize the app. Click the **Accept** button and you'll be redirected back to HCP Terraform. + + -> **Note:** If you receive a 404 error from Azure DevOps Services, it likely means your callback URL has not been configured correctly. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new Azure DevOps Services client. + +### 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. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need an SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and Azure DevOps Services; generate a new one 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, it retains it and will use it when authenticating to Azure DevOps Services. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Azure DevOps Services.com. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the Azure DevOps Services account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. 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. + +## Finished + +At this point, Azure DevOps Services access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/bitbucket-cloud.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/bitbucket-cloud.mdx new file mode 100644 index 0000000000..41e33f8676 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/bitbucket-cloud.mdx @@ -0,0 +1,127 @@ +--- +page_title: Set up the Bitbucket Cloud VCS provider +description: >- + Learn how to use Bitbucket Cloud with workspaces and private registry modules + in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the Bitbucket Cloud VCS provider + +This topic describes how to connect Bitbucket Cloud to HCP Terraform. Bitbucket Cloud is the cloud-hosted version of Bitbucket. For self-hosted Bitbucket Data Center instances, refer to [Configuring Bitbucket Data Center Access](/terraform/enterprise/vcs/bitbucket-data-center). Refer to [Connecting VCS Providers to HCP Terraform](/terraform/enterprise/vcs) for other supported VCS providers. + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get callback URL. | +| Register your HCP Terraform organization as a new app. Provide callback URL. Get ID and key. |   | +|   | Provide HCP Terraform with ID and key. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the Bitbucket Cloud-specific versions of these steps. + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +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 **Bitbucket** and then select **Bitbucket Cloud** from the menu. The page moves to the next step. + +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: On Bitbucket Cloud, Create a New OAuth Consumer + +1. In a new browser tab, open [Bitbucket Cloud](https://bitbucket.org) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. + +2. Navigate to Bitbucket's "Add OAuth Consumer" page. + + This page is located at `https://bitbucket.org//workspace/settings/oauth-consumers/new`. You can also reach it through Bitbucket's menus: + + - Click your profile picture and choose the workspace you want to access. + - Click "Settings". + - Click "OAuth consumers," which is in the "Apps and Features" section. + - On the OAuth settings page, click the "Add consumer" button. + +3. This page has a form with several text fields and checkboxes. + + Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the text fields as follows: + + | Field | Value | + | ------------ | ----------------------------------------------------------------------------- | + | Name | HCP Terraform (``) | + | Description | Any description of your choice. | + | Callback URL | `https://app.terraform.io/` | + | URL | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + + Ensure that the "This is a private consumer" option is checked. Then, activate the following permissions checkboxes: + + | Permission type | Permission level | + | --------------- | ---------------- | + | Account | Write | + | Repositories | Admin | + | Pull requests | Write | + | Webhooks | Read and write | + +4. Click the "Save" button, which returns you to the OAuth settings page. + +5. Find your new OAuth consumer under the "OAuth Consumers" heading, and click its name to reveal its details. + + Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Key** and **Secret.** + +## Step 3: On HCP Terraform, Set up Your Provider + +1. Enter the **Key** and **Secret** from the previous step, as well as an optional **Name** for this VCS connection. + +2. Click "Connect and continue." This takes you to a page on Bitbucket Cloud asking whether you want to authorize the app. + +3. Click the blue "Grant access" button to proceed. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new Bitbucket Cloud client. + +### 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. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need an SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and Bitbucket Cloud; generate a new one 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, it retains it and will use it when authenticating to Bitbucket Cloud. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Bitbucket Cloud. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the Bitbucket Cloud account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. 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. + +## Finished + +At this point, Bitbucket Cloud access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/bitbucket-data-center.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/bitbucket-data-center.mdx new file mode 100644 index 0000000000..7951e3e2d7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/bitbucket-data-center.mdx @@ -0,0 +1,128 @@ +--- +page_title: Set up the Bitbucket Data Center VCS provider +description: >- + Learn how to use Bitbucket Data Center with workspaces and private registry + modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the Bitbucket Data Center VCS provider + +This topic describes how to connect Bitbucket Data Center to HCP Terraform. For instructions on how to connect Bitbucket Cloud, refer to [Configuring Bitbucket Cloud Access](/terraform/enterprise/vcs/bitbucket-cloud). Refer to [Connecting VCS Providers to HCP Terraform](/terraform/enterprise/vcs) for other supported VCS providers. + +**Bitbucket Server is deprecated**. Atlassian ended support for Bitbucket Server on February 15, 2024, and recommends using either Bitbucket Data Center (v8.0 or newer) or Bitbucket Cloud instead. Refer to the [Atlassian documentation](https://bitbucket.org/blog/cloud-migration-benefits) for additional information. + +HCP Terraform will end support Bitbucket Server on August 15, 2024. Terraform Enterprise will also end support for Bitbucket Server in Terraform Enterprise v202410. [Contact HashiCorp support](https://support.hashicorp.com/hc/en-us) if you have any questions regarding this change. + +## Overview + +The following steps provide an overview of how to connect HCP Terraform and Terraform Enterprise to Bitbucket Data Center: + +1. Add a new VCS provider to HCP Terraform or Enterprise. +2. Create a new application link in Bitbucket. +3. Create an SSH key pair. SSH keys must have an empty passphrase because HCP Terraform cannot use SSH keys that require a passphrase. +4. Add an SSH key to Bitbucket. You must complete this step as a non-administrator user in Bitbucket. +5. Add the private SSH key to Terraform. + +## Requirements + +- You must have permission to manage VCS settings for the organization. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +- You must have OAuth authentication credentials for Bitbucket Data Center. + +- Your instance of Bitbucket Data Center must be internet-accessible on its SSH and HTTP(S) ports. This is because HCP Terraform must be able to contact Bitbucket Data Center over both SSH and HTTP or HTTPS during setup and during normal operation. + +- HCP Terraform must have network connectivity to Bitbucket Data Center instances. Note that [Bitbucket Data Center's default ports](https://confluence.atlassian.com/bitbucketserverkb/which-ports-does-bitbucket-server-listen-on-and-what-are-they-used-for-806029586.html) are `7999` for SSH and `7990` for HTTP. Check your configuration to confirm your BitBucket instance's real ports. + +## Add a new VCS provider to 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. Choose **Bitbucket Data Center** from the **Bitbucket** drop-down menu. + +5. (Optional) Enter a **Name** for this VCS connection. + +6. Specify the URL of your Bitbucket Data Center instance in the **HTTP URL** and **API URL** fields. If the context path is not set for your Bitbucket Data Center instance, the **API URL** is the same as the **HTTP URL**. Refer to the [Atlassian documentation](https://confluence.atlassian.com/bitbucketserver/moving-bitbucket-server-to-a-different-context-path-776640153.html) for additional information. Specify the following values if the context path is set for your Bitbucket Data Center instance: + + - Set the **HTTP URL** field to your Bitbucket Data Center instance URL and add the context path: `https:///`. + - Set the **API URL** field to your Bitbucket Data Center instance URL: `https://`. + + By default, HCP Terraform uses port `80` for HTTP and `443` for HTTPS. If Bitbucket Data Center is configured to use non-standard ports or is behind a reverse proxy, you may need to include the port number in the URL. + +7. You can either generate new consumer and public keys that you can use to create a new application link in Bitbucket Data Center described in [Create an application link](#create-an-application-link) or use keys from an existing application link: + - To generate new keys, click **Continue**. Do not leave this screen until you have copied the key values. + - To use existing keys, enable the **Use Custom Keys** option and enter them into the fields. + +## Create an application link + +1. Log into Bitbucket Data Center as an admin. + +2. Open the **Application Links** administration page using the navigation or by entering `https:///plugins/servlet/applinks/listApplicationLinks` in your browser's address bar. + +3. Click **Application Links** in the sidebar, then click **Create new link**. + +4. Choose **Atlassian product** as the link type. This option also works for external applications and lets you continue to use OAuth 1.0 integrations. + +5. Enter `https://app.terraform.io` or the hostname of your Terraform Enterprise instance when prompted. You can only specify the main URL once. To connect multiple HCP Terraform organizations to the same Bitbucket Data Center instance, enter the organization URL when creating the link instead. The organization URL is the HCP Terraform URL or Terraform Enterprise hostname appended with `/app/`. + +6. When prompted, confirm that you wish to use the URL as entered. If you specified HCP Terraform's main URL, click **Continue**. If you specified an organization URL, enable the **Use this URL** option and then click **Continue**. + +7. In the **Link applications** dialog, configure the following settings: + + - Specify `HCP Terraform ` in the **Application Name** field + - Choose **Generic Application** from the **Application Type** drop-down menu + - Enable the **Create incoming link** option + + Leave all the other fields empty. + +8. Click **Continue**. The **Link applications** screen progresses to the second configuration screen. + +9. In the **Consumer Key** and **Public Key** fields, enter the key values you created in the [Add a new VCS provider to Terraform](#add-a-new-vcs-provider-to-terraform) instructions. + +10. In the **Consumer Name** field, enter `HCP Terraform ()`. + +11. Click **Continue**. Bitbucket prompts you to authorize Terraform to make changes. Before you proceed, verify that you are logged in with the user account that HCP Terraform will use to access Bitbucket and not as a Bitbucket administrator. If Bitbucket returns a 500 error instead of the authorization screen, Terraform may have been unable to reach your Bitbucket Data Center instance. + +12. Click **Allow** and enter the SSH key when prompted. + +## Create an SSH key for Terraform + +On a secure workstation, create an SSH keypair that HCP Terraform or Terraform Enterprise can use to connect to Bitbucket Data Center. The command for generating SSH keys depends on your OS. The following example for Linux creates 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" +``` + +Do not specify a passphrase because Terraform cannot use SSH keys that require a passphrase. + +## Add an SSH key to Bitbucket + +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 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. +6. Click **Add key** and enter the SSH public key you created in [Create an SSH key for Terraform](#create-an-ssh-key-for-terraform) into the text field. Open the `.pub` file to get the key value. +7. Click **Add key** to finish adding the key. + +## Add an SSH private key + +Complete the following steps in HCP Terraform or Terraform Enterprise to request access to Bitbucket and add the SSH private key. + +1. Open the **SSH keys** settings page and click **Add a private SSH key**. A large text field appears. +2. Enter the text of the **SSH private key** you created in [Create an SSH key for Terraform](#create-an-ssh-key-for-terraform) and click **Add SSH Key**. + +## Next steps + +After completing these instructions, you can create Terraform workspaces based on your organization's shared repositories. Refer to the following resources for additional guidance: + +- [Creating Workspaces](/terraform/enterprise/workspaces/create) in HCP Terraform +- [Creating Workspaces](/terraform/enterprise/workspaces/create) in Terraform Enterprise diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/github-enterprise.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/github-enterprise.mdx new file mode 100644 index 0000000000..ffdc1dd99f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/github-enterprise.mdx @@ -0,0 +1,140 @@ +--- +page_title: Set up the GitHub Enterprise VCS provider +description: >- + Learn how to use an on-premise installation of GitHub Enterprise with + workspaces and private registry modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the GitHub Enterprise VCS provider + +These instructions are for using a self-hosted installation of GitHub Enterprise for HCP Terraform's VCS features. [GitHub.com has separate instructions,](/terraform/enterprise/vcs/github-enterprise) as do the [other supported 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)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get callback URL. | +| Register your HCP Terraform organization as a new app. Provide callback URL. Get ID and key. |   | +|   | Provide HCP Terraform with ID and key. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the GitHub Enterprise versions of these steps. + +~> **Important:** HCP Terraform needs to contact your GitHub Enterprise instance during setup and during normal operation. For the SaaS version of HCP Terraform, this means GitHub Enterprise must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitHub Enterprise instances. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +## Step 1: On HCP Terraform, begin adding a new VCS provider + +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 a VCS provider**. The **Add VCS Provider** page appears. + +4. Select **GitHub** and then select **GitHub Enterprise** from the menu. The page moves to the next step. + +5. In the "Set up provider" step, fill in the **HTTP URL** and **API URL** of your GitHub Enterprise instance, as well as an optional **Name** for this VCS connection. + + | Field | Value | + | -------- | ------------------------------------------- | + | HTTP URL | `https://` | + | API URL | `https:///api/v3` | + +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: On GitHub, create a new OAuth application + +1. In a new browser tab, open your GitHub Enterprise instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. + +2. Navigate to GitHub's Register a New OAuth Application page. + + This page is located at `https:///settings/applications/new`. You can also reach it through GitHub's menus: + + - Click your profile picture and choose "Settings." + - Click "OAuth Apps" (under the "Developer settings" section). + - Click the "Register a new application" button. + +3. This page has a form with four text fields. + + Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the text fields as follows: + + | Field name | Value | + | -------------------------- | ----------------------------------------------------------------------------- | + | Application Name | HCP Terraform (``) | + | Homepage URL | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + | Application Description | Any description of your choice. | + | Authorization callback URL | `https://app.terraform.io/` | + +4. Click the "Register application" button, which creates the application and takes you to its page. + +5. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance. + +6. Click the "Generate a new client secret" button. You will need this secret in the next step. + +7. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Client ID** and **Client Secret.** + +## Step 3: On HCP Terraform, set up your provider + +1. Enter the **Client ID** and **Client Secret** from the previous step. + +2. Click "Connect and continue." This takes you to a page on your GitHub Enterprise instance, asking whether you want to authorize the app. + +3. The authorization page lists any GitHub organizations this account belongs to. If there is a **Request** button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions. See [About OAuth App access restrictions](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). + + If it results in a 500 error, it usually means HCP Terraform was unable to reach your GitHub Enterprise instance. + +4. Click the green "Authorize ``" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation. + +## Step 4: On HCP Terraform, configure advanced settings (optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If you don't need to configure advanced settings: + +1. Click the **Skip and finish** button. This returns you to HCP Terraform's VCS Providers page, which now includes your new GitHub Enterprise client. + +### 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. + +2. Click the **Update VCS Provider** button to save your selections. + +### If you need an SSH keypair: + +#### Important notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitHub Enterprise; generate a new one 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, it retains it and will use it when authenticating to GitHub Enterprise. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to Github Enterprise. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitHub Enterprise account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. 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. + +## Step 5: Contact Your GitHub organization admins + +If your organization uses OAuth app access restrictions, you had to click a **Request** button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform can access your organization's shared repositories. + +If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request. + +## Finished + +At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub Enterprise repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/github.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/github.mdx new file mode 100644 index 0000000000..0ffe1630c9 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/github.mdx @@ -0,0 +1,145 @@ +--- +page_title: Set up the GitHub.com OAuth VCS provider +description: >- + Learn how to use GitHub.com with workspaces and private registry modules in + Terraform Enterprise with a per-organization OAuth connection. +source: terraform-docs-common +--- + +# Set up the GitHub.com OAuth VCS provider + +These instructions are for using GitHub.com for HCP Terraform's VCS features, using a per-organization OAuth connection with the permissions of one particular GitHub user. [GitHub Enterprise has separate instructions,](/terraform/enterprise/vcs/github-enterprise) as do the [other supported VCS providers.](/terraform/enterprise/vcs) + + + +For new users on HCP Terraform, we recommend using our [configuration-free GitHub App](/terraform/enterprise/vcs/github-app) to access repositories instead. + + + +For Terraform Enterprise site admins, you can create your own [GitHub App](/terraform/enterprise/admin/application/github-app-integration) to access repositories. + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| ---------------------------------------------------------------------------- | ----------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get callback URL. | +| Register your HCP Terraform organization as a new app. Provide callback URL. |   | +|   | Provide HCP Terraform with ID and key. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the GitHub versions of these steps. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +## Step 1: On HCP Terraform, begin adding a new VCS provider + +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 a VCS provider**. The **Add VCS Provider** page appears. + +4. Select **GitHub** and then select **GitHub.com (Custom)** from the menu. The page moves to the next step. + +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: On GitHub, create a new OAuth application + +On the HCP Terraform **Add VCS Provider** page, click **register a new OAuth Application**. This opens GitHub.com in a new browser tab with the OAuth application settings pre-filled. + +Alternately, create the OAuth application manually on GitHub.com. + +### Manual steps + +1. In a new browser tab, open [github.com](https://github.com) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. + +2. Navigate to GitHub's [Register a New OAuth Application](https://github.com/settings/applications/new) page. + + This page is located at . You can also reach it through GitHub's menus: + + - Click your profile picture and choose "Settings." + - Click "Developer settings," then make sure you're on the "OAuth Apps" page (not "GitHub Apps"). + - Click the "New OAuth App" button. + +3. This page has a form with four text fields. + + Fill out the fields with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the text fields as follows: + + | Field name | Value | + | -------------------------- | ----------------------------------------------------------------------------- | + | Application Name | HCP Terraform (``) | + | Homepage URL | `https://app.terraform.io` (or the URL of your Terraform Enterprise instance) | + | Application Description | Any description of your choice. | + | Authorization callback URL | `https://app.terraform.io/` | + +### Register the OAuth application + +1. Click the "Register application" button, which creates the application and takes you to its page. + +2. Download this image of the HCP Terraform logo and upload it with the "Upload new logo" button or the drag-and-drop target. This optional step helps you identify HCP Terraform's pull request checks at a glance. + +3. Click the **Generate a new client secret** button. You will need this secret in the next step. + +4. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Client ID** and **Client Secret.** + +## Step 3: On HCP Terraform, set up your provider + +1. Enter the **Client ID** and **Client Secret** from the previous step, as well as an optional **Name** for this VCS connection. + +2. Click "Connect and continue." This takes you to a page on GitHub.com, asking whether you want to authorize the app. + +3. The authorization page lists any GitHub organizations this account belongs to. If there is a **Request** button next to the organization that owns your Terraform code repositories, click it now. Note that you need to do this even if you are only connecting workspaces to private forks of repositories in those organizations since those forks are subject to the organization's access restrictions. See [About OAuth App access restrictions](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions). + +4. Click the green "Authorize ``" button at the bottom of the authorization page. GitHub might request your password or multi-factor token to confirm the operation. + +## Step 4: On HCP Terraform, configure advanced settings (optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If you don't need to configure advanced settings: + +1. Click the **Skip and finish** button. This returns you to HCP Terraform's **VCS Providers** page, which now includes your new GitHub client. + +### 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. + +2. Click the **Update VCS Provider** button to save your selections. + +### If you need an SSH keypair: + +#### Important notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitHub; generate a new one 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, it retains it and will use it when authenticating to GitHub. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitHub.com. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitHub.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. 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. + +## Step 5: Contact your GitHub organization admins + +If your organization uses OAuth app access restrictions, you had to click a **Request** button when authorizing HCP Terraform, which sent an automated email to the administrators of your GitHub organization. An administrator must approve the request before HCP Terraform can access your organization's shared repositories. + +If you're a GitHub administrator, check your email now and respond to the request; otherwise, contact whoever is responsible for GitHub accounts in your organization, and wait for confirmation that they've approved your request. + +## Finished + +At this point, GitHub access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared GitHub repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/gitlab-com.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/gitlab-com.mdx new file mode 100644 index 0000000000..43bee92f73 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/gitlab-com.mdx @@ -0,0 +1,119 @@ +--- +page_title: Set up the GitLab.com VCS provider +description: >- + Learn how to use GitLab.com repositories with workspaces and private registry + modules in Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the GitLab.com VCS provider + +These instructions are for using GitLab.com for HCP Terraform's VCS features. [GitLab CE and GitLab EE have separate instructions,](/terraform/enterprise/vcs/gitlab-eece) as do the [other supported 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)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get redirect URI. | +| Register your HCP Terraform organization as a new app. Provide redirect URI. |   | +|   | Provide HCP Terraform with application ID and secret. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the GitLab.com versions of these steps. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +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 **GitLab** and then select **GitLab.com** from the menu. The page moves to the next step. + +5. Locate the "Redirect URI" and copy it to your clipboard; you'll paste it in the next step. + +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: On GitLab, Create a New Application + +1. In a new browser tab, open [gitlab.com](https://gitlab.com) and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have Maintainer access** to any shared repositories of Terraform configurations, since creating webhooks requires Maintainer permissions. Refer to [the GitLab documentation](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions) for details. + +2. Navigate to GitLab's [User Settings > Applications](https://gitlab.com/-/profile/applications) page. + + This page is located at . You can also reach it through GitLab's menus: + + - Click your profile picture and choose "Settings." + - Click "Applications." + +3. This page has a list of applications and a form for adding new ones. The form has two text fields and some checkboxes. + + Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the form as follows: + + | Field | Value | + | ----------------------- | ---------------------------------------------------------------------------------------------- | + | Name | HCP Terraform (``) | + | Redirect URI | `https://app.terraform.io/`, the redirect URI you copied from HCP Terraform | + | Confidential (checkbox) | ✔️ (enabled) | + | Scopes (all checkboxes) | api | + + +1. Click the "Save application" button, which creates the application and takes you to its page. + +2. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Application ID** and **Secret.** + +## Step 3: On HCP Terraform, Set up Your Provider + +1. Enter the **Application ID** and **Secret** from the previous step, as well as an option **Name** for this VCS connection. + +2. Click **Connect and continue.** This takes you to a page on GitLab.com, which asks if you want to authorize the app. + +3. Click the green **Authorize** button at the bottom of the authorization page. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new GitLab client. + +### 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. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need an SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitLab; generate a new one 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, it retains it and will use it when authenticating to GitLab. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create an SSH keypair that HCP Terraform can use to connect to GitLab.com. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitLab.com account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. 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. + +## Finished + +At this point, GitLab.com access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/gitlab-eece.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/gitlab-eece.mdx new file mode 100644 index 0000000000..a4b484859d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/gitlab-eece.mdx @@ -0,0 +1,133 @@ +--- +page_title: Set up the GitLab EE and CE VCS provider +description: >- + Learn how to use on-premise installation of GitLab Enterprise Edition (EE) or + GitLab Community Edition (CE) with workspaces and private registry module in + Terraform Enterprise. +source: terraform-docs-common +--- + +# Set up the GitLab EE and CE VCS provider + +These instructions are for using an on-premise installation of GitLab Enterprise Edition (EE) or GitLab Community Edition (CE) for HCP Terraform's VCS features. [GitLab.com has separate instructions,](/terraform/enterprise/vcs/gitlab-com) as do the [other supported 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)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Connecting HCP Terraform to your VCS involves four steps: + +| On your VCS | On HCP Terraform | +| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +|   | Create a new connection in HCP Terraform. Get redirect URI. | +| Register your HCP Terraform organization as a new app. Provide redirect URI. Get ID and key. |   | +|   | Provide HCP Terraform with application ID and secret. Request VCS access. | +| Approve access request. |   | + +The rest of this page explains the on-premise GitLab versions of these steps. + +~> **Important:** HCP Terraform needs to contact your GitLab instance during setup and during normal operation. For the SaaS version of HCP Terraform, this means GitLab must be internet-accessible; for Terraform Enterprise, you must have network connectivity between your Terraform Enterprise and GitLab instances. + +-> **Note:** Alternately, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + +-> **Version Note:** HCP Terraform supports GitLab versions 9.0 and newer. HashiCorp does not test older versions of GitLab with HCP Terraform, and they might not work as expected. Also note that, although we do not deliberately remove support for versions that have reached end of life (per the [GitLab Support End of Life Policy](https://docs.gitlab.com/ee/policy/maintenance.html#patch-releases)), our ability to resolve customer issues with end of life versions might be limited. + +## Step 1: On HCP Terraform, Begin Adding a New VCS Provider + +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. Select **GitLab** and then select **GitLab Enterprise Edition** or **GitLab Community Edition** from the menu. The page moves to the next step. + +4. In the "Set up provider" step, fill in the **HTTP URL** and **API URL** of your GitLab Enterprise Edition or GitLab Community Edition instance, as well as an optional **Name** for this VCS connection. Click "Continue." + + | Field | Value | + | -------- | ------------------------------------------- | + | HTTP URL | `https://` | + | API URL | `https:///api/v4` | + + Note that HCP Terraform uses GitLab's v4 API. + +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: On GitLab, Create a New Application + +1. In a new browser tab, open your GitLab instance and log in as whichever account you want HCP Terraform to act as. For most organizations this should be a dedicated service user, but a personal account will also work. + + ~> **Important:** The account you use for connecting HCP Terraform **must have admin (master) access** to any shared repositories of Terraform configurations, since creating webhooks requires admin permissions. Do not create the application as an administrative application not owned by a user; HCP Terraform needs user access to repositories to create webhooks and ingress configurations. + + ~> **Important**: In GitLab CE or EE 10.6 and up, you may also need to enable **Allow requests to the local network from hooks and services** on the "Outbound requests" section inside the Admin area under Settings (`/admin/application_settings/network`). Refer to [the GitLab documentation](https://docs.gitlab.com/ee/security/webhooks.html) for details. + +2. Navigate to GitLab's "User Settings > Applications" page. + + This page is located at `https:///profile/applications`. You can also reach it through GitLab's menus: + + - Click your profile picture and choose "Settings." + - Click "Applications." + +3. This page has a list of applications and a form for adding new ones. The form has two text fields and some checkboxes. + + Fill out the fields and checkboxes with the corresponding values currently displayed in your HCP Terraform browser tab. HCP Terraform lists the values in the order they appear, and includes controls for copying values to your clipboard. + + Fill out the form as follows: + + | Field | Value | + | ------------------------------- | ---------------------------------------------- | + | Name | HCP Terraform (``) | + | Redirect URI | `https://app.terraform.io/` | + | Confidential (checkbox) | ✔️ (enabled) | + | Expire access tokens (checkbox) | (no longer required) | + | Scopes (all checkboxes) | api | + + -> **Note:** For previous versions of HCP Terraform and GitLab, we recommended disabling a setting called `Expire access tokens`. This action was required because Gitlab marked OAuth tokens as expired after 2 hours, but HCP Terraform only refreshed tokens after 6 hours. This setting does not exist on Gitlab v15+ and HCP Terraform now refreshes tokens more often. + +4. Click the "Save application" button, which creates the application and takes you to its page. + +5. Leave this page open in a browser tab. In the next step, you will copy and paste the unique **Application ID** and **Secret.** + +## Step 3: On HCP Terraform, Set up Your Provider + +1. On the "Configure settings" step on HCP Terraform, enter the **Application ID** and **Secret** from the previous step. + +2. Click **Connect and continue.** This takes you to a page on GitLab asking whether you want to authorize the app. Alternatively, if you are redirected to a 500 error, it usually means HCP Terraform was unable to reach your GitLab instance. + +3. Click the green **Authorize** button at the bottom of the authorization page. + +## Step 4: On HCP Terraform, Configure Advanced Settings (Optional) + +The settings in this section are optional. The Advanced Settings you can configure are: + +- **Scope of VCS Provider** - You can configure which workspaces can use repositories from this VCS provider. By default the **All Projects** option is selected, meaning this VCS provider is available to be used by all workspaces in the organization. +- **Set up a PEM formatted SSH Keypair** - Most organizations will not need to add an SSH key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. You can add or update the SSH key at a later time. + +### If You Don't Need to Configure Advanced Settings: + +1. Click the **Skip and Finish** button. This returns you to HCP Terraform's VCS Provider page, which now includes your new GitLab client. + +### 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. + +2. Click the **Update VCS Provider** button to save your selections. + +### If You Do Need a PEM formatted SSH Keypair: + +#### Important Notes + +- SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. +- Do not use your personal SSH key to connect HCP Terraform and GitLab; generate a new one 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, it retains it and will use it when authenticating to GitLab. +- **Protect this private key carefully.** It can push code to the repositories you use to manage your infrastructure. Take note of your organization's policies for protecting important credentials and be sure to follow them. + +1. On a secure workstation, create a PEM formatted SSH keypair that HCP Terraform can use to connect to GitLab. The exact command depends on your OS, but is usually something like: + `ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise"` + This creates a `service_terraform` file with the private key, and a `service_terraform.pub` file with the public key. This SSH key **must have an empty passphrase**. HCP Terraform cannot use SSH keys that require a passphrase. + +2. While logged into the GitLab account you want HCP Terraform to act as, navigate to the SSH Keys settings page, add a new SSH key and paste the value of the SSH public key you just created. + +3. 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. + +## Finished + +At this point, GitLab access for HCP Terraform is fully configured, and you can create Terraform workspaces based on your organization's shared repositories. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/index.mdx new file mode 100644 index 0000000000..4b1c37c0c5 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/index.mdx @@ -0,0 +1,137 @@ +--- +page_title: Connect to VCS Providers +description: >- + Version control system (VCS) connections integrate Terraform Enterprise into + your workflow. Learn how to automate Terraform runs when you commit changes to + your code. +source: terraform-docs-common +--- + +# Connect to VCS Providers + +HCP Terraform is more powerful when you integrate it with your version control system (VCS) provider. Although you can use many of HCP Terraform's features without one, a VCS connection provides additional features and improved workflows. In particular: + +- When workspaces are linked to a VCS repository, HCP Terraform can [automatically initiate Terraform runs](/terraform/enterprise/run/ui) when changes are committed to the specified branch. +- HCP Terraform makes code review easier by [automatically predicting](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) how pull requests will affect infrastructure. +- Publishing new versions of a [private Terraform module](/terraform/enterprise/registry/publish-modules) is as easy as pushing a tag to the module's repository. + +We recommend configuring VCS access when first setting up an organization, and you might need to add additional VCS providers later depending on how your organization grows. + +Configuring a new VCS provider requires permission to manage VCS settings for the organization. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Supported VCS Providers + +HCP Terraform supports the following VCS providers: + + + +- [GitHub.com](/terraform/enterprise/vcs/github-app) + + + +- [GitHub App for TFE](/terraform/enterprise/admin/application/github-app-integration) +- [GitHub.com (OAuth)](/terraform/enterprise/vcs/github) +- [GitHub Enterprise](/terraform/enterprise/vcs/github-enterprise) +- [GitLab.com](/terraform/enterprise/vcs/gitlab-com) +- [GitLab EE and CE](/terraform/enterprise/vcs/gitlab-eece) +- [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 (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). + +## How HCP Terraform Uses VCS Access + +Most workspaces in HCP Terraform are associated with a VCS repository, which provides Terraform configurations for that workspace. To find out which repos are available, access their contents, and create webhooks, HCP Terraform needs access to your VCS provider. + +Although HCP Terraform's API lets you create workspaces and push configurations to them without a VCS connection, the primary workflow expects every workspace to be backed by a repository. + +To use configurations from VCS, HCP Terraform needs to do several things: + +- Access a list of repositories, to let you search for repos when creating new workspaces. +- Register webhooks with your VCS provider, to get notified of new commits to a chosen branch. +- Download the contents of a repository at a specific commit in order to run Terraform with that code. + +~> **Important:** HCP Terraform usually performs VCS actions using a designated VCS user account, but it has no other knowledge about your VCS's authorization controls and does not associate HCP Terraform user accounts with VCS user accounts. This means HCP Terraform's VCS user might have a different level of access to repositories than any given HCP Terraform user. Keep this in mind when selecting a VCS user, as it may affect your security posture in one or both systems. + +### Webhooks + +HCP Terraform uses webhooks to monitor new commits and pull requests. + +- When someone adds new commits to a branch, any HCP Terraform workspaces based on that branch will begin a Terraform run. Usually a user must inspect the plan output and approve an apply, but you can also enable automatic applies on a per-workspace basis. You can prevent automatic runs by locking a workspace. A run will only occur if the workspace has not previously processed a run for the commit SHA. +- When someone submits a pull request/merge request to a branch, any HCP Terraform workspaces based on that branch will perform a [speculative plan](/terraform/enterprise/run/remote-operations#speculative-plans) with the contents of the request and links to the results on the PR's page. This helps you avoid merging PRs that cause plan failures. + +~> **Important:** In Terraform Enterprise, integration with a SaaS VCS provider (GitHub.com, GitLab.com, Bitbucket Cloud, or Azure DevOps Services) requires ingress from the public internet. This lets the inbound web hooks reach Terraform Enterprise. You should also configure appropriate security controls, such as a Web Application Firewall (WAF). + +### SSH Keys + +For most supported VCS providers, HCP Terraform does not need an SSH key. This is because Terraform can do everything it needs with the provider's API and an OAuth token. The exceptions are Azure DevOps Server and Bitbucket Data Center, which require an SSH key for downloading repository contents. Refer to the setup instructions for [Azure DevOps Server](/terraform/enterprise/vcs/azure-devops-server) and [Bitbucket Data Center](/terraform/enterprise/vcs/bitbucket-data-center) for details. + +For other VCS providers, most organizations will not need to add an SSH private key. However, if the organization repositories include Git submodules that can only be accessed via SSH, an SSH key can be added along with the OAuth credentials. + +For VCS providers where adding an SSH private key is optional, SSH will only be used to clone Git submodules. All other Git operations will still use HTTPS. + +If submodules will be cloned via SSH from a private VCS instance, SSH must be running on the standard port 22 on the VCS server. + +To add an SSH key to a VCS connection, finish configuring OAuth in the organization settings, and then use the "add a private SSH key" link on the VCS Provider settings page to add a private key that has access to the submodule repositories. When setting up a workspace, if submodules are required, select "Include submodules on clone". More at [Workspace settings](/terraform/enterprise/workspaces/settings). + +### Multiple VCS Connections + +If your infrastructure code is spread across multiple VCS providers, you can configure multiple VCS connections. You can choose which VCS connection to use whenever you create a new workspace. + +#### Scoping VCS Connections using Projects + +You can configure which projects can use repositories from a VCS connection. By default each VCS connection is enabled for all workspaces in the organization. If you need to limit which projects can use repositories from a given VCS connection, you can change this setting to enable the connection for only workspaces in the selected projects. + +## Configuring VCS Access + +HCP Terraform uses the OAuth protocol to authenticate with VCS providers. + +~> **Important:** Even if you've used OAuth before, read the instructions carefully. Since HCP Terraform's security model treats each _organization_ as a separate OAuth application, we authenticate with OAuth's developer workflow, which is more complex than the standard user workflow. + +The exact steps to authenticate are different for each VCS provider, but they follow this general order: + +| On your VCS | On HCP Terraform | +| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| Register your HCP Terraform organization as a new app. Get ID and key. |   | +|   | Tell HCP Terraform how to reach VCS, and provide ID and key. Get callback URL. | +| Provide callback URL. |   | +|   | Request VCS access. | +| Approve access request. |   | + +For complete details, click the link for your VCS provider: + +- [GitHub](/terraform/enterprise/vcs/github) +- [GitHub Enterprise](/terraform/enterprise/vcs/github-enterprise) +- [GitLab.com](/terraform/enterprise/vcs/gitlab-com) +- [GitLab EE and CE](/terraform/enterprise/vcs/gitlab-eece) +- [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) + +-> **Note:** Alternatively, you can skip the OAuth configuration process and authenticate with a personal access token. This requires using HCP Terraform's API. For details, see [the OAuth Clients API page](/terraform/enterprise/api-docs/oauth-clients). + + + +### Private VCS + +You can use self-hosted HCP Terraform Agents to connect HCP Terraform to your private VCS provider, such as GitHub Enterprise, GitLab Enterprise, and BitBucket Data Center. For more information, refer to [Connect to Private VCS Providers](/terraform/enterprise/vcs/private). + + + +## 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)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +To view VCS events for your organization, go to your organization's settings and click **Events**. The **VCS Events** page appears. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/vcs/troubleshooting.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/troubleshooting.mdx new file mode 100644 index 0000000000..182c9ba0bb --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/vcs/troubleshooting.mdx @@ -0,0 +1,227 @@ +--- +page_title: Troubleshoot VCS providers in Terraform Enterprise +description: >- + Learn how to address common problems in VCS integrations for Terraform + Enterprise. +source: terraform-docs-common +--- + +# Troubleshoot VCS providers + +This page collects solutions to the most common problems our users encounter with VCS integration in HCP Terraform. + +## Azure DevOps + +### Required status checks not sending + +When configuring [status checks with Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/git/pr-status-policy) the web interface may auto populate Genre and Name fields (beneath "Status to check") with incorrect values that do not reflect what HCP Terraform is sending. +To function correctly as required checks the Genre must be populated with "Terraform Cloud" (or the first segment for a Terraform Enterprise install), and the remainder of the status check goes in the Name field. This requires using the "Enter genre/name separately" checkbox to not use the default configuration. + +In the example below the status check is named `Terraform Cloud/paul-hcp/gianni-test-1` and needs to be configured with Genre `Terraform Cloud` and Name `paul-hcp/gianni-test-1`. + +![Azure DevOps screenshot: configuring required status checks correctly](/img/docs/ado-required-status-check.png) + +With an older version of Azure DevOps Server it may be that the web interface does not allow entering the Genre and Name separately. In which case the status check will need to be created via the [API](https://learn.microsoft.com/en-us/rest/api/azure/devops/policy/configurations/create). + +## Bitbucket Data Center + +The following errors are specific to Bitbucket Data Center integrations. + +### Clicking "Connect organization ``" with Bitbucket Data Center raises an error message in HCP Terraform + +HCP Terraform uses OAuth 1 to authenticate the user to Bitbucket Data Center. The first step in the authentication process is for HCP Terraform to call Bitbucket Data Center to obtain a request token. After the call completes, HCP Terraform redirects you to Bitbucket Data Center with the request token. + +An error occurs when HCP Terraform calls to Bitbucket Data Center to obtain the request token but the request is rejected. Some common reasons for the request to be rejected are: + +- The API endpoint is unreachable; this can happen if the address or port is incorrect or the domain name doesn't resolve. +- The certificate used on Bitbucket Data Center is rejected by the HCP Terraform HTTP client because the SSL verification fails. This is often the case with self-signed certificates or when the Terraform Enterprise instance is not configured to trust the signing chain of the Bitbucket Data Center SSL certificate. + +To fix this issue, do the following: + +- Verify that the instance running Terraform Enterprise can resolve the domain name and can reach Bitbucket Data Center. +- Verify that the HCP Terraform client accepts the HTTPS connection to Bitbucket Data Center. This can be done by performing a `curl` from the Terraform Enterprise instance to Bitbucket Data Center; it should not return any SSL errors. +- Verify that the Consumer Key, Consumer Name, and the Public Key are configured properly in Bitbucket Data Center. +- Verify that the HTTP URL and API URL in HCP Terraform are correct for your Bitbucket Data Center instance. This includes the proper scheme (HTTP vs HTTPS), as well as the port. + +### Creating a workspace from a repository hangs indefinitely, displaying a spinner on the confirm button + +If you were able to connect HCP Terraform to Bitbucket Data Center but cannot create workspaces, it often means HCP Terraform isn't able to automatically add webhook URLs for that repository. + +To fix this issue: + +- Make sure you haven't manually entered any webhook URLs for the affected repository or project. Although the Bitbucket Web Post Hooks Plugin documentation describes how to manually enter a hook URL, HCP Terraform handles this automatically. Manually entered URLs can interfere with HCP Terraform's operation. + + To check the hook URLs for a repository, go to the repository's settings, then go to the "Hooks" page (in the "Workflow" section) and click on the "Post-Receive WebHooks" link. + + Also note that some Bitbucket Data Center versions might allow you to set per-project or server-wide hook URLs in addition to per-repository hooks. These should all be empty; if you set a hook URL that might affect more than one repo when installing the plugin, go back and delete it. +- Make sure you aren't trying to connect too many workspaces to a single repository. Bitbucket Data Center's webhooks plugin can only attach five hooks to a given repo. You might need to create additional repositories if you need to make more than five workspaces from a single configuration repo. + +## Bitbucket Cloud + +### HCP Terraform fails to obtain repositories + +This typically happens when the HCP Terraform application in Bitbucket Cloud wasn't configured to have the full set of permissions. Go to the OAuth section of the Bitbucket settings, find your HCP Terraform OAuth consumer, click the edit link in the "..." menu, and ensure it has the required permissions enabled: + +| Permission type | Permission level | +| --------------- | ---------------- | +| Account | Write | +| Repositories | Admin | +| Pull requests | Write | +| Webhooks | Read and write | + +## GitHub + +### "Host key verification failed" error in `terraform init` when attempting to ingress Terraform modules via Git over SSH + +This is most common when running Terraform 0.10.3 or 0.10.4, which had a bug in handling SSH submodule ingress. Try upgrading affected HCP Terraform workspaces to the latest Terraform version or 0.10.8 (the latest in the 0.10 series). + +### HCP Terraform can't ingress Git submodules, with auth errors during init + +This usually happens when an SSH key isn't associated with the VCS provider's OAuth client. + +- Go to your organization's "VCS Provider" settings page and check your GitHub client. If it still says "You can add a private SSH key to this connection to be used for git clone operations" (instead of "A private SSH key has been added..."), you need to click the "add a private SSH key" link and add a key. +- Check the settings page for affected workspaces and ensure that "Include submodules on clone" is enabled. + +Note that the "SSH Key" section in a workspace's settings is only used for mid-run operations like cloning Terraform modules. It isn't used when cloning the linked repository before a run. + +## General + +The following errors may occur for all VCS providers except Bitbucket Data Center. + +### HCP Terraform returns 500 after authenticating with the VCS provider + +The Callback URL in the OAuth application configuration in the VCS provider probably wasn't updated in the last step of the instructions and still points to the default "/" path (or an example.com link) instead of the full callback url. + +The fix is to update the callback URL in your VCS provider's application settings. You can look up the real callback URL in HCP Terraform's settings. + +### Can't delete a workspace or module, resulting in 500 errors + +This often happens when the VCS connection has been somehow broken: it might have had permissions revoked, been reconfigured, or had the repository removed. Check for these possibilities and contact HashiCorp support for further assistance, including any information you collected in your support ticket. + +### `redirect_uri_mismatch` error on "Connect" + +The domain name for HCP Terraform's SaaS release changed on 02/22 at 9AM from `atlas.hashicorp.com` to `app.terraform.io`. If the OAuth client was originally configured on the old domain, using it for a new VCS connection can result in this error. + +The fix is to update the OAuth Callback URL in your VCS provider to use app.terraform.io instead of atlas.hashicorp.com. + +### Can't trigger workspace runs from VCS webhook + +A workspace with no runs will not accept new runs from a VCS webhook. You must queue at least one run manually. + +A workspace will not process a webhook if the workspace previously processed a webhook with the same commit SHA and created a run. To trigger a run, create a new commit. If a workspace receives a webhook with a previously processed commit, HCP Terraform adds a new event to the [VCS Events](/terraform/enterprise/vcs#viewing-events) page documenting the received webhook. + +### Changing the URL for a VCS provider + +On rare occasions, you might need HCP Terraform to change the URL it uses to reach your VCS provider. This usually only happens if you move your VCS server or the VCS vendor changes their supported API versions. + +HCP Terraform does not allow you to change the API URL for an existing VCS connection, but you can create a new VCS connection and update existing resources to use it. This is most efficient if you script the necessary updates using HCP Terraform's API. In brief: + +1. [Configure a new VCS connection](/terraform/enterprise/vcs) with the updated URL. +2. Obtain the [oauth-token IDs](/terraform/enterprise/api-docs/oauth-tokens) for the old and new OAuth clients. +3. [List all workspaces](/terraform/enterprise/api-docs/workspaces#list-workspaces) (dealing with pagination if necessary), and use a JSON filtering tool like `jq` to make a list of all workspace IDs whose `attributes.vcs-repo.oauth-token-id` matches the old VCS connection. +4. Iterate over the list of workspaces and [PATCH each one](/terraform/enterprise/api-docs/workspaces#update-a-workspace) to use the new `oauth-token-id`. +5. [List all registry modules](/terraform/registry/api-docs#list-modules) and use their `source` property to determine which ones came from the old VCS connection. +6. [Delete each affected module](/terraform/enterprise/api-docs/private-registry/modules#delete-a-module), then [create a new module](/terraform/enterprise/api-docs/private-registry/modules#publish-a-private-module-from-a-vcs) from the new connection's version of the relevant repo. +7. Delete the old VCS connection. + +### Reauthorizing VCS OAuth Providers + +If a VCS OAuth connection breaks, you can reauthorize an existing VCS provider while retaining any VCS connected resources, like workspaces. We recommend only using this feature to fix broken VCS connections. We also recommend reauthorizing using the same VCS account to avoid permission changes to your repositories. + +~> **Important:** Reauthorizing is not available when the [TFE Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/oauth_client) is managing the OAuth Client. Instead, you can update the [oauth_token](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/oauth_client#oauth_token) argument with a new token from your VCS Provider. + +To reauthorize a VCS connection, complete the following steps: + +1. Go to your organization's settings and click **Providers** under **Version Control**. +2. Click **Reauthorize** in the **OAuth Token ID** column. +3. Confirm the reauthorization. HCP Terraform redirects you to your VCS Provider where you can reauthorize the connection. + +## Certificate Errors on Terraform Enterprise + +When debugging failures of VCS connections due to certificate errors, running additional diagnostics using the OpenSSL command may provide more information about the failure. + +First, attach a bash session to the application container: + + docker exec -it ptfe_atlas sh -c "stty rows 50 && stty cols 150 && bash" + +Then run the `openssl s_client` command, using the certificate at `/tmp/cust-ca-certificates.crt` in the container: + + openssl s_client -showcerts -CAfile /tmp/cust-ca-certificates.crt -connect git-server-hostname:443 + +For example, a Gitlab server that uses a self-signed certificate might result in an error like `verify error:num=18:self signed certificate`, as shown in the output below: + + bash-4.3# openssl s_client -showcerts -CAfile /tmp/cust-ca-certificates.crt -connect gitlab.local:443 + CONNECTED(00000003) + depth=0 CN = gitlab.local + verify error:num=18:self signed certificate + verify return:1 + depth=0 CN = gitlab.local + verify return:1 + --- + Certificate chain + 0 s:/CN=gitlab.local + i:/CN=gitlab.local + -----BEGIN CERTIFICATE----- + MIIC/DCCAeSgAwIBAgIJAIhG2GWtcj7lMA0GCSqGSIb3DQEBCwUAMCAxHjAcBgNV + BAMMFWdpdGxhYi1sb2NhbC5oYXNoaS5jbzAeFw0xODA2MDQyMjAwMDhaFw0xOTA2 + MDQyMjAwMDhaMCAxHjAcBgNVBAMMFWdpdGxhYi1sb2NhbC5oYXNoaS5jbzCCASIw + DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMMgrpo3zsoy2BP/AoGIgrYwEMnj + PwSOFGNHbclmiVBCW9jvrZrtva8Qh+twU7CSQdkeSP34ZgLrRp1msmLvUuVMgPts + i7isrI5hug/IHLLOGO5xMvxOcrHknvySYJRmvYFriEBPNRPYJGJ9O1ZUVUYeNwW/ + l9eegBDpJrdsjGmFKCOzZEdUA3zu7PfNgf788uIi4UkVXZNa/OFHsZi63OYyfOc2 + Zm0/vRKOn17dewOOesHhw77yYbBH8OFsEiC10JCe5y3MD9yrhV1h9Z4niK8rHPXz + XEh3JfV+BBArodmDbvi4UtT+IGdDueUllXv7kbwqvQ67OFmmek0GZOY7ZvMCAwEA + AaM5MDcwIAYDVR0RBBkwF4IVZ2l0bGFiLWxvY2FsLmhhc2hpLmNvMBMGA1UdJQQM + MAoGCCsGAQUFBwMBMA0GCSqGSIb3DQEBCwUAA4IBAQCfkukNV/9vCA/8qoEbPt1M + mvf2FHyUD69p/Gq/04IhGty3sno4eVcwWEc5EvfNt8vv1FykFQ6zMJuWA0jL9x2s + LbC8yuRDnsAlukSBvyazCZ9pt3qseGOLskaVCeOqG3b+hJqikZihFUD95IvWNFQs + RpvGvnA/AH2Lqqeyk2ITtLYj1AcSB1hBSnG/0fdtao9zs0JQsrS59CD1lbbTPPRN + orbKtVTWF2JlJxl2watfCNTw6nTCPI+51CYd687T3MuRN7LsTgglzP4xazuNjbWB + QGAiQRd6aKj+xAJnqjzXt9wl6a493m8aNkyWrxZGHfIA1W70RtMqIC/554flZ4ia + -----END CERTIFICATE----- + --- + Server certificate + subject=/CN=gitlab.local + issuer=/CN=gitlab.local + --- + No client certificate CA names sent + Peer signing digest: SHA512 + Server Temp Key: ECDH, P-256, 256 bits + --- + SSL handshake has read 1443 bytes and written 433 bytes + --- + New, TLSv1/SSLv3, Cipher is ECDHE-RSA-AES256-GCM-SHA384 + Server public key is 2048 bit + Secure Renegotiation IS supported + Compression: NONE + Expansion: NONE + No ALPN negotiated + SSL-Session: + Protocol : TLSv1.2 + Cipher : ECDHE-RSA-AES256-GCM-SHA384 + Session-ID: AF5286FB7C7725D377B4A5F556DEB6DDC38B302153DDAE90C552ACB5DC4D86B8 + Session-ID-ctx: + Master-Key: DB75AEC12C6E7B62246C653C8CB8FC3B90DE86886D68CB09898A6A6F5D539007F7760BC25EC4563A893D34ABCFAAC28A + Key-Arg : None + PSK identity: None + PSK identity hint: None + SRP username: None + TLS session ticket lifetime hint: 300 (seconds) + TLS session ticket: + 0000 - 03 c1 35 c4 ff 6d 24 a8-6c 70 61 fb 2c dc 2e b8 ..5..m$.lpa.,... + 0010 - de 4c 6d b0 2c 13 8e b6-63 95 18 ee 4d 33 a6 dc .Lm.,...c...M3.. + 0020 - 0d 64 24 f0 8d 3f 9c aa-b8 a4 e2 4f d3 c3 4d 88 .d$..?.....O..M. + 0030 - 58 99 10 73 83 93 70 4a-2c 61 e7 2d 41 74 d3 e9 X..s..pJ,a.-At.. + 0040 - 83 8c 4a 7f ae 7b e8 56-5c 51 fc 6f fe e3 a0 ec ..J..{.V\Q.o.... + 0050 - 3c 2b 6b 13 fc a0 e5 15-a8 31 16 19 11 98 56 43 <+k......1....VC + 0060 - 16 86 c4 cd 53 e6 c3 61-e2 6c 1b 99 86 f5 a8 bd ....S..a.l...... + 0070 - 3c 49 c0 0a ce 81 a9 33-9b 95 2c e1 f4 6d 05 1e - + Best practices to structure your configuration and Terraform Enterprise + workspaces +source: terraform-docs-common +--- + +# Workspace Best Practices + +An HCP Terraform workspace manages a single state file and the lifecycle of its resources. It is the smallest collection of HCP Terraform-managed infrastructure. Any operation on a resource can potentially affect other resources managed in the same state file, so it is best to keep the potential blast radius of your operations small. To do so, manage resources in separate workspaces when possible, grouping together only necessary and logically-related resources. For example, even though your application may require both compute resources and a database, these resources can operate independently and should be in their own workspaces. +Scoping your configuration and planning your workspace strategy early in your adoption of HCP Terraform and Terraform Enterprise will simplify your operations and make them safer. + +## Name your Workspace + +We recommend using the following naming convention so you can identify and associate workspaces with specific components of your infrastructure: + +`---` + +- ``: The business unit or team that owns the workspace. +- ``: The name of the application or service that the workspace manages. +- ``: The layer of the infrastructure that the workspace manages (or example, network, compute, filestore). +- ``: The environment that the workspace manages (for example, prod, staging, QA, prod). + +If your application team does not have a `layer`, use `main` or `app` in its place to maintain consistency across the organization. + +## Group by volatility + +Volatility refers to the rate of change of the resources in a workspace. Infrastructure such as databases, VPCs, and subnets change much less frequently than infrastructure such as your web servers. By exposing your long-living infrastructure to unnecessary volatility, you introduce more opportunities for accidental changes. When planning your workspace organization, group resources by volatility. + +![An example of how workspaces can be split among Production, Staging, QA, and Dev. In this example, networking and security are grouped in one workspace, with compute, filestore, and SQL all having their own workspace. This is duplicated in each environment](/img/docs/workspace-net-infra-split.png) + +The above example groups together tightly-coupled resources like networking, security, and identity in a shared workspace. Compute, storage, and databases have separate workspaces, since they change at different frequencies. You may scale compute instances multiple times a day, but your database instances probably change far less frequently. By grouping these parts of your infrastructure into separate workspaces, you decouple unrelated resources and reduce the risk of unexpected changes. + +## Determine stateful vs stateless infrastructure + +Stateful resources are ones that you cannot delete and recreate because they persist data, such as databases and object storage. By managing stateful resources independently of stateless ones, such as separating databases from compute instances, you limit the blast radius of operations that cause the resource recreation and help protect against accidental data loss. + +Consider the workspace structure in the [Volatility section](#group-by-volatility). You could potentially manage filestore and database resources together, as they are both stateful resources. Your compute resources are stateless and should still have a separate workspace. + +## Separate privileges and responsibilities + +A best practice is to split up workspaces based on team responsibilities and required privileges. For example, consider an application that requires separate developer and production environments, each with special networking and application infrastructure. One approach is to create four different workspaces, two for the developer environment and two for production. Only the networking team has access to the networking workspaces. + +In this setup, only the networking team needs permissions to manage the resources in the networking workspaces, and others cannot manage those workspace resources. If a workspace's scope is too large, a user might need more permissions than appropriate in order to perform operations the workspace. + +![An example of how workspaces can be split among Production, Staging, QA, and Dev. In this example, networking and security are grouped in one workspace, with compute, filestore, and SQL all having their own workspace. This is duplicated in each environment](/img/docs/workspace-net-infra-combined.png) + +Splitting your workspaces by team also helps limit the responsibility per workspace and allows teams to maintain distinct areas of ownership. If you need to reference attributes of resources managed in other workspaces, you can share the outputs using the [tfe_outputs](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) data source. By limiting the scope of each workspace and sharing just the required outputs with others, you reduce the risk of leaking potentially sensitive information in a workspace's state. To share outputs from a workspace, you must explicitly enable remote state sharing in the workspace settings. + +## Avoid large Terraform plans and applies + +HCP Terraform and Terraform Enterprise execute workloads using agents. Every time an agent refreshes a workspace's state, it builds a [dependency graph](/terraform/internals/graph) of the resources to determine how to sequence operations in the workspace. As the number of resources your workspace manages grows, these graphs become larger and more complex. As these graphs grow, they require more worker RAM to build them. If your agent's performance degrades or workloads take longer to complete, we suggest exploring ways to split up the workspace to reduce the size of the dependency graph. + +## Determine workspace concurrency vs Terraform parallelism + +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. + +You can [increase the parallelism](/terraform/enterprise/workspaces/variables#parallelism) of Terraform, but this increases a run's CPU usage. We recommend that you instead break down large Terraform configurations into smaller ones with fewer resources when possible. Long-running Terraform workloads are an early sign of a bloated workspace scope. + +## Next steps + +This article introduces some considerations to keep in mind as your organization matures their workspace usage. Being deliberate about how you use these to organize your infrastructure will ensure smoother and safer operations. [HCP Terraform](/terraform/tutorials/cloud-get-started) provides a place to try these concepts hands-on, and you can [get started for free](https://app.terraform.io/public/signup/account). + +To learn more about HCP Terraform and Terraform Enterprise best practices, refer to [Project Best Practices](/terraform/enterprise/projects/best-practices). To learn best practices for writing Terraform configuration, refer to the [Terraform Style Guide](/terraform/language/style). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/browse.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/browse.mdx new file mode 100644 index 0000000000..3b7ef87d01 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/browse.mdx @@ -0,0 +1,72 @@ +--- +page_title: Browse workspaces +description: >- + Learn how to use the sorting and filtering interfaces in Terraform Enterprise + to create different views of the resource data that the app manages so that + you can track consumption across your organizations. +source: terraform-docs-common +--- + +# Browse workspaces + +This topic describes how to use browse, sort, and filter workspaces in the UI so that you can track consumption across your organizations. + +## Overview + +HCP Terraform and Terraform Enterprise include several interfaces for browsing, sorting, and filtering resource data so that you can effectively manage workspaces and projects. You can also use interfaces together, such as applying a tag filter and sorting by workspace name, to refine results. + + + +### Explorer view + +The explorer for workspace visibility surfaces a wider range of valuable information from across your workspaces. Refer to [Explorer for workspace visibility](/terraform/enterprise/workspaces/explorer) for additional information. + + + +## Requirements + +You must be a member of a team with the **Read** permissions enabled for Terraform runs to view workspaces associated with the run. Refer to the [permissions reference](/terraform/enterprise/users-teams-organizations/permissions) for additional information. + +If your organization contains many workspaces, you can use the filter tools at the top of the list to find the workspaces you are interested in. + +## Find a workspace + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select your organization. +2. Click **Workspaces** to view workspaces you have access to. +3. To view projects you have access to, click on either **Projects** in the sidebar menu or the drawer icon in the **Workspaces** bar. +4. If your organization contains several workspaces or projects, you can paginate through the workspace screen or project drawer to find the workspace you are looking for. +5. You can also use the search bar in the **Workspace** drawer to find a project by name + +## Filter workspaces + +You can use the following interfaces to sort and filter workspaces: + +- Click on a run status button to filter workspaces by one of the most common run statuses. You can filter by one of the following statuses: + + - Needs attention + - Errored + - Running + - On hold + - Applied + +- Choose one or more tag keys, values, or key-value pairs from the **Tags** drop-down to filter workspaces by tag. + +- Choose one or more run statuses from the **Status** drop-down to filter workspaces by run status. The **Status** drop-down lists all available run statuses, including the common statuses available in the run status button bar. + +- The tag filter shows a list of tags added to all workspaces, limited to the first 1,000 tags alphabetically. Choosing one or more will show only workspaces tagged with all of the chosen tags. + +- Choose a health assessment label form the **Health** drop-down to filter workspaces according to the latest health assessment results. You can filter according to the following labels: + + - Drifted + - Health error + - Check failed + +## Sort workspaces + +Click on a column header to sort workspaces by trait. Traits appear in either ascending or descending alphabetical order. You can sort according to the following traits: + +- Workspace name +- Run status +- Repository +- Latest change +- Tag diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/configurations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/configurations.mdx new file mode 100644 index 0000000000..f56346f09b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/configurations.mdx @@ -0,0 +1,73 @@ +--- +page_title: Manage Terraform configurations +description: >- + Workspaces organize infrastructure and state. Learn how to provide + configuration versions for a workspace and organize multiple environments. +source: terraform-docs-common +--- + +# Manage Terraform configurations + +[remote operations]: /terraform/enterprise/run/remote-operations + +[execution mode]: /terraform/enterprise/workspaces/settings#execution-mode + +[Terraform configuration]: /terraform/language + +Each HCP Terraform workspace is associated with a particular [Terraform configuration][], which is expected to change and evolve over time. + +Since every organization has its own preferred source code control practices, HCP Terraform does not provide integrated version management. Instead, it expects Terraform configurations to be managed in your existing version control system (VCS). + +In order to perform [remote Terraform runs][remote operations] for a given workspace, HCP Terraform needs to periodically receive new versions of its configuration. Usually, this can be handled automatically by connecting a workspace to a VCS repository. + +-> **Note:** If a workspace's [execution mode is set to local][execution mode], it doesn't require configuration versions, since HCP Terraform won't perform runs for that workspace. + +## Providing Configuration Versions + +There are two ways to provide configuration versions for a workspace: + +- **With a connected VCS repository.** HCP Terraform can automatically fetch content from supported VCS providers, and uses webhooks to get notified of code changes. This is the most convenient way to use HCP Terraform. See [The UI- and VCS-driven Run Workflow](/terraform/enterprise/run/ui) for more information. + + A VCS connection can be configured [when a workspace is created](/terraform/enterprise/workspaces/create), or later in its [version control settings](/terraform/enterprise/workspaces/settings/vcs). + + -> **Note:** When a workspace is connected to a VCS repository, directly uploaded configuration versions can only be used for [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans). This helps ensure your VCS remains the source of truth for all real infrastructure changes. + +- **With direct uploads.** You can use a variety of tools to directly upload configuration content to HCP Terraform: + + - **Terraform CLI:** With the [CLI integration](/terraform/cli/cloud) configured, the `terraform plan` and `terraform apply` commands will perform remote runs by uploading a configuration from a local working directory. See [The CLI-driven Run Workflow](/terraform/enterprise/run/cli) for more information. + - **API:** HCP Terraform's API can accept configurations as `.tar.gz` files, which can be uploaded by a CI system or other workflow tools. See [The API-driven Run Workflow](/terraform/enterprise/run/api) for more information. + + When configuration versions are provided via the CLI or API, HCP Terraform can't automatically react to code changes in the underlying VCS repository. + +## Code Organization and Repository Structure + +### Organizing Separate Configurations + +Most organizations either keep each Terraform configuration in a separate repository, or keep many Terraform configurations as separate directories in a single repository (often called a "monorepo"). + +HCP Terraform works well with either approach, but monorepos require some extra configuration: + +- Each workspace must [specify a Terraform working directory](/terraform/enterprise/workspaces/settings#terraform-working-directory), so HCP Terraform knows which configuration to use. +- If the repository includes any shared Terraform modules, you must add those directories to the [automatic run triggering setting](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering) for any workspace that uses those modules. + +-> **Note:** If your organization does not have a strong preference, we recommend using separate repositories for each configuration and using the private module registry to share modules. This allows for faster module development, since you don't have to update every configuration that consumes a module at the same time as the module itself. + +### Organizing Multiple Environments for a Configuration + +There are also a variety of ways to handle multiple environments. The most common approaches are: + +- All environments use the same main branch, and environment differences are handled with Terraform variables. To protect production environments, wait to apply runs until their changes are verified in staging. +- Different environments use different long-lived VCS branches. To protect production environments, merge changes to the production branch after they have been verified in staging. +- Different environments use completely separate configurations, and shared behaviors are handled with shared Terraform modules. To protect production environments, verify new module versions in staging before updating the version used in production. + +HCP Terraform works well with all of these approaches. If you used long-lived branches, be sure to specify which branch to use in each workspace's VCS connection settings. + +## Archiving Configuration Versions + +Once all runs using a particular configuration version are complete, HCP Terraform no longer needs the associated `.tar.gz` file and may discard it to save storage space. This process is handled differently depending on how the configuration version was created. + +- **Created with a connected VCS repository.** HCP Terraform will automatically archive VCS configuration versions once all runs are completed and they are no longer current for any workspace. HCP Terraform will re-fetch the configuration files from VCS as needed for new runs. + +- **Created with direct uploads via the API or CLI.** HCP Terraform does not archive CLI and API configuration versions automatically, because it cannot re-fetch the files for new runs. However, you can use the [Archive a Configuration Version](/terraform/enterprise/api-docs/configuration-versions#archive-a-configuration-version) endpoint to archive them manually. + +For Terraform Enterprise customers upgrading from a previous version, the functionality has a backfill capability that will clean up space for historical runs in batches. In each organization, Terraform Enterprise archives a batch of 100 configurations each time a run completes or a new configuration version is uploaded. This will gradually free up existing object storage space over time. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/create.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/create.mdx new file mode 100644 index 0000000000..e52c6468b2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/create.mdx @@ -0,0 +1,110 @@ +--- +page_title: Create workspaces in Terraform Enterprise +description: >- + Workspaces organize infrastructure and state into groups. Learn how to create + and configure Terraform Enterprise workspaces through the UI. +source: terraform-docs-common +--- + +# Create workspaces + +This topic describes how to create and manage workspaces in HCP Terraform and Terraform Enterprise UI. A workspace is a group of infrastructure resources managed by Terraform. Refer to [Workspaces overview](/terraform/enterprise/workspaces) for additional information. + +> **Hands-on:** Try the [Get Started - HCP Terraform](/terraform/tutorials/cloud-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. + +## Introduction + +Create new workspaces when you need to manage a new collection of infrastructure resources. You can use the following methods to create workspaces: + +- HCP Terraform UI: Refer to [Create a workspace](#create-a-workspace) for instructions. +- Workspaces API: Send a `POST`call to the `/organizations/:organization_name/workspaces` endpoint to create a workspace. Refer to the [API documentation](/terraform/enterprise/api-docs/workspaces#create-a-workspace) for instructions. +- Terraform Enterprise provider: Install the `tfe` provider and add the `tfe_workspace` resource to your configuration. Refer to the [`tfe` provider documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace) in the Terraform registry for instructions. +- No-code provisioning: Use a no-code module from the registry to create a new workspace and deploy the module's resources. Refer to [Provisioning No-Code Infrastructure](/terraform/enterprise/no-code-provisioning/provisioning) for instructions. + +Each workspace belongs to a project. Refer to [Manage projects](/terraform/enterprise/projects/manage) for additional information. + +## Requirements + +You must be a member of a team with one of the following permissions enabled to create and manage workspaces: + +- **Manage all projects** +- **Manage all workspaces** +- **Admin** permission group for a project. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Workspace naming + +We recommend using consistent and informative names for new workspaces. One common approach is combining the workspace's important attributes in a consistent order. Attributes can be any defining characteristic of a workspace, such as the component, the component’s run environment, and the region where the workspace is provisioning infrastructure. + +This strategy could produce the following example workspace names: + +- networking-prod-us-east +- networking-staging-us-east +- networking-prod-eu-central +- networking-staging-eu-central +- monitoring-prod-us-east +- monitoring-staging-us-east +- monitoring-prod-eu-central +- monitoring-staging-eu-central + +You can add additional attributes to your workspace names as needed. For example, you may add the infrastructure provider, datacenter, or line of business. + +We recommend using 90 characters or less for the name of your workspace. + +## Create a workspace + +[workdir]: /terraform/enterprise/workspaces/settings#terraform-working-directory + +[trigger]: /terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering + +[branch]: /terraform/enterprise/workspaces/settings/vcs#vcs-branch + +[submodules]: /terraform/enterprise/workspaces/settings/vcs#include-submodules-on-clone + +Complete the following steps to use the HCP Terraform or Terraform Enterprise UI to create a workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and choose your organization. +2. Click **New** and choose **Workspace** from the drop-down menu. +3. If you have multiple projects, HCP Terraform may prompt you to choose the project to create the workspace in. Only users on teams with permissions for the entire project or the specific workspace can access the workspace. Refer to [Manage projects](/terraform/enterprise/projects/manage) for additional information. +4. Choose a workflow type. +5. Complete the following steps if you are creating a workspace that follows the VCS workflow: + 1. Choose an existing version control provider from the list or configure a new system. You must enable the workspace project to connect to your provider. Refer to [Connecting VCS + Providers](/terraform/enterprise/vcs) for more details. + 2. If you choose the **GitHub App** provider, choose an organization and repository when prompted. The list only displays the first 100 repositories from your VCS provider. If your repository is missing from the list, enter the repository ID in the text field . + 3. Refer to the following topics for information about configuring workspaces settings in the **Advanced options** screen: + - [Terraform Working Directory][workdir] + - [Automatic Run Triggering][trigger] + - [VCS branch][branch] + - [Include submodules on clone][submodules] +6. Specify a name for the workspace. VCS workflow workspaces default to the name of the repository. The name must be unique within the organization and can include letters, numbers, hyphens, and underscores. Refer to [Workspace naming](#workspace-naming) for additional information. +7. Add an optional description for the workspace. The description appears at the top of the workspace in the HCP Terraform UI. +8. Click **Create workspace** to finish. + +For CLI or API-driven workflow, the system opens the new workspace overview. For version control workspaces, the **Configure Terraform variables** page appears. + +### Configure Terraform variables for VCS workflows + +After you create a new workspace from a version control repository, HCP Terraform scans its configuration files for [Terraform variables](/terraform/enterprise/workspaces/variables#terraform-variables) and displays variables without default values or variables that are undefined in an existing [global or project-scoped variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). Terraform cannot perform successful runs in the workspace until you set values for these variables. + +Choose one of the following actions: + +- To skip this step, click **Go to workspace overview**. You can [load these variables from files](/terraform/enterprise/workspaces/variables/managing-variables#loading-variables-from-files) or create and set values for them later from within the workspace. HCP Terraform does not automatically scan your configuration again; you can only add variables from within the workspace individually. +- To configure variables, enter a value for each variable on the page. You may want to leave a variable empty if you plan to provide it through another source, like an `auto.tfvars` file. Click **Save variables** to add these variables to the workspace. + +## Next steps + +If you have already configured all Terraform variables, we recommend [manually starting a run](/terraform/enterprise/run/ui#manually-starting-runs) to prepare VCS-driven workspaces. You may also want to do one or more of the following actions: + +- [Upload configuration versions](/terraform/enterprise/workspaces/configurations#providing-configuration-versions): If you chose the API or CLI-Driven workflow, you must upload configuration versions for the workspace. +- [Edit environment variables](/terraform/enterprise/workspaces/variables): Shell environment variables store credentials and customize Terraform's behavior. +- [Edit additional workspace settings](/terraform/enterprise/workspaces/settings): This includes notifications, permissions, and run triggers to start runs automatically. +- [Learn more about running Terraform in your workspace](/terraform/enterprise/run/remote-operations): This includes how Terraform processes runs within the workspace, run modes, run states, and other operations. +- [Create workspace tags](/terraform/enterprise/workspaces/tags): Add tags to your workspaces so that you can organize and track them. +- [Browse workspaces](/terraform/enterprise/workspaces/browse): Use the interfaces available in the UI to browse, sort, and filter workspaces so that you can track resource consumption. + +### VCS Connection + +If you connected a VCS repository to the workspace, HCP Terraform automatically registers a webhook with your VCS provider. A workspace with no runs will not accept new runs from a VCS webhook, so you must [manually start at least one run](/terraform/enterprise/run/ui#manually-starting-runs). + +After you manually start a run, HCP Terraform automatically queues a plan when new commits appear in the selected branch of the linked repository or someone opens a pull request on that branch. Refer to [Webhooks](/terraform/enterprise/vcs#webhooks) for more details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/aws-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/aws-configuration.mdx new file mode 100644 index 0000000000..3d84e52e56 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/aws-configuration.mdx @@ -0,0 +1,165 @@ +--- +page_title: Use dynamic credentials with the AWS provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the AWS Terraform + provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the AWS provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with AWS to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure AWS](#configure-aws):** Set up a trust configuration between AWS and HCP Terraform. Then, you must create AWS roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to AWS during each run. The AWS provider authentication is valid for the length of the plan or apply. + +## Configure AWS + +You must enable and configure an OIDC identity provider and accompanying role and trust policy on AWS. These instructions use the AWS console, but you can also use Terraform to configure AWS. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/aws). + +### Create an OIDC Identity Provider + +AWS documentation for setting this up through the AWS console or API can be found here: [Creating OpenID Connect (OIDC) identity providers - AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html). + +The `provider URL` should be set to the address of HCP Terraform (e.g., **without** a trailing slash), and the `audience` should be set to `aws.workload.identity` or the value of `TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE`, if configured. + +### Configure a Role and Trust Policy + +You must configure a role and corresponding trust policy. Amazon documentation on setting this up can be found here: [Creating a role for web identity or OpenID Connect Federation (console) - AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html). +The trust policy will be of the form: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Federated": "OIDC_PROVIDER_ARN" + }, + "Action": "sts:AssumeRoleWithWebIdentity", + "Condition": { + "StringEquals": { + "SITE_ADDRESS:aud": "AUDIENCE_VALUE", + "SITE_ADDRESS:sub": "organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:RUN_PHASE" + } + } + } + ] +} +``` + +with the capitalized values replaced with the following: + +- **OIDC_PROVIDER_ARN**: The ARN from the OIDC provider resource created in the previous step +- **SITE_ADDRESS**: The address of HCP Terraform with `https://` stripped, (e.g., `app.terraform.io`) +- **AUDIENCE_VALUE**: This should be set to `aws.workload.identity` unless a non-default audience has been specified in TFC +- **ORG_NAME**: The organization name this policy will apply to, such as `my-org-name` +- **PROJECT_NAME**: The project name that this policy will apply to, such as `my-project-name` +- **WORKSPACE_NAME**: The workspace name this policy will apply to, such as `my-workspace-name` +- **RUN_PHASE**: The run phase this policy will apply to, currently one of `plan` or `apply`. + +-> **Note:** if different permissions are desired for plan and apply, then two separate roles and trust policies must be created for each of these run phases to properly match them to the correct access level. +If the same permissions will be used regardless of run phase, then the condition can be modified like the below to use `StringLike` instead of `StringEquals` for the sub and include a `*` after `run_phase:` to perform a wildcard match: + +```json +{ + "Condition": { + "StringEquals": { + "SITE_ADDRESS:aud": "AUDIENCE_VALUE" + }, + "StringLike": { + "SITE_ADDRESS:sub": "organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:*" + } + } +} +``` + +!> **Warning**: you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations! + +A permissions policy needs to be added to the role which defines what operations within AWS the role is allowed to perform. As an example, the below policy allows for fetching a list of S3 buckets: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": "*" + } + ] +} +``` + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with AWS using dynamic credentials. You can set these as workspace variables, or if you’d like to share one AWS role across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AWS_PROVIDER_AUTH`
`TFC_AWS_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to AWS. | +| `TFC_AWS_RUN_ROLE_ARN`
`TFC_AWS_RUN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_AWS_RUN_ROLE_ARN` | The ARN of the role to assume in AWS. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_AWS_PLAN_ROLE_ARN` and `TFC_AWS_APPLY_ROLE_ARN` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/aws-configuration#optional-environment-variables) | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_AWS_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_AWS_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to `aws.workload.identity`. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_AWS_PLAN_ROLE_ARN`
`TFC_AWS_PLAN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_AWS_PLAN_ROLE_ARN` | The ARN of the role to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AWS_RUN_ROLE_ARN` if not provided. | +| `TFC_AWS_APPLY_ROLE_ARN`
`TFC_AWS_APPLY_ROLE_ARN[_TAG]`
`TFC_DEFAULT_AWS_APPLY_ROLE_ARN` | The ARN of the role to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AWS_RUN_ROLE_ARN` if not provided. | + +## Configure the AWS Provider + +Make sure that you’re passing a value for the `region` argument into the provider configuration block or setting the `AWS_REGION` variable in your workspace. + +Make sure that you’re not using any of the other arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation as these settings may interfere with dynamic provider credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_aws_dynamic_credentials" { + description = "Object containing AWS dynamic credentials configuration" + type = object({ + default = object({ + shared_config_file = string + }) + aliases = map(object({ + shared_config_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "aws" { + shared_config_files = [var.tfc_aws_dynamic_credentials.default.shared_config_file] +} + +provider "aws" { + alias = "ALIAS1" + shared_config_files = [var.tfc_aws_dynamic_credentials.aliases["ALIAS1"].shared_config_file] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/azure-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/azure-configuration.mdx new file mode 100644 index 0000000000..502cd60c8d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/azure-configuration.mdx @@ -0,0 +1,177 @@ +--- +page_title: Use dynamic credentials with the Azure provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the Azure Terraform + providers in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the Azure provider + +~> **Important:** Ensure you are using version **3.25.0** or later of the **AzureRM provider** and version **2.29.0** or later of the **Microsoft Entra ID provider** (previously Azure Active Directory) as required OIDC functionality was introduced in these provider versions. + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Azure to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the AzureRM or Microsoft Entra ID providers in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Azure](#configure-azure):** Set up a trust configuration between Azure and HCP Terraform. Then, you must create Azure roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to Azure during each run. The Azure provider authentication is valid for the length of the plan or apply. + +!> **Warning:** Dynamic credentials with the Azure providers do not work when your Terraform Enterprise instance uses a custom or self-signed certificate. This limitation is due to restrictions in Azure. + +## Configure Azure + +You must enable and configure an application and service principal with accompanying federated credentials and permissions on Azure. These instructions use the Azure portal, but you can also use Terraform to configure Azure. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/azure). + +### Create an Application and Service Principal + +Follow the steps mentioned in the AzureRM provider docs here: [Creating the Application and Service Principal](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#creating-the-application-and-service-principal). + +As mentioned in the documentation it will be important to make note of the `client_id` for the application as you will use this later for authentication. + +-> **Note:** you will want to skip the `“Configure Microsoft Entra ID Application to Trust a GitHub Repository”` section as this does not apply here. + +### Grant the Application Access to Manage Resources in Your Azure Subscription + +You must now give the created Application permission to modify resources within your Subscription. + +Follow the steps mentioned in the AzureRM provider docs here: [Granting the Application access to manage resources in your Azure Subscription](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#granting-the-application-access-to-manage-resources-in-your-azure-subscription). + +### Configure Microsoft Entra ID Application to Trust a Generic Issuer + +Finally, you must create federated identity credentials which validate the contents of the token sent to Azure from HCP Terraform. + +Follow the steps mentioned in the AzureRM provider docs here: [Configure Azure Microsoft Entra ID Application to Trust a Generic Issuer](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#configure-azure-active-directory-application-to-trust-a-generic-issuer). + +The following information should be specified: + +- **Federated credential scenario**: Must be set to `Other issuer`. +- **Issuer**: The address of HCP Terraform (e.g., ). + - **Important**: make sure this value starts with **https://** and does _not_ have a trailing slash. +- **Subject identifier**: The subject identifier from HCP Terraform that this credential will match. This will be in the form `organization:my-org-name:project:my-project-name:workspace:my-workspace-name:run_phase:plan` where the `run_phase` can be one of `plan` or `apply`. +- **Name**: A name for the federated credential, such as `tfc-plan-credential`. Note that this cannot be changed later. + +The following is optional, but may be desired: + +- **Audience**: Enter the audience value that will be set when requesting the identity token. This will be `api://AzureADTokenExchange` by default. This should be set to the value of `TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE` if this has been configured. + +-> **Note:** because the `Subject identifier` for federated credentials is a direct string match, two federated identity credentials need to be created for each workspace using dynamic credentials: one that matches `run_phase:plan` and one that matches `run_phase:apply`. + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with Azure using dynamic credentials. You can set these as workspace variables. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AZURE_PROVIDER_AUTH`
`TFC_AZURE_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to Azure. | +| `TFC_AZURE_RUN_CLIENT_ID`
`TFC_AZURE_RUN_CLIENT_ID[_TAG]`
`TFC_DEFAULT_AZURE_RUN_CLIENT_ID` | The client ID for the Service Principal / Application used when authenticating to Azure. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_AZURE_PLAN_CLIENT_ID` and `TFC_AZURE_APPLY_CLIENT_ID` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/azure-configuration#optional-environment-variables) | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_AZURE_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_AZURE_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to `api://AzureADTokenExchange`. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_AZURE_PLAN_CLIENT_ID`
`TFC_AZURE_PLAN_CLIENT_ID[_TAG]`
`TFC_DEFAULT_AZURE_PLAN_CLIENT_ID` | The client ID for the Service Principal / Application to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AZURE_RUN_CLIENT_ID` if not provided. | +| `TFC_AZURE_APPLY_CLIENT_ID`
`TFC_AZURE_APPLY_CLIENT_ID[_TAG]`
`TFC_DEFAULT_AZURE_APPLY_CLIENT_ID` | The client ID for the Service Principal / Application to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_AZURE_RUN_CLIENT_ID` if not provided. | + +## Configure the AzureRM or Microsoft Entra ID Provider + +Make sure that you’re passing values for the `subscription_id` and `tenant_id` arguments into the provider configuration block or setting the `ARM_SUBSCRIPTION_ID` and `ARM_TENANT_ID` variables in your workspace. + +Make sure that you’re _not_ setting values for `client_id`, `use_oidc`, or `oidc_token` in the provider or setting any of `ARM_CLIENT_ID`, `ARM_USE_OIDC`, `ARM_OIDC_TOKEN`. + +### Specifying Multiple Configurations + +~> **Important:** Ensure you are using version **3.60.0** or later of the **AzureRM provider** and version **2.43.0** or later of the **Microsoft Entra ID provider** as required functionality was introduced in these provider versions. + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Azure setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_azure_dynamic_credentials" { + description = "Object containing Azure dynamic credentials configuration" + type = object({ + default = object({ + client_id_file_path = string + oidc_token_file_path = string + }) + aliases = map(object({ + client_id_file_path = string + oidc_token_file_path = string + })) + }) +} +``` + +#### Example Usage + +##### AzureRM Provider + +```hcl +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + client_id_file_path = var.tfc_azure_dynamic_credentials.default.client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.default.oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + alias = "ALIAS1" + client_id_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` + +##### Microsoft Entra ID Provider (formerly Azure AD) + +```hcl +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + client_id_file_path = var.tfc_azure_dynamic_credentials.default.client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.default.oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + // use_oidc must be explicitly set to true when using multiple configurations. + use_oidc = true + alias = "ALIAS1" + client_id_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + oidc_token_file_path = var.tfc_azure_dynamic_credentials.aliases["ALIAS1"].oidc_token_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration.mdx new file mode 100644 index 0000000000..400f5e996f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration.mdx @@ -0,0 +1,174 @@ +--- +page_title: Use dynamic credentials with the GCP provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the GCP Terraform + provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the GCP provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with GCP to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure GCP](#configure-gcp):** Set up a trust configuration between GCP and HCP Terraform. Then, you must create GCP roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to GCP during each run. The GCP provider authentication is valid for the length of the plan or apply. + +!> **Warning:** Dynamic credentials with the GCP provider do not work if your Terraform Enterprise instance uses a custom or self-signed certificate. This limitation is due to restrictions in GCP. + +## Configure GCP + +You must enable and configure a workload identity pool and provider on GCP. These instructions use the GCP console, but you can also use Terraform to configure GCP. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/gcp). + +### Add a Workload Identity Pool and Provider + +Google documentation for setting this up can be found here: [Configuring workload identity federation with other identity providers](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers). + +Before starting to create the resources, you must enable the APIs mentioned at the start of the [Configure workload Identity federation](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#configure). + +#### Add a Workload Identity Pool + +The following information should be specified: + +- **Name**: Name for the pool, such as `my-tfc-pool`. The name is also used as the pool ID. You can't change the pool ID later. + +The following is optional, but may be desired: + +- **Pool ID**: The ID for the pool. This defaults to the name as mentioned above, but can be set to another value. +- **Description**: Text that describes the purpose of the pool. + +You will also want to ensure that the `Enabled Pool` option is set to be enabled before clicking next. + +#### Add a Workload Identity Provider + +You must add a workload identity provider to the pool. The following information should be specified: + +- **Provider type**: Must be `OpenID Connect (OIDC)`. +- **Provider name**: Name for the identity provider, such as `my-tfc-provider`. The name is also used as the provider ID. You can’t change the provider ID later. +- **Issuer (URL)**: The address of the TFC/E instance, such as + - **Important**: make sure this value starts with **https://** and does _not_ have a trailing slash. +- **Audiences**: This can be left as `Default audience` if you are planning on using the default audience HCP Terraform provides. + - **Important**: you must select the `Allowed audiences` toggle and set this to the value of `TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE`, if configured. +- **Provider attributes mapping**: At the minimum this must include `assertion.sub` for the `google.subject` entry. Other mappings can be added for other claims in the identity token to attributes by adding `attribute.[claim name]` on the Google side and `assertion.[claim name]` on the OIDC side of a new mapping. +- **Attribute Conditions**: Conditions to restrict which identity tokens can authenticate using the workload identity pool, such as `assertion.sub.startsWith("organization:my-org:project:my-project:workspace:my-workspace")` to restrict access to identity tokens from a specific workspace. See this page in Google documentation for more information on the expression language: [Attribute conditions](https://cloud.google.com/iam/docs/workload-identity-federation#conditions). + +!> **Warning**: you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations! + +The following is optional, but may be desired: + +- **Provider ID**: The ID for the provider. This defaults to the name as mentioned above, but can be set to another value. + +### Add a Service Account and Permissions + +You must next add a service account and properly configure the permissions. + +#### Create a Service Account + +Google documentation for setting this up can be found here: [Creating a service account for the external workload](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create_a_service_account_for_the_external_workload). + +The following information should be specified: + +- **Service account name**: Name for the service account, such as `tfc-service-account`. The name is also used as the pool ID. You can't change the pool ID later. + +The following is optional, but may be desired: + +- **Service account ID**: The ID for the service account. This defaults to the name as mentioned above, but can be set to another value. +- **Description**: Text that describes the purpose of the service account. + +#### Grant IAM Permissions + +The next step in the setup wizard will allow for granting IAM permissions for the service account. The role that is given to the service account will vary depending on your specific needs and project setup. This should in general be the most minimal set of permissions needed for the service account to properly function. + +#### Grant External Permissions + +Once the service account has been created and granted IAM permissions, you will need to grant access to the service account for the identity pool created above. Google documentation for setting this up can be found here: [Allow the external workload to impersonate the service account](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#allow_the_external_workload_to_impersonate_the_service_account). + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with GCP using dynamic credentials. You can set these as workspace variables, or if you’d like to share one GCP service account across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_GCP_PROVIDER_AUTH`
`TFC_GCP_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to use dynamic credentials to authenticate to GCP. | +| `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_RUN_SERVICE_ACCOUNT_EMAIL` | The service account email HCP Terraform will use when authenticating to GCP. | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL` and `TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration#optional-environment-variables) | + +You must also include information about the GCP Workload Identity Provider that HCP Terraform will use when authenticating to GCP. You can supply this information in two different ways: + +1. By providing one unified variable containing the canonical name of the workload identity provider. +2. By providing the project number, pool ID, and provider ID as separate variables. + +You should avoid setting both types of variables, but if you do, the unified version will take precedence. + +#### Unified Variable + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_GCP_WORKLOAD_PROVIDER_NAME`
`TFC_GCP_WORKLOAD_PROVIDER_NAME[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_PROVIDER_NAME` | The canonical name of the workload identity provider. This must be in the form mentioned for the `name` attribute [here](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/iam_workload_identity_pool_provider#attributes-reference) | Requires **v1.7.0** or later if self-managing agents. This will take precedence over `TFC_GCP_PROJECT_NUMBER`, `TFC_GCP_WORKLOAD_POOL_ID`, and `TFC_GCP_WORKLOAD_PROVIDER_ID` if set. | + +#### Separate Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `TFC_GCP_PROJECT_NUMBER`
`TFC_GCP_PROJECT_NUMBER[_TAG]`
`TFC_DEFAULT_GCP_PROJECT_NUMBER` | The project number where the pool and other resources live. | Requires **v1.7.0** or later if self-managing agents. This is _not_ the project ID and is a separate number. | +| `TFC_GCP_WORKLOAD_POOL_ID`
`TFC_GCP_WORKLOAD_POOL_ID[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_POOL_ID` | The workload pool ID. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_GCP_WORKLOAD_PROVIDER_ID`
`TFC_GCP_WORKLOAD_PROVIDER_ID[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_PROVIDER_ID` | The workload identity provider ID. | Requires **v1.7.0** or later if self-managing agents. | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_GCP_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to a string of the form mentioned [here](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#oidc_1) in the GCP docs with the leading **https:** stripped. | Requires **v1.7.0** or later if self-managing agents. This is one of the default `aud` formats that GCP accepts. | +| `TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_PLAN_SERVICE_ACCOUNT_EMAIL` | The service account email to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL` if not provided. | +| `TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL`
`TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL[_TAG]`
`TFC_DEFAULT_GCP_APPLY_SERVICE_ACCOUNT_EMAIL` | The service account email to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL` if not provided. | + +## Configure the GCP Provider + +Make sure that you’re passing values for the `project` and `region` arguments into the provider configuration block. + +Make sure that you’re not setting values for the `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` environment variables as these will conflict with the dynamic credentials authentication process. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_gcp_dynamic_credentials" { + description = "Object containing GCP dynamic credentials configuration" + type = object({ + default = object({ + credentials = string + }) + aliases = map(object({ + credentials = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "google" { + credentials = var.tfc_gcp_dynamic_credentials.default.credentials +} + +provider "google" { + alias = "ALIAS1" + credentials = var.tfc_gcp_dynamic_credentials.aliases["ALIAS1"].credentials +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration.mdx new file mode 100644 index 0000000000..2414f1b7af --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration.mdx @@ -0,0 +1,116 @@ +--- +page_title: Dynamic Credentials with the HCP Provider - Workspaces - Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the HCP provider in your + Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Dynamic Credentials with the HCP Provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.15.1](/terraform/cloud-docs/agents/changelog#1-15-1-05-01-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with HCP to authenticate with the HCP provider using [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) in your HCP Terraform runs. Configuring dynamic credentials for the HCP provider requires the following steps: + +1. **[Configure HCP](#configure-hcp):** Set up a trust configuration between HCP and HCP Terraform. Then, you must create a [service principal in HPC](https://developer.hashicorp.com/hcp/docs/hcp/admin/iam/service-principals) for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to HCP during each run. + +## Configure HCP + +You must enable and configure a workload identity pool and provider on HCP. These instructions use the HCP CLI, but you can also use Terraform to configure HCP. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/hcp). + +#### Create a Service Principal + +Create a service principal for HCP Terraform to assume during runs by running the following HCP command. Note the ID of the service principal you create because you will need it in the following steps. For all remaining steps, replace `HCP_PROJECT_ID` with the ID of the project that contains all the resources and workspaces that you want to manage with this service principal. If you wish to manage more than one project with dynamic credentials, it is recommended that you create multiple service principals, one for each project. + +```shell +hcp iam service-principals create hcp-terraform --project=HCP_PROJECT_ID +``` + +Grant your service principal the necessary permissions to manage your infrastructure during runs. + +```shell +hcp projects iam add-binding \ + --project=HCP_PROJECT_ID \ + --member=HCP_PRINCIPAL_ID \ + --role=roles/contributor +``` + +#### Add a Workload Identity Provider + +Next, create a workload identity provider that HCP uses to authenticate the HCP Terraform run. Make sure to replace `HCP_PROJECT_ID`, `ORG_NAME`, `PROJECT_NAME`, and `WORKSPACE_NAME` with their respective values before running the command. + +```shell +hcp iam workload-identity-providers create-oidc hcp-terraform-dynamic-credentials \ + --service-principal=iam/project/HCP_PROJECT_ID/service-principal/hcp-terraform \ + --issuer=https://app.terraform.io \ + --allowed-audience=hcp.workload.identity \ + --conditional-access='jwt_claims.sub matches `^organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:.*`' \ + --description="Allow HCP Terraform agents to act as the hcp-terraform service principal" +``` + +## Configure HCP Terraform + +Next, you need to set environment variables in your HCP Terraform workspace to configure HCP Terraform to authenticate with HCP using dynamic credentials. You can set these as workspace variables or use a variable set to share one HCP service principal across multiple workspaces. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HCP_PROVIDER_AUTH`
`TFC_HCP_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.15.1** or later if you use self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to use dynamic credentials to authenticate to HCP. | +| `TFC_HCP_RUN_PROVIDER_RESOURCE_NAME`
`TFC_HCP_RUN_PROVIDER_RESOURCE_NAME[_TAG]`
`TFC_DEFAULT_HCP_RUN_PROVIDER_RESOURCE_NAME` | The resource name of the workload identity provider that will be used to assume the service principal | Requires **v1.15.1** or later if you use self-managing agents. Optional if you provide `PLAN_PROVIDER_RESOURCE_NAME` and `APPLY_PROVIDER_RESOURCE_NAME`. [Learn more](#optional-environment-variables). | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HCP_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_HCP_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_HCP_WORKLOAD_IDENTITY_AUDIENCE` | HCP Terraform uses this as the `aud` claim for the identity token. Defaults to the provider resource name for the current run phase, which HCP Terraform derives from the values you provide for `RUN_PROVIDER_RESOURCE_NAME`, `PLAN_PROVIDER_RESOURCE_NAME`, and `APPLY_PROVIDER_RESOURCE_NAME`. | Requires **v1.15.1** or later if you use self-managing agents. This is one of the default `aud` formats that HCP accepts. | +| `TFC_HCP_PLAN_PROVIDER_RESOURCE_NAME`
`TFC_HCP_PLAN_PROVIDER_RESOURCE_NAME[_TAG]`
`TFC_DEFAULT_HCP_PLAN_PROVIDER_RESOURCE_NAME` | The resource name of the workload identity provider that will HCP Terraform will use to authenticate the agent during the plan phase of a run. | Requires **v1.15.1** or later if self-managing agents. Will fall back to the value of `RUN_PROVIDER_RESOURCE_NAME` if not provided. | +| `TFC_HCP_APPLY_PROVIDER_RESOURCE_NAME`
`TFC_HCP_APPLY_PROVIDER_RESOURCE_NAME[_TAG]`
`TFC_DEFAULT_HCP_APPLY_PROVIDER_RESOURCE_NAME` | The resource name of the workload identity provider that will HCP Terraform will use to authenticate the agent during the apply phase of a run. | Requires **v1.15.1** or later if self-managing agents. Will fall back to the value of `RUN_PROVIDER_RESOURCE_NAME` if not provided. | + +## Configure the HCP Provider + +Do not set the `HCP_CRED_FILE` environment variable when configuring the HCP provider, or `HCP_CRED_FILE` will conflict with the dynamic credentials authentication process. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.15.1](/terraform/cloud-docs/agents/changelog#1-15-1-05-01-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct HCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, refer to [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +Add the following variable to your Terraform configuration to set up additional dynamic credential configurations with the HCP provider. This variable lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_hcp_dynamic_credentials" { + description = "Object containing HCP dynamic credentials configuration" + type = object({ + default = object({ + credential_file = string + }) + aliases = map(object({ + credential_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "hcp" { + credential_file = var.tfc_hcp_dynamic_credentials.default.credential_file +} + +provider "hcp" { + alias = "ALIAS1" + credential_file = var.tfc_hcp_dynamic_credentials.aliases["ALIAS1"].credential_file +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration.mdx new file mode 100644 index 0000000000..984c8ce7a7 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration.mdx @@ -0,0 +1,102 @@ +--- +page_title: >- + HCP Vault Secrets-Backed Dynamic Credentials with the AWS Provider - + Workspaces - Terraform Enterprise +description: >- + Use OpenID Connect and HCP Vault Secrets to get short-term credentials for the + AWS Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# HCP Vault Secrets-Backed Dynamic Credentials with the AWS Provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with HCP to use [HCP Vault Secrets-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed) with the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure HCP Provider Credentials](#configure-hcp-provider-credentials)**: Set up a trust configuration between HCP Vault Secrets and HCP Terraform, create HCP roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure HCP Vault Secrets](#configure-hcp-vault-secrets-aws-secrets-engine)**: Set up your HCP project's AWS integration and dynamic secret. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use HCP Vault Secrets-backed dynamic credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with HCP Vault Secrets-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with AWS via HCP Vault Secrets-generated credentials during the plan and apply phase of each run. The AWS provider's authentication is only valid for the length of the plan or apply phase. + +## Configure HCP Provider Credentials + +You must first set up HCP dynamic provider credentials before you can use HCP Vault Secrets-backed dynamic credentials. This includes creating a service principal, configuring trust between HCP and HCP Terraform, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for HCP dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration). + +## Configure HCP Vault Secrets AWS Secrets Engine + +Follow the instructions in the HCP Vault Secrets documentation for [setting up the AWS integration in your HCP project](/hcp/docs/vault-secrets/dynamic-secrets/aws). + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with AWS using HCP Vault Secrets-backed dynamic credentials. These variables are in addition to those you previously set while configuring [HCP provider credentials](#configure-hcp-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +### Required Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_AWS_AUTH`
`TFC_HVS_BACKED_AWS_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.16.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with AWS. | +| `TFC_HVS_BACKED_AWS_RUN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_AWS_HCP_CONFIG`
`TFC_HVS_BACKED_AWS_HCP_CONFIG[_TAG]`
`TFC_DEFAULT_HVS_BACKED_AWS_HCP_CONFIG` | The name of the non-default HCP configuration for workspaces using [multiple HCP configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.16.0** or later if self-managing agents. Will fall back to using the default HCP Vault Secrets configuration if not provided. | +| `TFC_HVS_BACKED_AWS_PLAN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the plan phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | +| `TFC_HVS_BACKED_AWS_APPLY_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the apply phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +## Configure Terraform Providers + +The final step is to directly configure your AWS and HCP Vault Secrets providers. + +### Configure the AWS Provider + +Ensure you pass a value for the `region` argument in your AWS provider configuration block or set the `AWS_REGION` variable in your workspace. + +Ensure you are not using any of the arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation. Otherwise, these settings may interfere with dynamic provider credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct HCP Vault Secrets-backed AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_hvs_backed_aws_dynamic_credentials" { + description = "Object containing HCP Vault Secrets-backed AWS dynamic credentials configuration" + type = object({ + default = object({ + shared_credentials_file = string + }) + aliases = map(object({ + shared_credentials_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "aws" { + shared_credentials_files = [var.tfc_hvs_backed_aws_dynamic_credentials.default.shared_credentials_file] +} + +provider "aws" { + alias = "ALIAS1" + shared_credentials_files = [var.tfc_hvs_backed_aws_dynamic_credentials.aliases["ALIAS1"].shared_credentials_file] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration.mdx new file mode 100644 index 0000000000..725342406e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration.mdx @@ -0,0 +1,119 @@ +--- +page_title: >- + HCP Vault Secrets-Backed Dynamic Credentials with the GCP Provider - + Workspaces - Terraform Enterprise +description: >- + Use OpenID Connect and HCP Vault Secrets to get short-term credentials for the + GCP Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# HCP Vault Secrets-Backed Dynamic Credentials with the GCP Provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with HCP to use [HCP Vault Secrets-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed) with the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure HCP Provider Credentials](#configure-hcp-provider-credentials)**: Set up a trust configuration between HCP Vault Secrets and HCP Terraform, create HCP Vault Secrets roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure HCP Vault Secrets](#configure-hcp-vault-secrets-gcp-secrets-engine)**: Set up your HCP project's GCP integration and dynamic secret. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use HCP Vault Secrets-backed dynamic credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with HCP Vault Secrets-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with GCP via HCP Vault Secrets-generated credentials during the plan and apply phase of each run. The GCP provider's authentication is only valid for the length of the plan or apply phase. + +## Configure HCP Provider Credentials + +You must first set up HCP dynamic provider credentials before you can use HCP Vault Secrets-backed dynamic credentials. This includes creating a service principal, configuring trust between HCP and HCP Terraform, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for HCP dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration). + +## Configure HCP Vault Secrets GCP Secrets Engine + +Follow the instructions in the HCP Vault Secrets documentation for [setting up the GCP integration in your HCP project](/hcp/docs/vault-secrets/dynamic-secrets/gcp). + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with GCP using HCP Vault Secrets-backed dynamic credentials. These variables are in addition to those you previously set while configuring [HCP provider credentials](#configure-hcp-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +### Required Common Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_GCP_AUTH`
`TFC_HVS_BACKED_GCP_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.16.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with GCP. | +| `TFC_HVS_BACKED_GCP_RUN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +### Optional Common Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_HVS_BACKED_GCP_HCP_CONFIG`
`TFC_HVS_BACKED_GCP_HCP_CONFIG[_TAG]`
`TFC_DEFAULT_HVS_BACKED_GCP_HCP_CONFIG` | The name of the non-default HCP configuration for workspaces using [multiple HCP configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.16.0** or later if self-managing agents. Will fall back to using the default HCP Vault Secrets configuration if not provided. | +| `TFC_HVS_BACKED_GCP_PLAN_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the plan phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | +| `TFC_HVS_BACKED_GCP_APPLY_SECRET_RESOURCE_NAME` | The name of the HCP Vault Secrets dynamic secret resource to read for the apply phase. | Requires **v1.16.0** or later if self-managing agents. Must be present. | + +## Configure Terraform Providers + +The final step is to directly configure your GCP and HCP Vault Secrets providers. + +### Configure the GCP Provider + +Ensure you pass values for the `project` and `region` arguments into the provider configuration block. + +Ensure you are not setting values or environment variables for `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`. Otherwise, these values may interfere with dynamic provider credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct HCP Vault Secrets-backed GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_hvs_backed_gcp_dynamic_credentials" { + description = "Object containing HCP Vault Secrets-backed GCP dynamic credentials configuration" + type = object({ + default = object({ + credentials = string + access_token = string + }) + aliases = map(object({ + credentials = string + access_token = string + })) + }) +} +``` + +#### Example Usage + +##### Access Token + +```hcl +provider "google" { + access_token = var.tfc_hvs_backed_gcp_dynamic_credentials.default.access_token +} + +provider "google" { + alias = "ALIAS1" + access_token = var.tfc_hvs_backed_gcp_dynamic_credentials.aliases["ALIAS1"].access_token +} +``` + +##### Credentials + +```hcl +provider "google" { + credentials = var.tfc_hvs_backed_gcp_dynamic_credentials.default.credentials +} + +provider "google" { + alias = "ALIAS1" + credentials = var.tfc_hvs_backed_gcp_dynamic_credentials.aliases["ALIAS1"].credentials +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/index.mdx new file mode 100644 index 0000000000..a60b0e4b12 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/index.mdx @@ -0,0 +1,38 @@ +--- +page_title: HCP Vault Secrets-backed dynamic credentials overview +description: >- + HCP Vault Secrets-backed dynamic credentials improve security by leveraging + HCP Vault Secrets to generate temporary credentials for Terraform runs. + Configure HCP Vault Secrets-backed dynamic credentials for supported + providers. +source: terraform-docs-common +--- + +# HCP Vault Secrets-Backed Dynamic Credentials + +This topic provides an overview of how to use HCP Vault Secrets to generate temporary credentials for providers so that you can securely use them in HCP Terraform runs. + +## Introduction + +Configuring [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) with different cloud providers is suitable for most use cases, but you can use HCP Vault Secrets-backed dynamic credentials to centralize and consolidate cloud credential management. + +HCP Vault Secrets-backed dynamic credentials leverage HCP Vault Secrets' [dynamic secrets capability](/hcp/docs/vault-secrets/dynamic-secrets), which allows you to generate short-lived credentials for various providers. This means you can authenticate a HCP instance using workload identity tokens and use dynamic secret capabilities on that instance to generate dynamic credentials for the various providers. + +Refer to the [HCP Vault Secrets announcement](https://www.hashicorp.com/blog/hcp-vault-secrets-is-now-generally-available) to learn about the benefits of using HCP Vault Secrets to manage provider credentials. + +## Workflow + +Using HCP Vault Secrets-backed dynamic credentials in a workspace requires the following steps for each cloud platform: + +1. If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.16.0](/terraform/cloud-docs/agents/changelog#1-16-0-10-02-2024) or newer. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). +2. Set up dynamic provider credentials with the HCP provider: You must first [configure dynamic credentials with the HCP provider](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-configuration). +3. Configure the dynamic secrets integration: You must configure the desired Vault secrets integration in your HCP project, such as AWS or GCP. +4. Configure your HCP Terraform workspace: You must add specific environment variables to your workspace to tell HCP Terraform how to authenticate to other cloud providers during runs. Each cloud platform has its own set of environment variables that are necessary to configure dynamic credentials. +5. Complete the instructions for setting up HCP Vault Secrets-backed dynamic for [Amazon Web Services](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/aws-configuration) or [Google Cloud Platform](/terraform/enterprise/workspaces/dynamic-provider-credentials/hcp-vault-secrets-backed/gcp-configuration). + +### Access to metadata endpoints + +In order to verify signed JWTs, HCP must have network access to the following static OIDC metadata endpoints within HCP Terraform: + +- `/.well-known/openid-configuration`: Standard OIDC metadata. +- `/.well-known/jwks`: HCP Terraform public keys that cloud platforms use to verify the authenticity of tokens that claim to come from HCP Terraform. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/index.mdx new file mode 100644 index 0000000000..11a3902ea2 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/index.mdx @@ -0,0 +1,59 @@ +--- +page_title: Dynamic provider credentials in Terraform Enterprise +description: >- + Dynamic provider credentials generate temporary credentials for Terraform + Enterprise runs. Learn how dynamic credentials for Vault, AWS, Azure, + Kubernetes, and GCP can improve your security. +source: terraform-docs-common +--- + +# Dynamic provider credentials + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +Using static credentials in your workspaces to authenticate providers presents a security risk, even if you rotate your credentials regularly. Dynamic provider credentials improve your security posture by letting you provision new, temporary credentials for each run. + +You can configure dynamic credentials for each HCP Terraform workspace. This workflow eliminates the need to manually manage and rotate credentials across your organization. It also lets you use the cloud platform’s authentication and authorization tools to scope permissions based on metadata, such as a run’s phase, its workspace, or its organization. + +## How Dynamic Credentials Work + +You configure a trust relationship between your cloud platform and HCP Terraform. As part of that process, you can define rules that let HCP Terraform workspaces and runs access specific resources. Then, the following process occurs for each Terraform plan and apply: + +1. HCP Terraform generates a [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens). The token is compliant with OpenID Connect protocol (OIDC) standards and includes information about the organization, workspace, and run stage. +2. When a plan or apply begins, HCP Terraform sends the workload identity token to the cloud platform, along with any other information needed to authenticate. +3. The cloud platform uses HCP Terraform’s public signing key to verify the workload identity token. +4. If verification succeeds, the cloud platform returns a set of fresh temporary credentials for HCP Terraform to use. +5. HCP Terraform sets up these credentials within the run environment for the Terraform provider to use. +6. The Terraform plan or apply proceeds. +7. When the plan or apply completes, the run environment is torn down and the temporary credentials are discarded. + +## Configure Dynamic Credentials + +Using dynamic credentials in a workspace requires the following steps for each cloud platform: + +1. **Set up a Trust Relationship:** You must configure a relationship between HCP Terraform and the other cloud platform. The exact details of this process will be different depending on the cloud platform. +2. **Configure Cloud Platform Access:** You must configure roles and policies for the cloud platform to define the workspace’s access to infrastructure resources. +3. **Configure HCP Terraform Workspace**: You must add specific environment variables to your workspace to tell HCP Terraform how to authenticate to the other cloud platform during plans and applies. Each cloud platform has its own set of environment variables to configure dynamic credentials. + +The process for each step is different for each cloud platform. Refer to the cloud platform configuration instructions for full details. You can configure dynamic credentials for the following platforms: + +- [Vault](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration) +- [Amazon Web Services](/terraform/enterprise/workspaces/dynamic-provider-credentials/aws-configuration) +- [Google Cloud Platform](/terraform/enterprise/workspaces/dynamic-provider-credentials/gcp-configuration) +- [Azure](/terraform/enterprise/workspaces/dynamic-provider-credentials/azure-configuration) +- [Kubernetes](/terraform/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration) + +You can also use Vault to generate credentials for AWS, GCP, or Azure by setting up [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed), which take advantage of Vault's [secrets engines](/vault/docs/secrets) to generate temporary credentials. + +## Terraform Enterprise Specific Requirements + +### External Access to Metadata Endpoints + +In order to verify signed JWTs, cloud platforms must have network access to the following static OIDC metadata endpoints within TFE: + +1. `/.well-known/openid-configuration` - standard OIDC metadata. +2. `/.well-known/jwks` - TFE’s public key(s) that cloud platforms use to verify the authenticity of tokens that claim to come from TFE. + +### External Vault Policy + +If you are using an external Vault instance, you must ensure that your Vault instance has the correct policies setup as detailed in the [External Vault Requirements for Terraform Enterprise](/terraform/enterprise/requirements/data-storage/vault) documentation. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration.mdx new file mode 100644 index 0000000000..6cd1fbda1f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/kubernetes-configuration.mdx @@ -0,0 +1,171 @@ +--- +page_title: >- + Use dynamic credentials with the Kubernetes and Helm providers in Terraform + Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the Kubernetes and Helm + Terraform providers in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the Kubernetes and Helm providers + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.13.1](/terraform/cloud-docs/agents/changelog#1-13-1-10-25-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Kubernetes to use [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the Kubernetes and Helm providers in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Kubernetes](#configure-kubernetes):** Set up a trust configuration between Kubernetes and HCP Terraform. Next, create Kubernetes role bindings for your HCP Terraform identities. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use dynamic credentials. +3. **[Configure the Kubernetes or Helm provider](#configure-the-provider)**: Set the required attributes on the provider block. + +Once you complete the setup, HCP Terraform automatically authenticates to Kubernetes during each run. The Kubernetes and Helm providers' authentication is valid for the length of a plan or apply operation. + +## Configure Kubernetes + +You must enable and configure an OIDC identity provider in the Kubernetes API. This workflow changes based on the platform hosting your Kubernetes cluster. HCP Terraform only supports dynamic credentials with Kubernetes in AWS and GCP. + +### Configure an OIDC identity provider + +Refer to the AWS documentation for guidance on [setting up an EKS cluster for OIDC authentication](https://docs.aws.amazon.com/eks/latest/userguide/authenticate-oidc-identity-provider.html). You can also refer to our [example configuration](https://github.com/hashicorp-education/learn-terraform-dynamic-credentials/tree/main/eks/trust). + +Refer to the GCP documentation for guidance on [setting up a GKE cluster for OIDC authentication](https://cloud.google.com/kubernetes-engine/docs/how-to/oidc). You can also refer to our [example configuration](https://github.com/hashicorp-education/learn-terraform-dynamic-credentials/tree/main/gke/trust). + +When inputting an "issuer URL", use the address of HCP Terraform (`https://app.terraform.io` _without_ a trailing slash) or the URL of your Terraform Enterprise instance. The value of "client ID" is your audience in OIDC terminology, and it should match the value of the `TFC_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE` environment variable in your workspace. + +The OIDC identity resolves authentication to the Kubernetes API, but it first requires authorization to interact with that API. So, you must bind RBAC roles to the OIDC identity in Kubernetes. + +You can use both "User" and "Group" subjects in your role bindings. For OIDC identities coming from TFC, the "User" value is formatted like so: `organization::project::workspace::run_phase:`. + +You can extract the "Group" value from the token claim you configured in your cluster OIDC configuration. For details on the structure of the HCP Terraform token, refer to [Workload Identity](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens). + +Below, we show an example of a `RoleBinding` for the HCP Terraform OIDC identity. + +```hcl +resource "kubernetes_cluster_role_binding_v1" "oidc_role" { + metadata { + name = "odic-identity" + } + + role_ref { + api_group = "rbac.authorization.k8s.io" + kind = "ClusterRole" + name = var.rbac_group_cluster_role + } + + // Option A - Bind RBAC roles to groups + // + // Groups are extracted from the token claim designated by 'rbac_group_oidc_claim' + // + subject { + api_group = "rbac.authorization.k8s.io" + kind = "Group" + name = var.tfc_organization_name + } + + // Option B - Bind RBAC roles to user identities + // + // Users are extracted from the 'sub' token claim. + // Plan and apply phases get assigned different users identities. + // For HCP Terraform tokens, the format of the user id is always the one described bellow. + // + subject { + api_group = "rbac.authorization.k8s.io" + kind = "User" + name = "${var.tfc_hostname}#organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:plan" + } + + subject { + api_group = "rbac.authorization.k8s.io" + kind = "User" + name = "${var.tfc_hostname}#organization:${var.tfc_organization_name}:project:${var.tfc_project_name}:workspace:${var.tfc_workspace_name}:run_phase:apply" + } +} +``` + +If binding with "User" subjects, be aware that plan and apply phases are assigned different identities, each requiring specific bindings. Meaning you can tailor permissions for each Terraform operation. Planning operations usually require "read-only" permissions, while apply operations also require "write" access. + +!> **Warning**: Always check, at minimum, the audience and the organization's name to prevent unauthorized access from other HCP Terraform organizations. + +## Configure HCP Terraform + +You must set certain environment variables in your HCP Terraform workspace to configure HCP Terraform to authenticate with Kubernetes or Helm using dynamic credentials. You can set these as workspace variables, or if you’d like to share one Kubernetes role across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_KUBERNETES_PROVIDER_AUTH`
`TFC_KUBERNETES_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.14.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to Kubernetes. | +| `TFC_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_KUBERNETES_WORKLOAD_IDENTITY_AUDIENCE` | The audience name in your cluster's OIDC configuration, such as `kubernetes`. | Requires **v1.14.0** or later if self-managing agents. | + +## Configure the provider + +The Kubernetes and Helm providers share the same schema of configuration attributes for the provider block. The example below illustrates using the Kubernetes provider but the same configuration applies to the Helm provider. + +Make sure that you are not using any of the other arguments or methods listed in the [authentication](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#authentication) section of the provider documentation as these settings may interfere with dynamic provider credentials. The only allowed provider attributes are `host` and `cluster_ca_certificate`. + +### Single provider instance + +HCP Terraform automatically sets the `KUBE_TOKEN` environment variable and includes the workload identity token. + +The provider needs to be configured with the URL of the API endpoint using the `host` attribute (or `KUBE_HOST` environment variable). In most cases, the `cluster_ca_certificate` (or `KUBE_CLUSTER_CA_CERT_DATA` environment variable) is also required. + +#### Example Usage + +```hcl +provider "kubernetes" { + host = var.cluster-endpoint-url + cluster_ca_certificate = base64decode(var.cluster-endpoint-ca) +} +``` + +### Multiple aliases + +You can add additional variables to handle multiple distinct Kubernetes clusters, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_kubernetes_dynamic_credentials" { + description = "Object containing Kubernetes dynamic credentials configuration" + type = object({ + default = object({ + token_path = string + }) + aliases = map(object({ + token_path = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "kubernetes" { + alias = "ALIAS1" + host = var.alias1-endpoint-url + cluster_ca_certificate = base64decode(var.alias1-cluster-ca) + token = file(var.tfc_kubernetes_dynamic_credentials.aliases["ALIAS1"].token_path) +} + +provider "kubernetes" { + alias = "ALIAS2" + host = var.alias1-endpoint-url + cluster_ca_certificate = base64decode(var.alias1-cluster-ca) + token = file(var.tfc_kubernetes_dynamic_credentials.aliases["ALIAS2"].token_path) +} +``` + +The `tfc_kubernetes_dynamic_credentials` variable is also available to use for single provider configurations, instead of the `KUBE_TOKEN` environment variable. + +```hcl +provider "kubernetes" { + host = var.cluster-endpoint-url + cluster_ca_certificate = base64decode(var.cluster-endpoint-ca) + token = file(var.tfc_kubernetes_dynamic_credentials.default.token_path) +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/manual-generation.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/manual-generation.mdx new file mode 100644 index 0000000000..ab6be885fb --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/manual-generation.mdx @@ -0,0 +1,42 @@ +--- +page_title: Manually generate workload identity tokens in Terraform Enterprise +description: >- + Learn how to generate workload identity tokens to allow Terraform runs to + safely authenticate with custom workflows and providers that do not natively + support dynamic credentials. +source: terraform-docs-common +--- + +# Manually generate workload identity tokens + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +If required for custom auth workflows or to perform auth with providers that are not natively supported by dynamic credentials, you can request that HCP Terraform inject a [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens) into the run environment for usage in agent hooks. + +## Configure HCP Terraform + +### Required Environment Variables + +You’ll need to set the following environment variable in your HCP Terraform workspace in order to have HCP Terraform inject a workload identity token into the run environment. You can set this as a workspace variable, or if you’d like to inject tokens with the same audience value across multiple workspaces, you can use a variable set. + +| Variable | Value | Notes | +| -------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TFC_WORKLOAD_IDENTITY_AUDIENCE` | The desired value for the token’s audience. | Requires **v1.7.0** or later if self-managing agents. Must be present and set or HCP Terraform will not inject a workload identity token into the run environment. | + +### Generating Multiple Tokens + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can generate multiple tokens if you want distinct audience values for different consumers of your workload identity tokens. For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +You can generate multiple tokens by specifying additional variables in the following format: `TFC_WORKLOAD_IDENTITY_AUDIENCE_[YOUR_TAG_HERE]`. + +Your tag can only contain letters, numbers, and underscores and can not use reserved keywords. The following keywords are reserved: `TYPE`. + +Each additional audience variable you specify generates an additional workload identity token that HCP Terraform stores in variables with the format: `TFC_WORKLOAD_IDENTITY_TOKEN_[YOUR_TAG_HERE]`. + +## Configure Agent Hooks + +After you've set the `TFC_WORKLOAD_IDENTITY_AUDIENCE` variable, each plan and apply will have a `TFC_WORKLOAD_IDENTITY_TOKEN` variable available in the run environment, which contains a [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens). + +You can use this environment variable in custom agent hooks to enable custom auth workflows or to perform auth with providers which are not natively supported by dynamic credentials. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations.mdx new file mode 100644 index 0000000000..24a076a110 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations.mdx @@ -0,0 +1,94 @@ +--- +page_title: Specify multiple dynamic credential configurations in Terraform Enterprise +description: >- + Specify multiple dynamic provider credential configurations for the same + workspace to create aliases for different provider configurations. +source: terraform-docs-common +--- + +# Specify multiple dynamic credential configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can create multiple dynamic credential configurations of the same provider in a workspace. + +Each configuration generates a distinct [workload identity token](/terraform/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens), allowing you to create [aliases for different provider configurations](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can specify unique audience values per configuration, and [manually generate multiple tokens](/terraform/enterprise/workspaces/dynamic-provider-credentials/manual-generation). + +Specifying multiple dynamic credential configurations in HCP Terraform builds on the existing method of providing each provider's environment variables to a workspace. The process requires mapping well-known authentication [input variables](/terraform/language/values/variables) to the correct providers. + +## Configure HCP Terraform + +You can specify additional dynamic credentials configurations by defining and appending a “tag” to the end of your existing required environment variables: `[DYNAMIC_CREDENTIALS_VAR_NAME]_[YOUR_TAG]`. + +Your tag can only contain letters, numbers, and underscores and can not use reserved keywords. The following keywords are reserved: `TYPE`. + +### Example + +Using [Vault's dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration) setup as an example, we can create additional configurations by setting new tagged variables that match Vault's [required environment variables](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration#required-environment-variables). So, if you want to add a configuration with the tag `ALIAS1`, you must set environment variables for `TFC_VAULT_PROVIDER_AUTH_ALIAS1`, `TFC_VAULT_ADDR_ALIAS1`, and `TFC_VAULT_RUN_ROLE_ALIAS1`. + +### Default Values for Multiple Configurations + +Each environment variable has a corresponding default variable which you can use to share values across multiple configurations. In this way, you can set values common to multiple configurations a single time, rather than repeating them for each configuration. If you explicitly set the corresponding environment variable in addition to the default variable, the explicit value is given precedence. + +#### Example + +In the [example above](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations#example), if each of your Vault configurations used the same underlying Vault instance, you could define the Vault address a single time using the `TFC_DEFAULT_VAULT_ADDR` variable, and omit `TFC_VAULT_ADDR` and `TFC_VAULT_ADDR_ALIAS1`. If you add a third Vault configuration for a different Vault instance with the tag `ALIAS2`, you could set the variable `TFC_VAULT_ADDR_ALIAS2` to override the Vault address specifically for the `ALIAS2` configuration. + +## Configure Terraform Code + +Each supported provider has input variables you must declare in your Terraform code to use dynamic credentials with that provider. Each dynamic provider's documentation page lists the required variables for that provider. HCP Terraform provides values for these variables during runs, which you can use to authenticate HCP Terraform with providers using dynamic credentials. + +Use the input variable values that HCP Terraform provides to map configuration values to the correct provider blocks. Authentication information for the default provider exists in a variable's top-level `default` object, while each additional configuration exists under a variable's `aliases` map. HCP Terraform generates the keys of the `aliases` map based on the tag you define in your HCP Terraform configuration. + +~> **Important:** If you add additional configurations to a workspace, you need to manually map authentication information for all providers _including_ the default provider. + +### Example + +Continuing from the [example above](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations#example), after setting the required environment variables for your provider, [add the following code to your Terraform configuration](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration#required-terraform-variable). This lets HCP Terraform supply variable values that you can use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_dynamic_credentials" { + description = "Object containing Vault dynamic credentials configuration" + type = object({ + default = object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + }) + aliases = map(object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + })) + }) +} +``` + +Use the above object to map authentication information to the correct provider block. For this example, index into the `aliases` map with your alias's tag (`ALIAS1`) and the `default` provider object. + +```hcl +provider "vault" { + // Set this to true as HCP Terraform manages the token lifecycle + skip_child_token = true + address = var.tfc_vault_dynamic_credentials.default.address + namespace = var.tfc_vault_dynamic_credentials.default.namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.default.token_filename + } +} + +provider "vault" { + // Set this to true as HCP Terraform manages the token lifecycle + skip_child_token = true + alias = "ALIAS1" + address = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].address + namespace = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].token_filename + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration.mdx new file mode 100644 index 0000000000..31bcda6cda --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration.mdx @@ -0,0 +1,135 @@ +--- +page_title: >- + Use Vault-backed dynamic credentials with the AWS provider in Terraform + Enterprise +description: >- + Use OpenID Connect and Vault to get short-term credentials for the AWS + Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials with the AWS provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed) with the AWS provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure the Vault AWS Secrets Engine](#configure-vault-aws-secrets-engine)**: Set up the AWS secrets engine in your Vault instance. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with AWS via Vault-generated credentials during the plan and apply phase of each run. The AWS provider's authentication is only valid for the length of the plan or apply phase. + +## Configure Vault Dynamic Provider Credentials + +You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for Vault dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). + +# Configure Vault AWS Secrets Engine + +Follow the instructions in the Vault documentation for [setting up the AWS secrets engine in your Vault instance](/vault/docs/secrets/aws). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/aws). + +~> **Important**: carefully consider the limitations and differences between each supported credential type in the AWS secrets engine. These limitations carry over to HCP Terraform’s usage of these credentials for authenticating the AWS provider. + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with AWS using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Common Environment Variables + +The below variables apply to all AWS auth types. + +#### Required Common Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TFC_VAULT_BACKED_AWS_AUTH`
`TFC_VAULT_BACKED_AWS_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with AWS. | +| `TFC_VAULT_BACKED_AWS_AUTH_TYPE`
`TFC_VAULT_BACKED_AWS_AUTH_TYPE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_AUTH_TYPE` | Specifies the type of authentication to perform with AWS. Must be one of the following: `iam_user`, `assumed_role`, or `federation_token`. | Requires **v1.8.0** or later if self-managing agents. | +| `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_RUN_VAULT_ROLE` | The role to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE` and `TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE` are both provided. These variables are described [below](#optional-common-environment-variables). | + +#### Optional Common Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `TFC_VAULT_BACKED_AWS_MOUNT_PATH`
`TFC_VAULT_BACKED_AWS_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_MOUNT_PATH` | The mount path of the AWS secrets engine in Vault. | Requires **v1.8.0** or later if self-managing agents. Defaults to `aws`. | +| `TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_PLAN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_PLAN_VAULT_ROLE` | The Vault role to use the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE`
`TFC_VAULT_BACKED_AWS_APPLY_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_APPLY_VAULT_ROLE` | The Vault role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AWS_SLEEP_SECONDS`
`TFC_VAULT_BACKED_AWS_SLEEP_SECONDS[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_SLEEP_SECONDS` | The amount of time to wait, in seconds, after obtaining temporary credentials from Vault. e.g., `30` for 30 seconds. Must be 1500 seconds (25 minutes) or less. | Requires **v1.12.0** or later if self-managing agents. Can be used to mitigate eventual consistency issues in AWS when using the `iam_user` auth type. | +| `TFC_VAULT_BACKED_AWS_VAULT_CONFIG`
`TFC_VAULT_BACKED_AWS_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_VAULT_CONFIG` | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided. | + +### Assumed Role Specific Environment Variables + +These environment variables are only valid if the `TFC_VAULT_BACKED_AWS_AUTH_TYPE` is `assumed_role`. + +#### Required Assumed Role Specific Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_RUN_ROLE_ARN` | The ARN of the role to assume in AWS. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN` and `TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN` are both provided. These variables are described [below](#optional-assume-role-specific-environment-variables). | + +#### Optional Assumed Role Specific Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_PLAN_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_PLAN_ROLE_ARN` | The ARN of the role to use for the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN` if not provided. | +| `TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN`
`TFC_VAULT_BACKED_AWS_APPLY_ROLE_ARN[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AWS_APPLY_ROLE_ARN` | The ARN of the role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AWS_RUN_ROLE_ARN` if not provided. | + +## Configure Terraform Providers + +The final step is to directly configure your AWS and Vault providers. + +### Configure the AWS Provider + +Ensure you pass a value for the `region` argument in your AWS provider configuration block or set the `AWS_REGION` variable in your workspace. + +Ensure you are not using any of the arguments or methods mentioned in the [authentication and configuration](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration) section of the provider documentation. Otherwise, these settings may interfere with dynamic provider credentials. + +### Configure the Vault Provider + +If you were previously using the Vault provider to authenticate the AWS provider, remove any existing usage of the AWS secrets engine from your Terraform Code. +This includes the [`vault_aws_access_credentials`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/aws_access_credentials) data source and any instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) you previously used to generate AWS credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Vault-backed AWS setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_backed_aws_dynamic_credentials" { + description = "Object containing Vault-backed AWS dynamic credentials configuration" + type = object({ + default = object({ + shared_credentials_file = string + }) + aliases = map(object({ + shared_credentials_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "aws" { + shared_credentials_files = [var.tfc_vault_backed_aws_dynamic_credentials.default.shared_credentials_file] +} + +provider "aws" { + alias = "ALIAS1" + shared_credentials_files = [var.tfc_vault_backed_aws_dynamic_credentials.aliases["ALIAS1"].shared_credentials_file] +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration.mdx new file mode 100644 index 0000000000..138e30f69b --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration.mdx @@ -0,0 +1,152 @@ +--- +page_title: >- + Use Vault-backed dynamic credentials with the Azure provider in Terraform + Enterprise +description: >- + Use OpenID Connect and Vault to get short-term credentials for the Azure + Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials with the Azure provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed) with the Azure provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure the Vault Azure Secrets Engine](#configure-vault-azure-secrets-engine)**: Set up the Azure secrets engine in your Vault instance. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed Dynamic Credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with Azure via Vault-generated credentials during the plan and apply phase of each run. The Azure provider's authentication is only valid for the length of the plan or apply phase. + +## Configure Vault Dynamic Provider Credentials + +You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for Vault dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). + +# Configure Vault Azure Secrets Engine + +Follow the instructions in the Vault documentation for [setting up the Azure secrets engine in your Vault instance](/vault/docs/secrets/azure). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/azure). + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with Azure using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AZURE_AUTH`
`TFC_VAULT_BACKED_AZURE_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with Azure. | +| `TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE`
`TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_RUN_VAULT_ROLE` | The role to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE` and `TFC_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE` are both provided. These variables are described [below](#optional-environment-variables). | + +### Optional Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_AZURE_MOUNT_PATH`
`TFC_VAULT_BACKED_AZURE_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_MOUNT_PATH` | The mount path of the Azure secrets engine in Vault. | Requires **v1.8.0** or later if self-managing agents. Defaults to `azure`. | +| `TFC_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE`
`TFC_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_PLAN_VAULT_ROLE` | The Vault role to use the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE`
`TFC_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_APPLY_VAULT_ROLE` | The Vault role to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_AZURE_RUN_VAULT_ROLE` if not provided. | +| `TFC_VAULT_BACKED_AZURE_SLEEP_SECONDS`
`TFC_VAULT_BACKED_AZURE_SLEEP_SECONDS[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_SLEEP_SECONDS` | The amount of time to wait, in seconds, after obtaining temporary credentials from Vault. e.g., `30` for 30 seconds. Must be 1500 seconds (25 minutes) or less. | Requires **v1.12.0** or later if self-managing agents. Can be used to mitigate eventual consistency issues in Azure. | +| `TFC_VAULT_BACKED_AZURE_VAULT_CONFIG`
`TFC_VAULT_BACKED_AZURE_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_AZURE_VAULT_CONFIG` | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided. | + +## Configure Terraform Providers + +The final step is to directly configure your Azure and Vault providers. + +### Configure the AzureRM or Microsoft Entra ID + +Ensure you pass a value for the `subscription_id` and `tenant_id` arguments in your provider configuration block or set the `ARM_SUBSCRIPTION_ID` and `ARM_TENANT_ID` variables in your workspace. + +Do not set values for `client_id`, `use_oidc`, or `oidc_token` in your provider configuration block. Additionally, do not set variable values for `ARM_CLIENT_ID`, `ARM_USE_OIDC`, or `ARM_OIDC_TOKEN`. + +### Configure the Vault Provider + +If you were previously using the Vault provider to authenticate the Azure provider, remove any existing usage of the Azure secrets engine from your Terraform Code. +This includes the [`vault_azure_access_credentials`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/azure_access_credentials) data source and any instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) you previously used to generate Azure credentials. + +### Specifying Multiple Configurations + +~> **Important:** Ensure you are using version **3.60.0** or later of the **AzureRM provider** and version **2.43.0** or later of the **Microsoft Entra ID provider** (previously Azure Active Directory) as required functionality was introduced in these provider versions. + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Vault-backed Azure setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_backed_azure_dynamic_credentials" { + description = "Object containing Vault-backed Azure dynamic credentials configuration" + type = object({ + default = object({ + client_id_file_path = string + client_secret_file_path = string + }) + aliases = map(object({ + client_id_file_path = string + client_secret_file_path = string + })) + }) +} +``` + +#### Example Usage + +##### AzureRM Provider + +```hcl +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azurerm" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + alias = "ALIAS1" + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` + +##### Microsoft Entra ID Provider (previously AzureAD) + +```hcl +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.default.client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-0000-0000-0000-000000000000" +} + +provider "azuread" { + features {} + // use_cli should be set to false to yield more accurate error messages on auth failure. + use_cli = false + alias = "ALIAS1" + client_id_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_id_file_path + client_secret_file_path = var.tfc_vault_backed_azure_dynamic_credentials.aliases["ALIAS1"].client_secret_file_path + subscription_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "20000000-0000-0000-0000-000000000000" +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration.mdx new file mode 100644 index 0000000000..752c2887d9 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration.mdx @@ -0,0 +1,167 @@ +--- +page_title: >- + Use Vault-backed dynamic credentials with the GCP provider in Terraform + Enterprise +description: >- + Use OpenID Connect and Vault to get short-term credentials for the GCP + Terraform provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials with the GCP provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to use [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed) with the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault Dynamic Provider Credentials](#configure-vault-dynamic-provider-credentials)**: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces. +2. **[Configure the Vault GCP Secrets Engine](#configure-vault-gcp-secrets-engine)**: Set up the GCP secrets engine in your Vault instance. +3. **[Configure HCP Terraform](#configure-hcp-terraform)**: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials. +4. **[Configure Terraform Providers](#configure-terraform-providers)**: Configure your Terraform providers to work with Vault-backed dynamic credentials. + +Once you complete this setup, HCP Terraform automatically authenticates with GCP via Vault-generated credentials during the plan and apply phase of each run. The GCP provider's authentication is only valid for the length of the plan or apply phase. + +## Configure Vault Dynamic Provider Credentials + +You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace. + +[See the setup instructions for Vault dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). + +# Configure Vault GCP Secrets Engine + +Follow the instructions in the Vault documentation for [setting up the GCP secrets engine in your Vault instance](/vault/docs/secrets/gcp). You can also do this configuration through Terraform. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault-backed/gcp). + +~> **Important**: carefully consider the limitations and differences between each supported credential type in the GCP secrets engine. These limitations carry over to HCP Terraform’s usage of these credentials for authenticating the GCP provider. + +## Configure HCP Terraform + +Next, you need to set certain environment variables in your HCP Terraform workspace to authenticate HCP Terraform with GCP using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring [Vault dynamic provider credentials](#configure-vault-dynamic-provider-credentials). You can add these as workspace variables or as a [variable set](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Common Environment Variables + +The below variables apply to all GCP auth types. + +#### Required Common Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_AUTH`
`TFC_VAULT_BACKED_GCP_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.8.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate with GCP. | +| `TFC_VAULT_BACKED_GCP_AUTH_TYPE`
`TFC_VAULT_BACKED_GCP_AUTH_TYPE[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_AUTH_TYPE` | Specifies the type of authentication to perform with GCP. Must be one of the following: `roleset/access_token`, `roleset/service_account_key`, `static_account/access_token`, or `static_account/service_account_key`. | Requires **v1.8.0** or later if self-managing agents. | + +#### Optional Common Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_MOUNT_PATH`
`TFC_VAULT_BACKED_GCP_MOUNT_PATH[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_MOUNT_PATH` | The mount path of the GCP secrets engine in Vault. | Requires **v1.8.0** or later if self-managing agents. Defaults to `gcp`. | +| `TFC_VAULT_BACKED_GCP_VAULT_CONFIG`
`TFC_VAULT_BACKED_GCP_VAULT_CONFIG[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_VAULT_CONFIG` | The name of the non-default Vault configuration for workspaces using [multiple Vault configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). | Requires **v1.12.0** or later if self-managing agents. Will fall back to using the default Vault configuration if not provided. | + +### Roleset Specific Environment Variables + +These environment variables are only valid if the `TFC_VAULT_BACKED_GCP_AUTH_TYPE` is `roleset/access_token` or `roleset/service_account_key`. + +#### Required Roleset Specific Environment Variables + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET`
`TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` | The roleset to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET` and `TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET` are both provided. These variables are described [below](#optional-roleset-specific-environment-variables). | + +#### Optional Roleset Specific Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET`
`TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET` | The roleset to use for the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` if not provided. | +| `TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET`
`TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET` | The roleset to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` if not provided. | + +### Static Account Specific Environment Variables + +These environment variables are only valid if the `TFC_VAULT_BACKED_GCP_AUTH_TYPE` is `static_account/access_token` or `static_account/service_account_key`. + +#### Required Static Account Specific Environment Variables + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT`
`TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT` | The static account to use in Vault. | Requires **v1.8.0** or later if self-managing agents. Optional if `TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT` and `TFC_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT` are both provided. These variables are described [below](#optional-static-account-specific-environment-variables). | + +#### Optional Static Account Specific Environment Variables + +You may need to set these variables, depending on your use case. + +| Variable | Value | Notes | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT`
`TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT` | The static account to use for the plan phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT` if not provided. | +| `TFC_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT`
`TFC_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT[_TAG]`
`TFC_DEFAULT_VAULT_BACKED_GCP_APPLY_VAULT_STATIC_ACCOUNT` | The static account to use for the apply phase of a run. | Requires **v1.8.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_STATIC_ACCOUNT` if not provided. | + +## Configure Terraform Providers + +The final step is to directly configure your GCP and Vault providers. + +### Configure the GCP Provider + +Ensure you pass values for the `project` and `region` arguments into the provider configuration block. + +Ensure you are not setting values or environment variables for `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS`. Otherwise, these values may interfere with dynamic provider credentials. + +### Configure the Vault Provider + +If you were previously using the Vault provider to authenticate the GCP provider, remove any existing usage of the GCP secrets engine from your Terraform Code. +This includes instances of [`vault_generic_secret`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs/data-sources/generic_secret) that you previously used to generate GCP credentials. + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can add additional variables to handle multiple distinct Vault-backed GCP setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_backed_gcp_dynamic_credentials" { + description = "Object containing Vault-backed GCP dynamic credentials configuration" + type = object({ + default = object({ + credentials = string + access_token = string + }) + aliases = map(object({ + credentials = string + access_token = string + })) + }) +} +``` + +#### Example Usage + +##### Access Token + +```hcl +provider "google" { + access_token = var.tfc_vault_backed_gcp_dynamic_credentials.default.access_token +} + +provider "google" { + alias = "ALIAS1" + access_token = var.tfc_vault_backed_gcp_dynamic_credentials.aliases["ALIAS1"].access_token +} +``` + +##### Credentials + +```hcl +provider "google" { + credentials = var.tfc_vault_backed_gcp_dynamic_credentials.default.credentials +} + +provider "google" { + alias = "ALIAS1" + credentials = var.tfc_vault_backed_gcp_dynamic_credentials.aliases["ALIAS1"].credentials +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/index.mdx new file mode 100644 index 0000000000..29d2cd3396 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-backed/index.mdx @@ -0,0 +1,52 @@ +--- +page_title: Use Vault-backed dynamic credentials in Terraform Enterprise +description: >- + Vault-backed dynamic credentials leverage Vault to generate temporary + credentials for Terraform Enterprise runs. Learn how Vault-backed dynamic + credentials for AWS, Azure, and GCP can improve your security. +source: terraform-docs-common +--- + +# Use Vault-backed dynamic credentials + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.8.0](/terraform/cloud-docs/agents/changelog#1-8-0-04-18-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +For most use cases, separately configuring [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) with different cloud providers works well. However, Vault-backed dynamic credentials are for those looking for a way to: + +1. Use Vault's secrets engines as a centralized way to manage and consolidate cloud credentials management. +2. Generate short-lived credentials without exposing their Terraform Enterprise instance's OIDC metadata endpoints to the broader public internet. + +The "Vault-backed" in "Vault-backed dynamic credentials" refers to Vault's [secrets engines](/vault/docs/secrets), which allow you to generate short-lived [dynamic secrets](https://www.vaultproject.io/use-cases/dynamic-secrets) for the AWS, GCP, or Azure providers. If you are using Terraform Enterprise and your Vault instance is configured within the same secure network, you can generate secrets while keeping your environment air-gapped. + +Vault-backed dynamic credentials combine the features of dynamic provider credentials and Vault's secrets engines. This means you can authenticate a Vault instance using workload identity tokens and use secrets engines on that instance to generate dynamic credentials for the AWS, GCP, and Azure providers. + +For a comparison of Vault-backed dynamic credentials and dynamic provider credentials, refer to the article [Why use Vault-backed dynamic credentials to secure HCP Terraform infrastructure?](https://www.hashicorp.com/blog/why-use-vault-backed-dynamic-credentials-to-secure-hcp-terraform-infrastructure) on the HashiCorp blog. + +## Configure Vault-Backed Dynamic Credentials + +Using Vault-backed dynamic credentials in a workspace requires the following steps for each cloud platform: + +1. **Set up Dynamic Provider Credentials with the Vault Provider:** You must first [configure dynamic credentials with the Vault provider](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration). +2. **Configure the desired Secrets Engine**: You must configure the desired secrets engine in your Vault instance (i.e., AWS, GCP, or Azure). +3. **Configure HCP Terraform Workspace**: You must add specific environment variables to your workspace to tell HCP Terraform how to authenticate to other cloud providers during runs. Each cloud platform has its own set of environment variables that are necessary to configure dynamic credentials. + +Setting up Vault-backed dynamic credentials differs slightly for each cloud provider. You can configure Vault-backed dynamic credentials on the following platforms: + +- [Amazon Web Services](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed/aws-configuration) +- [Google Cloud Platform](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed/gcp-configuration) +- [Azure](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed/azure-configuration) + +## Terraform Enterprise Specific Requirements + +### Access to Metadata Endpoints + +In order to verify signed JWTs, Vault must have network access to the following static OIDC metadata endpoints within TFE: + +1. `/.well-known/openid-configuration` - standard OIDC metadata. +2. `/.well-known/jwks` - TFE’s public key(s) that cloud platforms use to verify the authenticity of tokens that claim to come from TFE. + +These endpoints **do not** need to be publicly exposed as long as your Vault instance can access them. + +### External Vault Policy + +If you are using an external Vault instance, you must ensure that your Vault instance has the correct policies setup as detailed in the [External Vault Requirements for Terraform Enterprise](/terraform/enterprise/requirements/data-storage/vault) documentation. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-configuration.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-configuration.mdx new file mode 100644 index 0000000000..8ed0483c1d --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/vault-configuration.mdx @@ -0,0 +1,225 @@ +--- +page_title: Use dynamic credentials with the Vault provider in Terraform Enterprise +description: >- + Use OpenID Connect to get short-term credentials for the Vault Terraform + provider in your Terraform Enterprise runs. +source: terraform-docs-common +--- + +# Use dynamic credentials with the Vault provider + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.7.0](/terraform/cloud-docs/agents/changelog#1-7-0-03-02-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +You can use HCP Terraform’s native OpenID Connect integration with Vault to get [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for the Vault provider in your HCP Terraform runs. Configuring the integration requires the following steps: + +1. **[Configure Vault](#configure-vault):** Set up a trust configuration between Vault and HCP Terraform. Then, you must create Vault roles and policies for your HCP Terraform workspaces. +2. **[Configure HCP Terraform](#configure-hcp-terraform):** Add environment variables to the HCP Terraform workspaces where you want to use Dynamic Credentials. + +Once you complete the setup, HCP Terraform automatically authenticates to Vault during each run. The Vault provider authentication is valid for the length of the plan or apply. Vault does not revoke authentication until the run is complete. + +If you are using Vault's [secrets engines](/vault/docs/secrets), you must complete the following set up before continuing to configure [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed). + +## Configure Vault + +You must enable and configure the JWT backend in Vault. These instructions use the Vault CLI commands, but you can also use Terraform to configure Vault. Refer to our [example Terraform configuration](https://github.com/hashicorp/terraform-dynamic-credentials-setup-examples/tree/main/vault). + +### Enable the JWT Auth Backend + +Run the following command to enable the JWT auth backend in Vault: + +```shell +vault auth enable jwt +``` + +### Configure Trust with HCP Terraform + +You must configure Vault to trust HCP Terraform’s identity tokens and verify them using HCP Terraform’s public key. The following command configures the `jwt` auth backend in Vault to trust HCP Terraform as an OIDC identity provider: + +```shell +vault write auth/jwt/config \ + oidc_discovery_url="https://app.terraform.io" \ + bound_issuer="https://app.terraform.io" +``` + +The `oidc_discovery_url` and `bound_issuer` should both be the root address of HCP Terraform, including the scheme and without a trailing slash. + +#### Terraform Enterprise Specific Requirements + +If you are using a custom or self-signed CA certificate you may need to specify the CA certificate or chain of certificates, in PEM format, via the [`oidc_discovery_ca_pem`](/vault/api-docs/auth/jwt#oidc_discovery_ca_pem) argument as shown in the following example command: + +```shell +vault write auth/jwt/config \ + oidc_discovery_url="https://app.terraform.io" \ + bound_issuer="https://app.terraform.io" \ + oidc_discovery_ca_pem=@my-cert.pem +``` + +In the example above, `my-cert.pem` is a PEM formatted file containing the certificate. + +### Create a Vault Policy + +You must create a Vault policy that controls what paths and secrets your HCP Terraform workspace can access in Vault. +Create a file called tfc-policy.hcl with the following content: + +```hcl +# Allow tokens to query themselves +path "auth/token/lookup-self" { + capabilities = ["read"] +} + +# Allow tokens to renew themselves +path "auth/token/renew-self" { + capabilities = ["update"] +} + +# Allow tokens to revoke themselves +path "auth/token/revoke-self" { + capabilities = ["update"] +} + +# Configure the actual secrets the token should have access to +path "secret/*" { + capabilities = ["read"] +} +``` + +Then create the policy in Vault: + +```shell +vault policy write tfc-policy tfc-policy.hcl +``` + +### Create a JWT Auth Role + +Create a Vault role that HCP Terraform can use when authenticating to Vault. + +Vault offers a lot of flexibility in determining how to map roles and permissions in Vault to workspaces in HCP Terraform. You can have one role for each workspace, one role for a group of workspaces, or one role for all workspaces in an organization. You can also configure different roles for the plan and apply phases of a run. + +-> **Note:** If you set your `user_claim` to be per workspace, then Vault ties the entity it creates to that workspace's name. If you rename the workspace tied to your `user_claim`, Vault will create an additional identity object. To avoid this, update the alias name in Vault to your new workspace name before you update it in HCP Terraform. + +The following example creates a role called `tfc-role`. The role is mapped to a single workspace and HCP Terraform can use it for both plan and apply runs. + +Create a file called `vault-jwt-auth-role.json` with the following content: + +```json +{ + "policies": ["tfc-policy"], + "bound_audiences": ["vault.workload.identity"], + "bound_claims_type": "glob", + "bound_claims": { + "sub": +"organization:my-org-name:project:my-project-name:workspace:my-workspace-name:run_phase:*" + }, + "user_claim": "terraform_full_workspace", + "role_type": "jwt", + "token_ttl": "20m" +} +``` + +Then run the following command to create a role named `tfc-role` with this configuration in Vault: + +```shell +vault write auth/jwt/role/tfc-role @vault-jwt-auth-role.json +``` + +To understand all the available options for matching bound claims, refer to the [Terraform workload identity claim specification](/terraform/enterprise/workspaces/dynamic-provider-credentials) and the [Vault documentation on configuring bound claims](/vault/docs/auth/jwt#bound-claims). To understand all the options available when configuring Vault JWT auth roles, refer to the [Vault API documentation](/vault/api-docs/auth/jwt#create-role). + +!> **Warning:** you should always check, at minimum, the audience and the name of the organization in order to prevent unauthorized access from other HCP Terraform organizations! + +#### Token TTLs + +We recommend setting token_ttl to a relatively short value. HCP Terraform can renew the token periodically until the plan or apply is complete, then revoke it to prevent it from being used further. + +## Configure HCP Terraform + +You’ll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with Vault using dynamic credentials. You can set these as workspace variables, or if you’d like to share one Vault role across multiple workspaces, you can use a variable set. When you configure dynamic provider credentials with multiple provider configurations of the same type, use either a default variable or a tagged alias variable name for each provider configuration. Refer to [Specifying Multiple Configurations](#specifying-multiple-configurations) for more details. + +### Required Environment Variables + +| Variable | Value | Notes | +| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_PROVIDER_AUTH`
`TFC_VAULT_PROVIDER_AUTH[_TAG]`
_(Default variable not supported)_ | `true` | Requires **v1.7.0** or later if self-managing agents. Must be present and set to `true`, or HCP Terraform will not attempt to authenticate to Vault. | +| `TFC_VAULT_ADDR`
`TFC_VAULT_ADDR[_TAG]`
`TFC_DEFAULT_VAULT_ADDR` | The address of the Vault instance to authenticate against. | Requires **v1.7.0** or later if self-managing agents. Will also be used to set `VAULT_ADDR` in the run environment. | +| `TFC_VAULT_RUN_ROLE`
`TFC_VAULT_RUN_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_RUN_ROLE` | The name of the Vault role to authenticate against (`tfc-role`, in our example). | Requires **v1.7.0** or later if self-managing agents. Optional if `TFC_VAULT_PLAN_ROLE` and `TFC_VAULT_APPLY_ROLE` are both provided. These variables are described [below](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-configuration#optional-environment-variables) | + +### Optional Environment Variables + +You may need to set these variables, depending on your Vault configuration and use case. + +| Variable | Value | Notes | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `TFC_VAULT_NAMESPACE`
`TFC_VAULT_NAMESPACE[_TAG]`
`TFC_DEFAULT_VAULT_NAMESPACE` | The namespace to use when authenticating to Vault. | Requires **v1.7.0** or later if self-managing agents. Will also be used to set `VAULT_NAMESPACE` in the run environment. | +| `TFC_VAULT_AUTH_PATH`
`TFC_VAULT_AUTH_PATH[_TAG]`
`TFC_DEFAULT_VAULT_AUTH_PATH` | The path where the JWT auth backend is mounted in Vault. Defaults to jwt. | Requires **v1.7.0** or later if self-managing agents. | +| `TFC_VAULT_WORKLOAD_IDENTITY_AUDIENCE`
`TFC_VAULT_WORKLOAD_IDENTITY_AUDIENCE[_TAG]`
`TFC_DEFAULT_VAULT_WORKLOAD_IDENTITY_AUDIENCE` | Will be used as the `aud` claim for the identity token. Defaults to `vault.workload.identity`. | Requires **v1.7.0** or later if self-managing agents. Must match the `bound_audiences` configured for the role in Vault. | +| `TFC_VAULT_PLAN_ROLE`
`TFC_VAULT_PLAN_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_PLAN_ROLE` | The Vault role to use for the plan phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_RUN_ROLE` if not provided. | +| `TFC_VAULT_APPLY_ROLE`
`TFC_VAULT_APPLY_ROLE[_TAG]`
`TFC_DEFAULT_VAULT_APPLY_ROLE` | The Vault role to use for the apply phase of a run. | Requires **v1.7.0** or later if self-managing agents. Will fall back to the value of `TFC_VAULT_RUN_ROLE` if not provided. | +| `TFC_VAULT_ENCODED_CACERT`
`TFC_VAULT_ENCODED_CACERT[_TAG]`
`TFC_DEFAULT_VAULT_ENCODED_CACERT` | A PEM-encoded CA certificate that has been Base64 encoded. | Requires **v1.9.0** or later if self-managing agents. This certificate will be used when connecting to Vault. May be required when connecting to Vault instances that use a custom or self-signed certificate. | + +## Vault Provider Configuration + +Once you set up dynamic credentials for a workspace, HCP Terraform automatically authenticates to Vault for each run. Do not pass the `address`, `token`, or `namespace` arguments into the provider configuration block. HCP Terraform sets these values as environment variables in the run environment. + +You can use the Vault provider to read static secrets from Vault and use them with other Terraform resources. You can also access the other resources and data sources available in the [Vault provider documentation](https://registry.terraform.io/providers/hashicorp/vault/latest). You must adjust your [Vault policy](#create-a-vault-policy) to give your HCP Terraform workspace access to all required Vault paths. + +~> **Important:** data sources that use secrets engines to generate dynamic secrets must not be used with Vault dynamic credentials. You can use Vault's dynamic secrets engines for AWS, GCP, and Azure by adding additional configurations. For more details, see [Vault-backed dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials/vault-backed). + +### Specifying Multiple Configurations + +~> **Important:** If you are self-hosting [HCP Terraform agents](/terraform/cloud-docs/agents), ensure your agents use [v1.12.0](/terraform/cloud-docs/agents/changelog#1-12-0-07-26-2023) or above. To use the latest dynamic credentials features, [upgrade your agents to the latest version](/terraform/cloud-docs/agents/changelog). + +~> **Important:** Ensure you are using version **3.18.0** or later of the **Vault provider** as the required [`auth_login_token_file`](https://registry.terraform.io/providers/hashicorp/vault/latest/docs#token-file) block was introduced in this provider version. + +You can add additional variables to handle multiple distinct Vault setups, enabling you to use multiple [provider aliases](/terraform/language/providers/configuration#alias-multiple-provider-configurations) within the same workspace. You can configure each set of credentials independently, or use default values by configuring the variables prefixed with `TFC_DEFAULT_`. + +For more details, see [Specifying Multiple Configurations](/terraform/enterprise/workspaces/dynamic-provider-credentials/specifying-multiple-configurations). + +#### Required Terraform Variable + +To use additional configurations, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks. + +```hcl +variable "tfc_vault_dynamic_credentials" { + description = "Object containing Vault dynamic credentials configuration" + type = object({ + default = object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + }) + aliases = map(object({ + token_filename = string + address = string + namespace = string + ca_cert_file = string + })) + }) +} +``` + +#### Example Usage + +```hcl +provider "vault" { + // skip_child_token must be explicitly set to true as HCP Terraform manages the token lifecycle + skip_child_token = true + address = var.tfc_vault_dynamic_credentials.default.address + namespace = var.tfc_vault_dynamic_credentials.default.namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.default.token_filename + } +} + +provider "vault" { + // skip_child_token must be explicitly set to true as HCP Terraform manages the token lifecycle + skip_child_token = true + alias = "ALIAS1" + address = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].address + namespace = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].namespace + + auth_login_token_file { + filename = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].token_filename + } +} +``` diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens.mdx new file mode 100644 index 0000000000..26851ac640 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/dynamic-provider-credentials/workload-identity-tokens.mdx @@ -0,0 +1,99 @@ +--- +page_title: Workload identity in Terraform Enterprise +description: >- + Learn how workload identity uses OpenID Connect (OIDC) to allow Terraform + plans and applies to safely authenticate to external systems. +source: terraform-docs-common +--- + +# Workload identity + +Dynamic Provider Credentials are powered by Terraform Workload Identity, which allows HCP Terraform to present information about a Terraform workload to an external system – like its workspace, organization, or whether it’s a plan or apply – and allows other external systems to verify that the information is accurate. + +You can think of it like an identity card for your Terraform runs: one that comes with a way for another system to easily verify whether the card is genuine. If the other system can confirm that the ID card is legitimate, it can trust the information the card contains and use it to decide whether to let that Terraform workload in the door. + +The “identity card” in this analogy is a workload identity token: a JSON Web Token (JWT) that contains information about a plan or apply, is signed by HCP Terraform’s private key, and expires at the end of the plan or apply timeout. Other systems can use HCP Terraform’s [public key](https://app.terraform.io/.well-known/jwks) to verify that a token that claims to be from HCP Terraform is genuine and has not been tampered with. + +This workflow is built on the [OpenID Connect protocol](https://openid.net/connect/), a trusted standard for verifying identity across different systems. + +## Token Specification + +Workload identity tokens contain useful metadata in their payloads, known as _claims_. This is the equivalent of the name and date of birth on an identity card. Once a cloud platform verifies a token using HCP Terraform’s public key, it can look at the claims in the identity token to either match it to the correct permissions or reject it. + +You don’t need to understand the full token specification and what every claim means in order to use dynamic credentials, but it’s useful for debugging. + +### Token Structure + +The following example shows a decoded HCP Terraform workload identity token: + +#### Header + +```json +{ + "typ": "JWT", + "alg": "RS256", + "kid": "j-fFp9evPJAzV5I2_58HY5UvdCK6Q4LLB1rnPOUfQAk" +} +``` + +#### Payload + +```json +{ + "jti": "1192426d-b525-4fde-9d42-f238be437bbd", + "iss": "https://app.terraform.io", + "aud": "my-example-audience", + "iat": 1650486122, + "nbf": 1650486117, + "exp": 1650486422, + "sub": "organization:my-org:project:Default Project:workspace:my-workspace:run_phase:apply", + "terraform_organization_id": "org-GRNbCjYNpBB6NEH9", + "terraform_organization_name": "my-org", + "terraform_project_id": "prj-vegSA59s1XPwMr2t", + "terraform_project_name": "Default Project", + "terraform_workspace_id": "ws-mbsd5E3Ktt5Rg2Xm", + "terraform_workspace_name": "my-workspace", + "terraform_full_workspace": "organization:my-org:project:Default Project:workspace:my-workspace", + "terraform_run_id": "run-X3n1AUXNGWbfECsJ", + "terraform_run_phase": "apply" +} +``` + +This payload includes a number of standard claims defined in the OIDC spec as well as a number of custom claims for further customization. + +### Standard Claims + +| Claim | Value | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `jti` (JWT ID) | A unique identifier for each JWT. | +| `iss` (issuer) | Full URL of HCP Terraform or the Terraform Enterprise instance which signed the JWT. | +| `iat` (issued at) | Unix Timestamp when the JWT was issued. May be required by certain relying parties. | +| `nbf` (not before) | Unix Timestamp when the JWT can start being used. This will be the same as `iat` for tokens issued by HCP Terraform, but may be required by certain relying parties. | +| `aud` (audience) | Intended audience for the JWT. For example, `aws.workload.identity` for AWS. This can be customized. | +| `exp` (expiration) | Unix Timestamp based on the timeout of the run phase that it was issued for. This will follow the `plan` and `apply` timeouts set at the organization and site admin level. | +| `sub` (subject) | Fully qualified path to a workspace, followed by the run phase. For example: `organization:my-organization-name:project:Default Project:workspace:my-workspace-name:run_phase:apply` | + +### Custom Claims + +| Claim | Value | +| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `terraform_organization_id` (organization ID) | ID of the HCP Terraform organization performing the run. | +| `terraform_organization_name` (organization name) | Human-readable name of the HCP Terraform organization performing the run. Note that organization names can be changed. | +| `terraform_project_id` (project ID) | ID of the HCP Terraform project performing the run. | +| `terraform_project_name` (project name) | Human-readable name of the HCP Terraform project performing the run. Note that project names can be changed. The default project name is `Default Project`. | +| `terraform_workspace_id` (workspace ID) | ID of the HCP Terraform workspace performing the run. | +| `terraform_workspace_name` (workspace name) | Human-readable name of the HCP Terraform workspace performing the run. Note that workspace names can be changed. | +| `terraform_full_workspace` (fully qualified workspace) | Fully qualified path to a workspace. For example: `organization:my-organization-name:project:my-project-name:workspace:my-workspace-name` | +| `terraform_run_id` (run ID) | ID of the run that the token was generated for. This is intended to aid in traceability and logging. | +| `terraform_run_phase` (run phase) | The phase of the run this token was issued for. For example, `plan` or `apply` | + +### Configuring Trust with your Cloud Platform + +When configuring the trust relationship between HCP Terraform and your cloud platform, you’ll set up conditions to validate the contents of the identity token provided by HCP Terraform against your roles and policies. + +At the minimum, you should match against the following claims: + +- `aud` - the audience value of the token. This ensures that, for example, a workload identity token intended for AWS can’t be used to authenticate to Vault. +- `sub` - the subject value, which includes the organization and workspace performing the run. If you don’t match against at least the organization name, any organization or workspace on HCP Terraform will be able to access your cloud resources! + +You can match on as many claims as you want, depending on your cloud platform. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/health.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/health.mdx new file mode 100644 index 0000000000..21c209b819 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/health.mdx @@ -0,0 +1,245 @@ +--- +page_title: Health assessments in Terraform Enterprise +description: >- + Learn how Terraform Enterprise can continuously monitor workspaces to assess + whether their real infrastructure matches the requirements defined in your + Terraform configuration. +source: terraform-docs-common +--- + +# Health + +HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations: + +- [Drift detection](#drift-detection) determines whether your real-world infrastructure matches your Terraform configuration. +- [Continuous validation](#continuous-validation) determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. + +When you enable health assessments, HCP Terraform periodically runs health assessments for your workspace. Refer to [Health Assessment Scheduling](#health-assessment-scheduling) for details. + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +## Permissions + +Working with health assessments requires the following permissions: + +- To view health status for a workspace, you need read access to that workspace. +- To change organization health settings, you must be an [organization owner](/terraform/enterprise/users-teams-organizations/permissions#organization-owners). +- To change a workspace’s health settings, you must be an [administrator for that workspace](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins). + +- To trigger [on-demand health assessments](/terraform/enterprise/workspaces/health#on-demand-assessments) for a workspace, you must be an [administrator for that workspace](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins). + + +## Workspace requirements + +Workspaces require the following settings to receive health assessments: + +- Terraform version 0.15.4+ for drift detection only +- Terraform version 1.3.0+ for drift detection and continuous validation +- [Remote execution mode](/terraform/enterprise/workspaces/settings#execution-mode) or [Agent execution mode](/terraform/cloud-docs/agents/agent-pools#configure-workspaces-to-use-the-agent) for Terraform runs + +The latest Terraform run in the workspace must have been successful. If the most recent run ended in an errored, canceled, or discarded state, HCP Terraform pauses health assessments until there is a successfully applied run. + +The workspace must also have at least one run in which Terraform successfully applies a configuration. HCP Terraform does not perform health assessments in workspaces with no real-world infrastructure. + +## Enable health assessments + +You can enforce health assessments across all eligible workspaces in an organization within the [organization settings](/terraform/enterprise/users-teams-organizations/organizations#health). Enforcing health assessments at an organization-level overrides workspace-level settings. You can only enable health assessments within a specific workspace when HCP Terraform is not enforcing health assessments at the organization level. + +To enable health assessments within a workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to enable health assessments on. +2. Verify that your workspace satisfies the [requirements](#workspace-requirements). +3. Go to the workspace and click **Settings**, then click **Health**. +4. Select **Enable** under **Health Assessments**. +5. Click **Save settings**. + +## Health assessment scheduling + +When you enable health assessments for a workspace, HCP Terraform runs the first health assessment based on whether there are active Terraform runs for the workspace: + +- **No active runs:** A few minutes after you enable the feature. +- **Active speculative plan:** A few minutes after that plan is complete. +- **Other active runs:** During the next assessment period. + +After the first health assessment, HCP Terraform starts a new health assessment during the next assessment period if there are no active runs in the workspace. Health assessments may take longer to complete when you enable health assessments in many workspaces at once or your workspace contains a complex configuration with many resources. + +A health assessment never interrupts or interferes with runs. If you start a new run during a health assessment, HCP Terraform cancels the current assessment and runs the next assessment during the next assessment period. This behavior may prevent HCP Terraform from performing health assessments in workspaces with frequent runs. + +HCP Terraform pauses health assessments if the latest run ended in an errored state. This behavior occurs for all run types, including plan-only runs and speculative plans. Once the workspace completes a successful run, HCP Terraform restarts health assessments during the next assessment period. + +Terraform Enterprise administrators can modify their installation's [assessment frequency and number of maximum concurrent assessments](/terraform/enterprise/admin/application/general#health-assessments) from the admin settings console. + + + +### On-demand assessments + +-> **Note:** On-demand assessments are only available in the HCP Terraform user interface. + +If you are an administrator for a workspace and it satisfies all [assessment requirements](/terraform/enterprise/workspaces/health#workspace-requirements), you can trigger a new assessment by clicking **Start health assessment** on the workspace's **Health** page. + +After clicking **Start health assessment**, the workspace displays a message in the bottom lefthand corner of the page to indicate if it successfully triggered a new assessment. The time it takes to complete an assessment can vary based on network latency and the number of resources managed by the workspace. + +You cannot trigger another assessment while one is in progress. An on-demand assessment resets the scheduling for automated assessments, so HCP Terraform waits to run the next assessment until the next scheduled period. + + + +### Concurrency + +If you enable health assessments on multiple workspaces, assessments may run concurrently. Health assessments do not affect your concurrency limit. HCP Terraform also monitors and controls health assessment concurrency to avoid issues for large-scale deployments with thousands of workspaces. However, HCP Terraform performs health assessments in batches, so health assessments may take longer to complete when you enable them in a large number of workspaces. + +### Notifications + +HCP Terraform sends [notifications](/terraform/enterprise/workspaces/settings/notifications) about health assessment results according to your workspace’s settings. + +## Workspace health status + +On the organization's **Workspaces** page, HCP Terraform displays a **Health warning** status for workspaces with infrastructure drift or failed continuous validation checks. + +On the right of a workspace’s overview page, HCP Terraform displays a **Health** bar that summarizes the results of the last health assessment. + +- The **Drift** summary shows the total number of resources in the configuration and the number of resources that have drifted. +- The **Checks** summary shows the number of passed, failed, and unknown statuses for objects with continuous validation checks. + + + +### View workspace health in explorer + +The [Explorer page](/terraform/enterprise/workspaces/explorer) presents a condensed overview of the health status of the workspaces within your organization. You can see the following information: + +- Workspaces that are monitoring workspace health +- Status of any configured continuous validation checks +- Count of drifted resources for each workspace + +For additional details on the data available for reporting, refer to the [Explorer](/terraform/enterprise/workspaces/explorer) documentation. + +![Viewing Workspace Health in Explorer](/img/docs/tfc-explorer-health.png) + + + +## Drift detection + +Drift detection helps you identify situations where your actual infrastructure no longer matches the configuration defined in Terraform. This deviation is known as _configuration drift_. Configuration drift occurs when changes are made outside Terraform's regular process, leading to inconsistencies between the remote objects and your configured infrastructure. + +For example, a teammate could create configuration drift by directly updating a storage bucket's settings with conflicting configuration settings using the cloud provider's console. Drift detection could detect these differences and recommend steps to address and rectify the discrepancies. + +Configuration drift differs from state drift. Drift detection does not detect state drift. + +Configuration drift happens when external changes affecting remote objects invalidate your infrastructure configuration. State drift occurs when external changes affecting remote objects _do not_ invalidate your infrastructure configuration. Refer to [Refresh-Only Mode](/terraform/enterprise/run/modes-and-options#refresh-only-mode) to learn more about remediating state drift. + +### View workspace drift + +To view the drift detection results from the latest health assessment, go to the workspace and click **Health > Drift**. If there is configuration drift, HCP Terraform proposes the necessary changes to bring the infrastructure back in sync with its configuration. + +### Resolve drift + +You can use one of the following approaches to correct configuration drift: + +- **Overwrite drift**: If you do not want the drift's changes, queue a new plan and apply the changes to revert your real-world infrastructure to match your Terraform configuration. +- **Update Terraform configuration:** If you want the drift's changes, modify your Terraform configuration to include the changes and push a new configuration version. This prevents Terraform from reverting the drift during the next apply. Refer to the [Manage Resource Drift](/terraform/tutorials/state/resource-drift) tutorial for a detailed example. + +## Continuous validation + +Continuous validation regularly verifies whether your configuration’s custom assertions continue to pass, validating your infrastructure. For example, you can monitor whether your website returns an expected status code, or whether an API gateway certificate is valid. Identifying failed assertions helps you resolve the failure and prevent errors during your next time Terraform operation. + +Continuous validation evaluates preconditions, postconditions, and check blocks as part of an assessment, but we recommend using [check blocks](/terraform/language/checks) for post-apply monitoring. Use check blocks to create custom rules to validate your infrastructure's resources, data sources, and outputs. + +### Preventing false positives + +Health assessments create a speculative plan to access the current state of your infrastructure. Terraform evaluates any check blocks in your configuration as the last step of creating the speculative plan. If your configuration relies on data sources and the values queried by a data source change between the time of your last run and the assessment, the speculative plan will include those changes. HCP Terraform will not modify your infrastructure as part of an assessment, but it can use those updated values to evaluate checks. This may lead to false positive results for alerts since your infrastructure did not yet change. + +To ensure your checks evaluate the current state of your configuration instead of against a possible future change, use nested data sources that query your actual resource configuration, rather than a computed latest value. Refer to the [AMI image scenario](#asserting-up-to-date-amis-for-compute-instances) below for an example. + +### Example use cases + +Review the provider documentation for `check` block examples with [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/continuous-validation-examples), [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/tfc-check-blocks), and [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/google-continuous-validation). + +#### Monitoring the health of a provisioned website + +The following example uses the [HTTP](https://registry.terraform.io/providers/hashicorp/http/latest/docs) Terraform provider and a [scoped data source](/terraform/language/checks#scoped-data-sources) within a [`check` block](/terraform/language/checks) to assert the Terraform website returns a `200` status code, indicating it is healthy. + +```hcl +check "health_check" { + data "http" "terraform_io" { + url = "https://www.terraform.io" + } + + assert { + condition = data.http.terraform_io.status_code == 200 + error_message = "${data.http.terraform_io.url} returned an unhealthy status code" + } +} +``` + +Continuous Validation alerts you if the website returns any status code besides `200` while Terraform evaluates this assertion. You can also find failures in your workspace's [Continuous Validation Results](#view-continuous-validation-results) page. You can configure continuous validation alerts in your workspace's [notification settings](/terraform/enterprise/workspaces/settings/notifications). + +#### Monitoring certificate expiration + +[Vault](https://www.vaultproject.io/) lets you secure, store, and tightly control access to tokens, passwords, certificates, encryption keys, and other sensitive data. The following example uses a `check` block to monitor for the expiration of a Vault certificate. + +```hcl +resource "vault_pki_secret_backend_cert" "app" { + backend = vault_mount.intermediate.path + name = vault_pki_secret_backend_role.test.name + common_name = "app.my.domain" +} + +check "certificate_valid" { + assert { + condition = !vault_pki_secret_backend_cert.app.renew_pending + error_message = "Vault cert is ready to renew." + } +} +``` + +#### Asserting up-to-date AMIs for compute instances + +[HCP Packer](/hcp/docs/packer) stores metadata about your [Packer](https://www.packer.io/) images. The following example check fails when there is a newer AMI version available. + +```hcl +data "hcp_packer_artifact" "hashiapp_image" { + bucket_name = "hashiapp" + channel_name = "latest" + platform = "aws" + region = "us-west-2" +} + +resource "aws_instance" "hashiapp" { + ami = data.hcp_packer_artifact.hashiapp_image.external_identifier + instance_type = var.instance_type + associate_public_ip_address = true + subnet_id = aws_subnet.hashiapp.id + vpc_security_group_ids = [aws_security_group.hashiapp.id] + key_name = aws_key_pair.generated_key.key_name + + tags = { + Name = "hashiapp" + } +} + +check "ami_version_check" { + data "aws_instance" "hashiapp_current" { + instance_tags = { + Name = "hashiapp" + } + } + + assert { + condition = aws_instance.hashiapp.ami == data.hcp_packer_artifact.hashiapp_image.external_identifier + error_message = "Must use the latest available AMI, ${data.hcp_packer_artifact.hashiapp_image.external_identifier}." + } +} +``` + +### View continuous validation results + +To view the continuous validation results from the latest health assessment, go to the workspace and click **Health > Continuous validation**. + +The page shows all of the resources, outputs, and data sources with custom assertions that HCP Terraform evaluated. Next to each object, HCP Terraform reports whether the assertion passed or failed. If one or more assertions fail, HCP Terraform displays the error messages for each assertion. + +The health assessment page displays each assertion by its [named value](/terraform/language/expressions/references). A `check` block's named value combines the prefix `check` with its configuration name. + +If your configuration contains multiple [preconditions and postconditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) within a single resource, output, or data source, HCP Terraform will not show the results of individual conditions unless they fail. If all custom conditions on the object pass, HCP Terraform reports that the entire check passed. The assessment results will display the results of any precondition and postconditions alongside the results of any assertions from `check` blocks, identified by the named values of their parent block. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/index.mdx new file mode 100644 index 0000000000..2c2f763bec --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/index.mdx @@ -0,0 +1,100 @@ +--- +page_title: Terraform Enterprise workspaces +description: >- + A workspace is a group of infrastructure resources managed by Terraform + Enterprise. Learn what workspaces contain, how they perform Terraform runs, + and how to create and organize them. +source: terraform-docs-common +--- + +# Workspaces + +This topic provides an overview of the workspaces resource in HCP Terraform and Terraform Enterprise. A workspace is a group of infrastructure resources managed by Terraform. + +## Introduction + +Working with Terraform involves managing collections of infrastructure resources, and most organizations manage many different collections. + +When run locally, Terraform manages each collection of infrastructure with a persistent working directory, which contains a configuration, state data, and variables. Since Terraform CLI uses content from the directory it runs in, you can organize infrastructure resources into meaningful groups by keeping their configurations in separate directories. + +HCP Terraform manages infrastructure collections with workspaces instead of directories. A workspace contains everything Terraform needs to manage a given collection of infrastructure, and separate workspaces function like completely separate working directories. + +> **Hands-on:** Try the [Create a Workspace](/terraform/tutorials/cloud-get-started/cloud-workspace-create) tutorial. + +## Workspace Contents + +HCP Terraform workspaces and local working directories serve the same purpose, but they store their data differently: + +| Component | Local Terraform | HCP Terraform | +| ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | +| Terraform configuration | On disk | In linked version control repository, or periodically uploaded via API/CLI | +| Variable values | As `.tfvars` files, as CLI arguments, or in shell environment | In workspace | +| State | On disk or in remote backend | In workspace | +| Credentials and secrets | In shell environment or entered at prompts | In workspace, stored as sensitive variables | + +In addition to the basic Terraform content, HCP Terraform keeps some additional data for each workspace: + +- **State versions:** Each workspace retains backups of its previous state files. Although only the current state is necessary for managing resources, the state history can be useful for tracking changes over time or recovering from problems. Refer to [Terraform State in HCP Terraform](/terraform/enterprise/workspaces/state) for more details. + +- **Run history:** When HCP Terraform manages a workspace's Terraform runs, it retains a record of all run activity, including summaries, logs, a reference to the changes that caused the run, and user comments. Refer to [Viewing and Managing Runs](/terraform/enterprise/run/manage) for more details. + + + +The top of each workspace shows a resource count, which reflects the number of resources recorded in the workspace’s state file. This includes both managed [resources](/terraform/language/resources/syntax) and [data sources](/terraform/language/data-sources). + + + +## Terraform Runs + +For workspaces with remote operations enabled (the default), HCP Terraform performs Terraform runs on its own disposable virtual machines, using that workspace's configuration, variables, and state. + +Refer to [Terraform Runs and Remote Operations](/terraform/enterprise/run/remote-operations) for more details. + +## HCP Terraform vs. Terraform CLI Workspaces + +Both HCP Terraform and Terraform CLI have features called workspaces, but they function differently. + +- HCP Terraform workspaces are required. They represent all of the collections of infrastructure in an organization. They are also a major component of role-based access in HCP Terraform. You can grant individual users and user groups permissions for one or more workspaces that dictate whether they can manage variables, perform runs, etc. You cannot manage resources in HCP Terraform without creating at least one workspace. + +- Terraform CLI workspaces are associated with a specific working directory and isolate multiple state files in the same working directory, letting you manage multiple groups of resources with a single configuration. The Terraform CLI does not require you to create CLI workspaces. Refer to [Workspaces](/terraform/language/state/workspaces) in the Terraform Language documentation for more details. + +## Planning and Organizing Workspaces + +We recommend that organizations break down large monolithic Terraform configurations into smaller ones, then assign each one to its own workspace and delegate permissions and responsibilities for them. HCP Terraform can manage monolithic configurations just fine, but managing infrastructure as smaller components is the best way to take full advantage of HCP Terraform's governance and delegation features. + +For example, the code that manages your production environment's infrastructure could be split into a networking configuration, the main application's configuration, and a monitoring configuration. After splitting the code, you would create "networking-prod", "app1-prod", "monitoring-prod" workspaces, and assign separate teams to manage them. + +Much like splitting monolithic applications into smaller microservices, this enables teams to make changes in parallel. In addition, it makes it easier to re-use configurations to manage other environments of infrastructure ("app1-dev," etc.). + +In Terraform Enterprise, administrators can use [Admin Settings](/terraform/enterprise/api-docs/admin/settings) to set the maximum number of workspaces for any single organization. You can also set a workspaces limit with the [tfe-terraform-provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/organization#workspace_limit). + +## Organize Workspaces with Projects + +Projects let you organize your workspaces into groups. + + + +@include 'tfc-package-callouts/project-workspaces.mdx' + + + +Refer to [Organize Workspaces with Projects](/terraform/enterprise/projects/manage) for more details. + +## Creating Workspaces + +You can create workspaces through the [HCP Terraform UI](/terraform/enterprise/workspaces/create), the [Workspaces API](/terraform/enterprise/api-docs/workspaces), or the [HCP Terraform CLI integration](/terraform/cli/cloud). + +## Workspace Health + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +HCP Terraform can perform automatic health assessments in a workspace to assess whether its real infrastructure matches the requirements defined in its Terraform configuration. Health assessments include the following types of evaluations: + +- Drift detection determines whether your real-world infrastructure matches your Terraform configuration. +- Continuous validation determines whether custom conditions in the workspace’s configuration continue to pass after Terraform provisions the infrastructure. + +You can enforce health assessments for all eligible workspaces or let each workspace opt in to health assessments through workspace settings. Refer to [Health](/terraform/enterprise/workspaces/health) in the workspaces documentation for more details. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/json-filtering.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/json-filtering.mdx new file mode 100644 index 0000000000..c70eb74e3f --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/json-filtering.mdx @@ -0,0 +1,117 @@ +--- +page_title: JSON data filtering in Terraform Enterprise +description: >- + Learn how to filter and create custom datasets on pages that display JSON data + in Terraform Enterprise. +source: terraform-docs-common +--- + +# JSON data filtering + +Certain pages where JSON data is displayed, such as the [state +viewer](/terraform/enterprise/workspaces/state) and [policy check JSON data +viewer](/terraform/enterprise/policy-enforcement/sentinel/json), allow you to filter the results. This +enables you to see just the data you need, and even create entirely new datasets +to see data in the way you want to see it! + +![entering a json filter](/img/docs/json-viewer-intro.png) + +-> **NOTE:** _Filtering_ the data in the JSON viewer is separate from +_searching_ it. To search, press Control-F (or Command-F on MacOS). You can +search and apply a filter at the same time. + +## Entering a Filter + +Filters are entered by putting the filter in the aptly named **filter** box in +the JSON viewer. After entering the filter, pressing **Apply** or the enter key +on your keyboard will apply the filter. The filtered results, if any, are +displayed in result box. Clearing the filter will restore the original JSON +data. + +![entering a json filter](/img/docs/sentinel-json-enter-filter.png) + +## Filter Language + +The JSON filter language is a small subset of the +[jq](https://stedolan.github.io/jq/) JSON filtering language. Selectors, +literals, indexes, slices, iterators, and pipes are supported, as are also array +and object construction. At this time, parentheses, and more complex operations +such as mathematical operators, conditionals, and functions are not supported. + +Below is a quick reference of some of the more basic functions to get you +started. + +### Selectors + +Selectors allow you to pick an index out of a JSON object, and are written as +`.KEY.SUBKEY`. So, as an example, given an object of +`{"foo": {"bar": "baz"}}`, and the filter `.foo.bar`, the result would be +displayed as `"baz"`. + +A single dot (`.`) without anything else always denotes the current value, +unaltered. + +### Indexes + +Indexes can be used to fetch array elements, or select non-alphanumeric object +fields. They are written as `[0]` or `["foo-bar"]`, depending on the purpose. + +Given an object of `{"foo-bar": ["baz", "qux"]}` and the filter of +`.["foo-bar"][0]`, the result would be displayed as `"baz"`. + +### Slices + +Arrays can be sliced to get a subset an array. The syntax is `[LOW:HIGH]`. + +Given an array of `[0, 1, 2, 3, 4]` and the filter of +`.[1:3]`, the result would be displayed as `[1, 2]`. This also illustrates that +the result of the slice operation is always of length HIGH-LOW. + +Slices can also be applied to strings, in which a substring is returned with the +same rules applied, with the first character of the string being index 0. + +### Iterators + +Iterators can iterate over arrays and objects. The syntax is `[]`. + +Iterators iterate over the _values_ of an object only. So given a object of +`{"foo": 1, "bar": 2}`, the filter `.[]` would yield an iteration of `1, 2`. + +Note that iteration results are not necessarily always arrays. Iterators are +handled in a special fashion when dealing with pipes and object creators (see +below). + +### Array Construction + +Wrapping an expression in brackets (`[ ... ]`) creates an array with the +sub-expressions inside the array. The results are always concatenated. + +For example, for an object of `{"foo": [1, 2], "bar": [3, 4]}`, the construction +expressions `[.foo[], .bar[]]` and `[.[][]]`, are the same, producing the +resulting array `[1, 2, 3, 4]`. + +### Object Construction + +Wrapping an expression in curly braces `{KEY: EXPRESSION, ...}` creates an +object. + +Iterators work uniquely with object construction in that an object is +constructed for each _iteration_ that the iterator produces. + +As a basic example, Consider an array `[1, 2, 3]`. While the expression +`{foo: .}` will produce `{"foo": [1, 2, 3]}`, adding an iterator to the +expression so that it reads `{foo: .[]}` will produce 3 individual objects: +`{"foo": 1}`, `{"foo": 2}`, and `{"foo": 3}`. + +### Pipes + +Pipes allow the results of one expression to be fed into another. This can be +used to re-write expressions to help reduce complexity. + +Iterators work with pipes in a fashion similar to object construction, where the +expression on the right-hand side of the pipe is evaluated once for every +iteration. + +As an example, for the object `{"foo": {"a": 1}, "bar": {"a": 2}}`, both the +expression `{z: .[].a}` and `.[] | {z: .a}` produce the same result: `{"z": 1}` +and `{"z": 2}`. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/access.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/access.mdx new file mode 100644 index 0000000000..abad3a8b0e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/access.mdx @@ -0,0 +1,54 @@ +--- +page_title: Manage access to workspaces in Terraform Enterprise +description: >- + Learn how to manage access to workspaces by adding teams and configuring their + permissions. +source: terraform-docs-common +--- + +# Manage access to workspaces + + + +@include 'tfc-package-callouts/team-management.mdx' + + + +HCP Terraform workspaces can only be accessed by users with the correct permissions. You can manage permissions for a workspace on a per-team basis. + +Teams with [admin access](/terraform/enterprise/users-teams-organizations/permissions) on a workspace can manage permissions for other teams on that workspace. Since newly created workspaces don't have any team permissions configured, the initial setup of a workspace's permissions requires the owners team or a team with permission to manage workspaces. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **API:** See the [Team Access APIs](/terraform/enterprise/api-docs/team-access).
+**Terraform:** See the `tfe` provider's [`tfe_team_access`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/team_access) resource. + +## Background + +HCP Terraform manages users' permissions to workspaces with teams. + +- [Workspace-level permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-permissions) can be granted to an individual team on a particular workspace. These permissions can be managed on the workspace by anyone with admin access to the workspace. +- In addition, some [organization-level permissions](/terraform/enterprise/users-teams-organizations/permissions#organization-permissions) can be granted to a team which apply to every workspace in the organization. For example, the + [manage all workspaces](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces) and [manage all projects](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects) permissions grant the workspace-level admin permission to every workspace in the organization. Organization-level permissions can only be managed by organization owners. + +## Managing Workspace Access Permissions + +When a user creates a workspace, the following teams can access that workspace with full admin permissions: + +- [the owners team](/terraform/enterprise/users-teams-organizations/teams#the-owners-team) +- teams with "Manage all workspaces" and/or “Manage all projects” [organization permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) +- teams with “Project Admin” project permissions + +You cannot override these teams' permissions through the workspace's specific permissions. + +To manage a team's access to a workspace, select "Team Access" from the workspace's "Settings" menu. + +This screen displays all teams granted workspace-level permissions to the workspace. To add a team, select "Add team and permissions". + +HCP Terraform displays the teams you can grant workspace access to. Select a team to continue and configure that team's permissions. + +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. + +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/v000011-1/docs/enterprise/workspaces/settings/deletion.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/deletion.mdx new file mode 100644 index 0000000000..4daa48e161 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/deletion.mdx @@ -0,0 +1,125 @@ +--- +page_title: Destroy infrastructure resources and delete workspaces in Terraform Enterprise +description: >- + Learn how to clean up resources by destroying a workspace's infrastructure and + deleting a workspace in Terraform Enterprise. +source: terraform-docs-common +--- + +# Destroy infrastructure resources and delete workspaces + +HCP Terraform workspaces have two primary delete actions: + +- [Destroying infrastructure](#destroy-infrastructure) deletes resources managed by the HCP Terraform workspace by triggering a destroy run. +- [Deleting a workspace](#delete-workspaces) deletes the workspace itself without triggering a destroy run. + +In general, you should perform both actions in the above order when destroying a workspace to ensure resource cleanup for all of a workspace's managed infrastructure. + +## Destroy Infrastructure + +Destroy plans delete the infrastructure managed by a workspace. We recommend destroying the infrastructure managed by a workspace _before_ deleting the workspace itself. Otherwise, the unmanaged infrastructure resources will continue to exist but will become unmanaged, and you must go into your infrastructure providers to delete the resources manually. + +Before queuing a destroy plan, enable the **Allow destroy plans** toggle setting on this page. + +### Automatically Destroy + + + +@include 'tfc-package-callouts/ephemeral-workspaces.mdx' + + + +Configuring automatic infrastructure destruction for a workspace requires [admin permissions](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) for that workspace. + +There are two main ways to automatically destroy a workspace's resources: + +- Schedule a run to destroy all resources in a workspace at a specific date and time. +- Configure HCP Terraform to destroy a workspace's infrastructure after a period of workspace inactivity. + +Workspaces can inherit auto-destroy settings from their project. Refer to [managing projects](/terraform/enterprise/projects/manage#automatically-destroy-inactive-workspaces) for more information. You can configure an individual workspace's auto-destroy settings to override the project's configuration. + +You can reduce your spending on infrastructure by automatically destroying temporary resources like development environments. + +After HCP Terraform performs an auto-destroy run, it unsets the `auto-destroy-at` field on the workspace. If you continue using the workspace, you can schedule another future auto-destroy run to remove any new resources. + +!> **Note:** Automatic destroy plans _do not_ prompt you for apply approval in the HCP Terraform user interface. We recommend only using this setting for development environments. + +You can schedule an auto-destroy run using the HCP Terraform web user interface, or the [workspace API](/terraform/enterprise/api-docs/workspaces). + +You can also schedule [notifications](/terraform/enterprise/workspaces/settings/notifications) to alert you 12 and 24 hours before an auto-destroy run, and to report auto-destroy run results. + +#### Destroy at a specific day and time + +To schedule an auto-destroy run at a specific time in HCP Terraform: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to destroy. +2. Choose **Settings** from the sidebar, then **Destruction and Deletion**. +3. Under **Automatically destroy**, click **Set up auto-destroy**. +4. Enter the desired date and time. HCP Terraform defaults to your local time zone for scheduling and displays how long until the scheduled operation. +5. Click **Confirm auto-destroy**. + +To cancel a scheduled auto-destroy run in HCP Terraform: + +1. Navigate to the workspace's **Settings** > **Destruction and Deletion** page. +2. Under **Automatically destroy**, click **Edit** next to your scheduled run's details. +3. Click **Remove**. + +#### Destroy if a workspace is inactive + +You can configure HCP Terraform to automatically destroy a workspace's infrastructure after a period of inactivity. +A workspace is _inactive_ if the workspace's state has not changed within your designated time period. + +!> **Caution:** As opposed to configuring an auto-destroy run for a specific date and time, this setting _persists_ after queueing auto-destroy runs. + +If you configure a workspace to auto-destroy its infrastructure when inactive, any run that updates Terraform state further delays the scheduled auto-destroy time by the length of your designated timeframe. + +To schedule an auto-destroy run after a period of workspace inactivity: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to destroy. +2. Choose **Settings** from the sidebar, then **Destruction and Deletion**. +3. Under **Automatically destroy**, click **Set up auto-destroy**. +4. Click the **Destroy if inactive** toggle. +5. Select or customize a desired timeframe of inactivity. +6. Click **Confirm auto-destroy**. + +When configured for the first time, the auto-destroy duration setting displays the scheduled date and time that HCP Terraform will perform the auto-destroy run. +Subsequent auto-destroy runs and Terraform runs that update state both update the next scheduled auto-destroy date. + +After HCP Terraform completes a manual or automatic destroy run, it waits until further state updates to schedule a new auto-destroy run. + +To remove your workspace's auto-destroy run: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to disable the auto-destroy run for. +2. Choose **Settings** from the sidebar, then **Destruction and Deletion**. +3. Under **Auto-destroy settings**, click **Edit** to change the auto-destroy settings. +4. Click **Remove**. + +When you move a workspace to a different project, it inherits the auto-destroy settings from the new project. If you configured the workspace to override the previous project's auto-destroy settings, it retains the override configuration in the new project. + +## Delete Workspace + +Terraform does not automatically destroy managed infrastructure when you delete a workspace. + +After you delete the workspace and its state file, Terraform can _no longer track or manage_ that infrastructure. You must manually delete or [import](/terraform/cli/commands/import) any remaining resources into another Terraform workspace. + +By default, [workspace administrators](/terraform/enterprise/users-teams-organizations/permissions#workspace-admins) can only delete unlocked workspaces that are not managing any infrastructure. Organization owners can force delete a workspace to override these protections. Organization owners can also configure the [organization's settings](/terraform/enterprise/users-teams-organizations/organizations#general) to let workspace administrators force delete their own workspaces. + +## Data Retention Policies + + +Data retention policies are exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise. + + +Define configurable data retention policies for workspaces to help reduce object storage consumption. You can define a policy that allows Terraform to _soft delete_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can automatically delete the object after a set number of days. + +Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection grace period elapses, you can still restore an object using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and [state version documentation](/terraform/enterprise/api-docs/state-versions). After the garbage collection grace period elapses, Terraform permanently deletes the archivist storage. + +The [organization policy](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) is the default policy applied to workspaces, but members of individual workspaces can override the policy for their workspaces. + +The workspace policy always overrides the organization policy. A workspace admin can set or override the following data retention policies: + +- **Organization default policy** +- **Do not auto-delete** +- **Auto-delete data** + +Setting the data retention policy to **Organization default policy** disables the other data retention policy settings. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/index.mdx new file mode 100644 index 0000000000..0dc4c0ab9c --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/index.mdx @@ -0,0 +1,213 @@ +--- +page_title: Workspaces settings in Terraform Enterprise +description: >- + Learn how to configure workspace settings for notifications, permissions, + health, locking, policies, run triggers, SSH keys, team access, version + control, and deletion. +source: terraform-docs-common +--- + +# Workspace settings + +You can change a workspace’s settings after creation. Workspace settings are separated into several pages. + +- [General](#general): Settings that determine how the workspace functions, including its name, description, associated project, Terraform version, and execution mode. +- [Health](/terraform/enterprise/workspaces/health): Settings that let you configure health assessments, including drift detection and continuous validation. +- [Locking](#locking): Locking a workspace temporarily prevents new plans and applies. +- [Notifications](#notifications): Settings that let you configure run notifications. +- [Policies](#policies): Settings that let you toggle between Sentinel policy evaluation experiences. +- [Run Triggers](#run-triggers): Settings that let you configure run triggers. Run triggers allow runs to queue automatically in your workspace when runs in other workspaces are successful. +- [SSH Key](#ssh-key): Set a private SSH key for downloading Terraform modules from Git-based module sources. +- [Team Access](#team-access): Settings that let you manage which teams can view the workspace and use it to provision infrastructure. +- [Version Control](#version-control): Manage the workspace’s VCS integration. +- [Destruction and Deletion](#destruction-and-deletion): Remove a workspace and the infrastructure it manages. + +Changing settings requires admin access to the relevant workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **API:** See the [Update a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#update-a-workspace) (`PATCH /organizations/:organization_name/workspaces/:name`). + +## General + +General settings let you change a workspace's name, description, the project it belongs to, and details about how Terraform runs operate. After changing these settings, click **Save settings** at the bottom of the page. + +### ID + +Every workspace has a unique ID that you cannot change. You may need to reference the workspace's ID when using the [HCP Terraform API](/terraform/enterprise/api-docs). + +Click the icon beside the ID to copy it to your clipboard. + +### Name + +The display name of the workspace. + +!> **Warning:** Some API calls refer to a workspace by its name, so changing the name may break existing integrations. + +### Project + +The [project](/terraform/enterprise/projects) that this workspace belongs to. Changing the workspace's project can change the read and write permissions for the workspace and which users can access it. + +To move a workspace, you must have the "Manage all Projects" organization permission or explicit team admin privileges on both the source and destination projects. Remember that moving a workspace to another project may affect user visibility for that project's workspaces. Refer to [Project Permissions](/terraform/enterprise/users-teams-organizations/permissions#project-permissions) for details on workspace access. + +### Description (Optional) + +Enter a brief description of the workspace's purpose or types of infrastructure. + +### Execution Mode + +Whether to use HCP Terraform as the Terraform execution platform for this workspace. + +By default, HCP Terraform uses an organization's [default execution mode](/terraform/enterprise/users-teams-organizations/organizations#organization-settings) to choose the execution platform for a workspace. Alternatively, you can instead choose a custom execution mode for a workspace. + +Specifying the "Remote" execution mode instructs HCP Terraform to perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more. + +To disable remote execution for a workspace, change its execution mode to "Local". This mode lets you perform Terraform runs locally with the [CLI-driven run workflow](/terraform/enterprise/run/cli). The workspace will store state, which Terraform can access with the [CLI integration](/terraform/cli/cloud). HCP Terraform does not evaluate workspace variables or variable sets in local execution mode. + +If you instead need to allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure, consider using [HCP Terraform agents](/terraform/cloud-docs/agents). By deploying a lightweight agent, you can establish a simple connection between your environment and HCP Terraform. + +Changing your workspace's execution mode after a run has already been planned will cause the run to error when it is applied. + +To minimize the number of runs that error when changing your workspace's execution mode, you should: + +1. Disable [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply) if you have it enabled. +2. Complete any runs that are no longer in the [pending stage](/terraform/enterprise/run/states#the-pending-stage). +3. [Lock](/terraform/enterprise/workspaces/settings#locking) your workspace to prevent any new runs. +4. Change the execution mode. +5. Enable [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply), if you had it enabled before changing your execution mode. +6. [Unlock](/terraform/enterprise/workspaces/settings#locking) your workspace. + + + + +### Auto-apply + +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, 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 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 + +### Terraform Version + +The Terraform version to use for all operations in the workspace. The default value is whichever release was current when HCP Terraform created the workspace. You can also update a workspace's Terraform version to an exact version or a valid [version constraint](/terraform/language/expressions/version-constraints). + +> **Hands-on:** Try the [Upgrade Terraform Version in HCP Terraform](/terraform/tutorials/cloud/cloud-versions) tutorial. + +-> **API:** You can specify a Terraform version when you [create a workspace](/terraform/enterprise/api-docs/workspaces#create-a-workspace) with the API. + +### Terraform Working Directory + +The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. Defaults to the root of the configuration directory. + +HCP Terraform will change to this directory before starting a Terraform run, and will report an error if the directory does not exist. + +Setting a working directory creates a default filter for automatic run triggering, and sometimes causes CLI-driven runs to upload additional configuration content. + +#### Default Run Trigger Filtering + +In VCS-backed workspaces that specify a working directory, HCP Terraform assumes that only changes within that working directory should trigger a run. You can override this behavior with the [Automatic Run Triggering](/terraform/enterprise/workspaces/settings/vcs#automatic-run-triggering) settings. + +#### Parent Directory Uploads + +If a working directory is configured, HCP Terraform always expects the complete shared configuration directory to be available, since the configuration might use local modules from outside its working directory. + +In [runs triggered by VCS commits](/terraform/enterprise/run/ui), this is automatic. In [CLI-driven runs](/terraform/enterprise/run/cli), Terraform's CLI sometimes uploads additional content: + +- When the local working directory _does not match_ the name of the configured working directory, Terraform assumes it is the root of the configuration directory, and uploads only the local working directory. +- When the local working directory _matches_ the name of the configured working directory, Terraform uploads one or more parents of the local working directory, according to the depth of the configured working directory. (For example, a working directory of `production` is only one level deep, so Terraform would upload the immediate parent directory. `consul/production` is two levels deep, so Terraform would upload the parent and grandparent directories.) + +If you use the working directory setting, always run Terraform from a complete copy of the configuration directory. Moving one subdirectory to a new location can result in unexpected content uploads. + +### Remote State Sharing + +Which other workspaces within the organization can access the state of the workspace during [runs managed by HCP Terraform](/terraform/enterprise/run/remote-operations#remote-operations). The [`terraform_remote_state` data source](/terraform/language/state/remote-state-data) relies on state sharing to access workspace outputs. + +- If "Share state globally" is enabled, all other workspaces within the organization can access this workspace's state during runs. +- If global sharing is turned off, you can specify a list of workspaces within the organization that can access this workspace's state; no other workspaces will be allowed. + + The workspace selector is searchable; if you don't initially see a workspace you're looking for, type part of its name. + +By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other. To configure remote state sharing, a user must have read access for the destination workspace. If a user does not have access to the destination workspace due to scoped project or workspace permissions, they will not have complete visibility into the list of other workspace that can access its state. + +-> **Note:** The default access permissions for new workspaces in HCP Terraform changed in April 2021. Workspaces created before this change default to allowing global access within their organization. These workspaces can be changed to more restrictive access at any time. Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access. + +### User Interface + +Select the user experience for displaying plan and apply details. + +The default experience is _Structured Run Output_, which displays your plan and apply results in a human-readable format. This includes nodes that you can expand to view details about each resource and any configured output. + +The Console UI experience is the traditional Terraform experience, where live text logging is streamed in real time to the UI. This experience most closely emulates the CLI output. + +~> **Note:** Your workspace must be configured to use a Terraform version of 1.0.5 or higher for the Structured Run Output experience to be fully supported. Workspaces running versions from 0.15.2 may see partial functionality. Workspaces running versions below 0.15.2 will default to the "Console UI" experience regardless of the User Interface setting. + +## Locking + +~> **Important:** Unlike other settings, locks can also be managed by users with permission to lock and unlock the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +If you need to prevent Terraform runs for any reason, you can lock a workspace. This prevents all applies (and many kinds of plans) from proceeding, and affects runs created via UI, CLI, API, and automated systems. To enable runs again, a user must unlock the workspace. + +Two kinds of run operations can ignore workspace locking because they cannot affect resources or state and do not attempt to lock the workspace themselves: + +- Plan-only runs. +- The planning stages of [saved plan runs](/terraform/enterprise/run/modes-and-options.mdx#saved-plans). You can only _apply_ a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow. + +Locking a workspace also restricts state uploads. In order to upload state, the workspace must be locked by the user who is uploading state. + +Users with permission to lock and unlock a workspace can't unlock a workspace which was locked by another user. Users with admin access to a workspace can force unlock a workspace even if another user has locked it. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Locks are managed with a single "Lock/Unlock/Force unlock ``" button. HCP Terraform asks for confirmation when unlocking. + +You can also manage the workspace's lock from the **Actions** menu. + +## Notifications + +The "Notifications" page allows HCP Terraform to send webhooks to external services whenever specific run events occur in a workspace. + +See [Run Notifications](/terraform/enterprise/workspaces/settings/notifications) for detailed information about configuring notifications. + +## Policies + +HCP Terraform offers two experiences for Sentinel policy evaluations. On the "Policies" page, you can adjust your **Sentinel Experience** settings to your preferred experience. By default, HCP Terraform enables the newest policy evaluation experience. + +To toggle between the two Sentinel policy evaluation experiences, click the **Enable the new Sentinel policy experience** toggle under the **Sentinel Experience** heading. HCP Terraform persists your changes automatically. If HCP Terraform is performing a run on a different page, you must refresh that page to see changes to your policy evaluation experience. + +## Run Triggers + +The "Run Triggers" page configures connections between a workspace and one or more source workspaces. These connections, called "run triggers", allow runs to queue automatically in a workspace on successful apply of runs in any of the source workspaces. + +See [Run Triggers](/terraform/enterprise/workspaces/settings/run-triggers) for detailed information about configuring run triggers. + +## SSH Key + +If a workspace's configuration uses [Git-based module sources](/terraform/language/modules/sources) to reference Terraform modules in private Git repositories, Terraform needs an SSH key to clone those repositories. The "SSH Key" page lets you choose which key it should use. + +See [Using SSH Keys for Cloning Modules](/terraform/enterprise/workspaces/settings/ssh-keys) for detailed information about this page. + +## Team Access + +The "Team Access" page configures which teams can perform which actions on a workspace. + +See [Managing Access to Workspaces](/terraform/enterprise/workspaces/settings/access) for detailed information. + +## Version Control + +The "Version Control" page configures an optional VCS repository that contains the workspace's Terraform configuration. Version control integration is only relevant for workspaces with [remote execution](#execution-mode) enabled. + +See [VCS Connections](/terraform/enterprise/workspaces/settings/vcs) for detailed information about this page. + +## Destruction and Deletion + +The **Destruction and Deletion** page allows [admin users](/terraform/enterprise/users-teams-organizations/permissions) to delete a workspace's managed infrastructure or delete the workspace itself. + +For details, refer to [Destruction and Deletion](/terraform/enterprise/workspaces/settings/deletion) for detailed information about this page. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/notifications.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/notifications.mdx new file mode 100644 index 0000000000..2c9b97b15e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/notifications.mdx @@ -0,0 +1,130 @@ +--- +page_title: Workspace notifications in Terraform Enterprise +description: >- + Use webhooks to notify external systems about run progress and other events in + Terraform Enterprise. Learn to create and enable workspace notifications. +source: terraform-docs-common +--- + +# Workspace notifications + +HCP Terraform can use webhooks to notify external systems about run progress and other events. Each workspace has its own notification settings and can notify up to 20 destinations. + +-> **Note:** [Speculative plans](/terraform/enterprise/run/modes-and-options#plan-only-speculative-plan) and workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode) do not support notifications. + +Configuring notifications requires admin access to the workspace. Refer to [Permissions](/terraform/enterprise/users-teams-organizations/permissions) for details. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +-> **API:** Refer to [Notification Configuration APIs](/terraform/enterprise/api-docs/notification-configurations). + +## Viewing and Managing Notification Settings + +To add, edit, or delete notifications for a workspace, go to the workspace and click **Settings > Notifications**. The **Notifications** page appears, showing existing notification configurations. + +## Creating a Notification Configuration + +A notification configuration specifies a destination URL, a payload type, and the events that should generate a notification. To create a notification configuration: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select the workspace you want to configure notifications for. + +2. Click **Settings**, then **Notifications**. + +3. Click **Create a Notification**. The **Create a Notification** form appears. + +4. Configure the notifications: + +- **Destination:** HCP Terraform can deliver either a generic payload or a payload formatted specifically for Slack, Microsoft Teams, or Email. Refer to [Notification Payloads](#notification-payloads) for details. + +- **Name:** A display name for this notification configuration. + +- **Webhook URL** This URL is only available for generic, Slack, and Microsoft Teams webhooks. The webhook URL is the destination for the webhook payload. This URL must accept HTTP or HTTPS `POST` requests and should be able to use the chosen payload type. For details, refer to Slack's documentation on [creating an incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook) and Microsoft's documentation on [creating a workflow from a channel in teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e). + +- **Token** (Optional) This notification is only available for generic webhooks. A token is an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to [Notification Authenticity][inpage-hmac] for details. You cannot view the token after you save the notification configuration. + +- **Email Recipients** This notification is only available for emails. Select users that should receive notifications. + +- **Workspace Events**: HCP Terraform can send notifications for all events or only for specific events. The following events are available: + + - **Drift**: HCP Terraform detected configuration drift. This notification is only available if you enable [health assessments](/terraform/enterprise/workspaces/health) for the workspace. + - **Check Failure:** HCP Terraform detected one or more failed continuous validation checks. This notification is only available if you enable health assessments for the workspace. + - **Health Assessment Fail**: A health assessment failed. This notification is only available if you enable health assessments for the workspace. Health assessments fail when HCP Terraform cannot perform drift detection, continuous validation, or both. The notification does not specify the cause of the failure, but you can use the [Assessment Result](/terraform/enterprise/api-docs/assessment-results) logs to help diagnose the issue. + - **Auto destroy reminder**: Sends reminders 12 and 24 hours before a scheduled auto destroy run. + - **Auto destroy results**: HCP Terraform performed an auto destroy run in the workspace. Reports both successful and errored runs. + + + +@include 'tfc-package-callouts/health-assessments.mdx' + + + +- **Run Events:** HCP Terraform can send notifications for all events or only for specific events. The following events are available: + - **Created**: A run begins and enters the [Pending stage](/terraform/enterprise/run/states#the-pending-stage). + - **Planning**: A run acquires the lock and starts to execute. + - **Needs Attention**: A plan has changes and Terraform requires user input to continue. This event may include approving the plan or a [policy override](/terraform/enterprise/run/states#the-policy-check-stage). + - **Applying**: A run enters the [Apply stage](/terraform/enterprise/run/states#the-apply-stage), where Terraform makes the infrastructure changes described in the plan. + - **Completed**: A run completed successfully. + - **Errored**: A run terminated early due to error or cancellation. + +4. Click **Create a notification**. + +## Enabling and Verifying a Configuration + +To enable or disable a configuration, toggle the **Enabled/Disabled** switch on its detail page. HCP Terraform will attempt to verify the configuration for generic and slack webhooks by sending a test message, and will enable the notification configuration if the test succeeds. + +For a verification to be successful, the destination must respond with a `2xx` HTTP code. If verification fails, HCP Terraform displays the error message and the configuration will remain disabled. + +For both successful and unsuccessful verifications, click the **Last Response** box to view more information about the verification results. You can also send additional test messages with the **Send a Test** link. + +## Notification Payloads + +### Slack + +Notifications to Slack will contain the following information: + +- The run's workspace (as a link) +- The HCP Terraform username and avatar of the person that created the run +- The run ID (as a link) +- The reason the run was queued (usually a commit message or a custom message) +- The time the run was created +- The event that triggered the notification and the time that event occurred + +### Microsoft Teams + +Notifications to Microsoft Teams contain the following information: + +- The run's workspace (as a link) +- The HCP Terraform username and avatar of the person that created the run +- The run ID +- A link to view the run +- The reason the run was queued (usually a commit message or a custom message) +- The time the run was created +- The event that triggered the notification and the time that event occurred + +### Email + +Email notifications will contain the following information: + +- The run's workspace (as a link) +- The run ID (as a link) +- The event that triggered the notification, and if the run needs to be acted upon or not + +### Generic + +A generic notification will contain information about a run and its state at the time the triggering event occurred. The complete generic notification payload is described in the [API documentation][generic-payload]. + +[generic-payload]: /terraform/enterprise/api-docs/notification-configurations#notification-payload + +Some of the values in the payload can be used to retrieve additional information through the API, such as: + +- The [run ID](/terraform/enterprise/api-docs/run#get-run-details) +- The [workspace ID](/terraform/enterprise/api-docs/workspaces#list-workspaces) +- The [organization name](/terraform/enterprise/api-docs/organizations#show-an-organization) + +## Notification Authenticity + +[inpage-hmac]: #notification-authenticity + +Slack notifications use Slack's own protocols for verifying HCP Terraform's webhook requests. + +Generic notifications can include a signature for verifying the request. For notification configurations that include a secret token, HCP Terraform's webhook requests will include an `X-TFE-Notification-Signature` header, which contains an HMAC signature computed from the token using the SHA-512 digest algorithm. The receiving service is responsible for validating the signature. More information, as well as an example of how to validate the signature, can be found in the [API documentation](/terraform/enterprise/api-docs/notification-configurations#notification-authenticity). diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/run-tasks.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/run-tasks.mdx new file mode 100644 index 0000000000..baab7caf6e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/run-tasks.mdx @@ -0,0 +1,134 @@ +--- +page_title: Terraform Enterprise run tasks +description: >- + Run tasks integrate third-party tools into the run lifecycle. Learn how to + create, delete, and associate run tasks with workspaces. +source: terraform-docs-common +--- + +[entitlement]: /terraform/enterprise/api-docs#feature-entitlements + +# Run tasks + +HCP Terraform run tasks let you directly integrate third-party tools and services at certain stages in the HCP Terraform run lifecycle. Use run tasks to validate Terraform configuration files, analyze execution plans before applying them, scan for security vulnerabilities, or perform other custom actions. + +Run tasks send data about a run to an external service at [specific run stages](#understanding-run-tasks-within-a-run). The external service processes the data, evaluates whether the run passes or fails, and sends a response to HCP Terraform. HCP Terraform then uses this response and the run task enforcement level to determine if a run can proceed. [Explore run tasks in the Terraform registry](https://registry.terraform.io/browse/run-tasks). + + + +@include 'tfc-package-callouts/run-tasks.mdx' + + + +You can manage run tasks through the HCP Terraform UI or the [Run Tasks API](/terraform/enterprise/api-docs/run-tasks/run-tasks). + +> **Hands-on:** Try the [HCP Packer validation run task](/packer/tutorials/hcp/setup-hcp-terraform-run-task) tutorial. + +## Requirements + +**Terraform Version** - You can assign run tasks to workspaces that use a Terraform version of 1.1.9 and later. You can downgrade a workspace with existing runs to use a prior Terraform version without causing an error. However, HCP Terraform no longer triggers the run tasks during plan and apply operations. + +**Permissions** - To create a run task, you must have a user account with the [Manage Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#manage-run-tasks). To associate run tasks with a workspace, you need the [Manage Workspace Run Tasks permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) on that particular workspace. + +## Creating a Run Task + +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. + +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. + +To create a new run task: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace where you want to create a run task. + +2. Choose **Settings** from the sidebar, then **Run Tasks**. + +3. Click **Create a new run task**. The **Run Tasks** page appears. + +4. Enter the information about the run task to be configured: + + - **Enabled** (optional): Whether the run task will run across all associated workspaces. New tasks are enabled by default. + - **Name** (required): A human-readable name for the run task. This will be displayed in workspace configuration pages and can contain letters, numbers, dashes and underscores. + - **Endpoint URL** (required): The URL for the external service. Run tasks will POST the [run tasks payload](/terraform/enterprise/integrations/run-tasks#integration-details) to this URL. + - **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. 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 + +When you create a new run task, you can choose to apply it globally to every workspace in an organization. Your organization must have the `global-run-task` [entitlement][] to use global run tasks. + +1. Select the **Global** checkbox + +2. Choose when HCP Terraform should start the run task: + + - **Pre-plan**: Before Terraform creates the plan. + - **Post-plan**: After Terraform creates the plan. + - **Pre-apply**: Before Terraform applies a plan. + - **Post-apply**: After Terraform applies a plan. + +3. Choose an enforcement level: + + - **Advisory**: Run tasks can not block a run from completing. If the task fails, the run proceeds with a warning in the user interface. + - **Mandatory**: Failed run tasks can block a run from completing. If the task fails (including timeouts or unexpected remote errors), the run stops and errors with a warning in the user interface. + +## Associating Run Tasks with a Workspace + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise, and choose **Workspaces** from the sidebar. + +2. Select the workspace that you want to associate with a run task. + +3. Open the **Settings** menu and select **Run Tasks**. + +4. Click the **+** next to the task you want to add to the workspace. + +5. Choose when HCP Terraform should start the run task: + + - **Pre-plan**: Before Terraform creates the plan. + - **Post-plan**: After Terraform creates the plan. + - **Pre-apply**: Before Terraform applies a plan. + - **Post-apply**: After Terraform applies a plan. + +6. Choose an enforcement level: + + - **Advisory**: Run tasks can not block a run from completing. If the task fails, the run will proceed with a warning in the UI. + - **Mandatory**: Run tasks can block a run from completing. If the task fails (including a timeout or unexpected remote error condition), the run will transition to an Errored state with a warning in the UI. + +7. Click **Create**. Your run task is now configured. + +## Understanding Run Tasks Within a Run + +Run tasks perform actions before and after, the [plan](/terraform/enterprise/run/states#the-plan-stage) and [apply](/terraform/enterprise/run/states#the-apply-stage) stages of a [Terraform run](/terraform/enterprise/run/remote-operations). Once all run tasks complete, the run ends based on the most restrictive enforcement level in each associated run task. + +For example, if a mandatory task fails and an advisory task succeeds, the run fails. If an advisory task fails, but a mandatory task succeeds, the run succeeds and proceeds to the apply stage. Regardless of the exit status of a task, HCP Terraform displays the status and any related message data in the UI. + +## Removing a Run Task from a Workspace + +Removing a run task from a workspace does not delete it from the organization. To remove a run task from a specific workspace: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace where you want to remove a run task. + +2. Choose **Settings** from the sidebar, then **Run Tasks**. + +3. Click the ellipses (...) on the associated run task, and then click **Remove**. The run task will no longer be applied to runs within the workspace. + +## Deleting a Run Task + +You must remove a run task from all associated workspaces before you can delete it. To delete a run task: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace associated with a run task you want to delete. + +2. Choose **Settings** from the sidebar, then **Run Tasks**. + +3. Click the ellipses (...) next to the run task you want to delete, and then click **Edit**. + +4. Click **Delete run task**. + +You cannot delete run tasks that are still associated with a workspace. If you attempt this, you will see a warning in the UI containing a list of all workspaces that are associated with the run task. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/run-triggers.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/run-triggers.mdx new file mode 100644 index 0000000000..13bda16de0 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/run-triggers.mdx @@ -0,0 +1,51 @@ +--- +page_title: Terraform Enterprise run triggers +description: >- + Use run triggers to connect workspaces within your organization. Learn how to + view, create, and manage run triggers. +source: terraform-docs-common +--- + +# Run triggers + +> **Hands-on:** Try the [Connect Workspaces with Run Triggers](/terraform/tutorials/cloud/cloud-run-triggers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. + +HCP Terraform provides a way to connect your workspace to one or more workspaces within your organization, known as "source workspaces". These connections, called run triggers, allow runs to queue automatically in your workspace on successful apply of runs in any of the source workspaces. You can connect each workspace to up to 20 source workspaces. + +Run triggers are designed for workspaces that rely on information or infrastructure produced by other workspaces. If a Terraform configuration uses [data sources](/terraform/language/data-sources) to read values that might be changed by another workspace, run triggers let you explicitly specify that external dependency. + +-> **API:** See the [Run Triggers APIs](/terraform/enterprise/api-docs/run-triggers). + +## Viewing and Managing Run Triggers + +To add or delete a run trigger, navigate to the desired workspace and choose "Run Triggers" from the "Settings" menu: + +This takes you to the run triggers settings page, which shows any existing run triggers. Configuring run triggers requires admin access to the workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) Admins are able to delete any of their workspace’s run triggers from this page. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Creating a Run Trigger + +Creating run triggers requires admin access to the workspace. You must also have permission to read runs for the source workspace you wish to connect to. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +Under the "Source Workspaces" section, select the workspace you would like to connect as your source and click "Add workspace". You now have a run trigger established with your source workspace. Any run from that source workspace which applies successfully will now cause a new run to be queued in your workspace. + +## Run Triggers Auto-Apply Setting + +Runs initiated by a run trigger do not auto-apply unless you enable the **Auto-apply run triggers** setting. This setting operates independently of the primary workspace [auto-apply](/terraform/enterprise/workspaces/settings#auto-apply) setting. + +## Interacting with Run Triggers + +Runs which are queued in your workspace through a run trigger will include extra information in their run details section. This includes links to the source workspace and the successfully applied run that activated the run trigger. + +The source workspace includes a message in the [plan](/terraform/docs/glossary#plan-noun-1-) and [apply](/terraform/docs/glossary#apply-noun-) run details that specifies the workspaces where HCP Terraform automatically starts a run. + +## Using a Remote State Data Source + +A common way to share information between workspaces is the [`terraform_remote_state` data source](/terraform/language/state/remote-state-data), which allows a Terraform configuration to access a source workspace's root-level [outputs](/terraform/language/values/outputs). + +Before other workspaces can read the outputs of a workspace, it must be configured to allow access. For more information about cross-workspace state access in HCP Terraform, see [Terraform State in HCP Terraform](/terraform/enterprise/workspaces/state). + +~> **Important:** We recommend using the [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) in the [HCP Terraform/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) to access remote state outputs in HCP Terraform or Terraform Enterprise. The `tfe_outputs` data source is more secure because it does not require full access to workspace state to fetch outputs. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/ssh-keys.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/ssh-keys.mdx new file mode 100644 index 0000000000..d2a9fde19e --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/ssh-keys.mdx @@ -0,0 +1,63 @@ +--- +page_title: Use SSH Keys to clone modules in Terraform Enterprise +description: >- + Learn how to configure the SSH keys that Terraform uses to pull modules from + private Git repositories. Learn to add, delete, and assign keys to workspaces. +source: terraform-docs-common +--- + +# Use SSH Keys for cloning modules + +Terraform configurations can pull in Terraform modules from [a variety of different sources](/terraform/language/modules/sources), and private Git repositories are a common source for private modules. + +-> **Note:** The [private module registry](/terraform/enterprise/registry) is an easier way to manage private Terraform modules in HCP Terraform, and doesn't require setting SSH keys for workspaces. The rest of this page only applies to configurations that fetch modules directly from a private Git repository. + +To access a private Git repository, Terraform either needs login credentials (for HTTPS access) or an SSH key. HCP Terraform can store private SSH keys centrally, and you can easily use them in any workspace that clones modules from a Git server. + +-> **Note:** SSH keys for cloning Terraform modules from Git repos are only used during Terraform runs. They are managed separately from any [keys used for bringing VCS content into HCP Terraform](/terraform/enterprise/vcs#ssh-keys). + +HCP Terraform manages SSH keys used to clone Terraform modules at the organization level, and allows multiple keys to be added for the organization. You can add or delete keys via the organization's settings. Once a key is uploaded, the text of the key is not displayed to users. + +To assign a key to a workspace, go to its settings and choose a previously added key from the drop-down menu on Integrations under "SSH Key". Each workspace can only use one SSH key. + +-> **API:** See the [SSH Keys API](/terraform/enterprise/api-docs/ssh-keys) and [Assign an SSH Key to a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#assign-an-ssh-key-to-a-workspace).
+**Terraform:** See the `tfe` provider's [`tfe_ssh_key`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/ssh_key) resource. + +## Adding Keys + +To add a key: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and choose the organization you want to add a key to. +2. Choose **Settings** from the sidebar, then **SSH Keys**. This page has a form for adding new keys and a list of existing keys. +3. Obtain a PEM formatted SSH keypair that HCP Terraform can use to download modules during a Terraform run. You might already have an appropriate key. If not, create one on a secure workstation and distribute the public key to your VCS provider(s). Do not use or generate a key that has a passphrase. Git is running non-interactively and cannot prompt for it. + + The exact command to create a PEM formatted SSH keypair depends on your operating system. The following example command creates a `service_terraform` file with the private key and a `service_terraform.pub` file with the public key. + + ```bash + ssh-keygen -t rsa -m PEM -f "/Users//.ssh/service_terraform" -C "service_terraform_enterprise" + ``` +4. Enter a name for the key in the **Name** field. Choose something identifiable. Keys are only listed by name. HCP Terraform retains the text of each private key, but never displays it for any purpose. +5. Paste the text of the private key in the **Private SSH Key** field. +6. Click **Add Private SSH Key**. + +The new key appears in the list of keys on the page. + +If you upload an invalid SSH key, upload the correct key and push a new commit for the new key to take effect. + +## Deleting Keys + +Before deleting a key, you should assign a new key to any workspaces that are using it. Otherwise workspaces using the deleted key can no longer clone modules from private repositories. This inability might cause Terraform runs to fail. + +To delete a key: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and choose the organization you want to delete a key from. +2. Choose **Settings** from the sidebar, then **SSH Keys**. +3. Find the key you want to delete and click **Delete**. + +## Assigning Keys to Workspaces + +To assign a key to a workspace, navigate to that workspace's page and choose "SSH Key" from the "Settings" menu. + +Select a named key from the "SSH Key" dropdown menu, then click the "Update SSH key" button. + +In subsequent runs, HCP Terraform will use the selected SSH key in this workspace when cloning modules from Git. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/vcs.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/vcs.mdx new file mode 100644 index 0000000000..a1e34e5a58 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/settings/vcs.mdx @@ -0,0 +1,127 @@ +--- +page_title: Configure workspace VCS connections in Terraform Enterprise +description: >- + Learn how to use the Terraform Enterprise UI to connect a workspace to a + version control system (VCS) repository that contains a Terraform + configuration. +source: terraform-docs-common +--- + +# Configure workspace VCS connections + +You can connect any HCP Terraform [workspace](/terraform/enterprise/workspaces) to a version control system (VCS) repository that contains a Terraform configuration. This page explains the workspace VCS connection settings in the HCP Terraform UI. + +Refer to [Terraform Configurations in HCP Terraform Workspaces](/terraform/enterprise/workspaces/configurations) for details on handling configuration versions and connected repositories. Refer to [Connecting VCS Providers](/terraform/enterprise/vcs) for a list of supported VCS providers and details about configuring VCS access, viewing VCS events, etc. + +## API + +You can use the [Update a Workspace endpoint](/terraform/enterprise/api-docs/workspaces#update-a-workspace) in the Workspaces API to change one or more VCS settings. We also recommend using this endpoint to automate changing VCS connections for many workspaces at once. For example, when you move a VCS server or remove a deprecated API version. + +## Version Control Settings + +To change a workspace's VCS settings: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and find the workspace you want to update. +2. Choose **Settings** from the sidebar, then **Version Control**. +3. Choose the settings you want, then click **Update VCS settings**. + +You can update the following types of VCS settings for the workspace. + +### VCS Connection + +You can take one of the following actions: + +- To add a new VCS connection, click **Connect to version control**. Select **Version control workflow** and follow the steps to [select a VCS provider and repository](/terraform/enterprise/workspaces/create#create-a-workspace). +- To edit an existing VCS connection, click **Change source**. Choose the **Version control workflow** and follow the steps to [select VCS provider and repository](/terraform/enterprise/workspaces/create#create-a-workspace). +- To remove the VCS connection, click **Change source**. Select either the **CLI-driven workflow** or the **API-driven workflow**, and click **Update VCS settings**. The workspace is no longer connected to VCS. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Terraform Working Directory + +Specify the directory where Terraform will execute runs. This defaults to the root directory in your repository, but you may want to specify another directory if you have directories for multiple different Terraform configurations within the same repository. For example, if you had one `staging` directory and one `production` directory. + +A working directory is required when you use [trigger prefixes](#automatic-run-triggering). + +### Apply Method + +Choose a workflow for Terraform runs. + +- **Auto apply:** Terraform will apply changes from successful plans without prompting for approval. A push to the default branch of your repository will trigger a plan and apply cycle. You may want to do this in non-interactive environments, like continuous deployment workflows. + + !> **Warning:** If you choose auto apply, make sure that no one can change your infrastructure outside of your automated build pipeline. This reduces the risk of configuration drift and unexpected changes. + +- **Manual apply:** Terraform will ask for approval before applying changes from a successful plan. A push to the default branch of your repository will trigger a plan, and then Terraform will wait for confirmation. + +### Automatic Run Triggering + +HCP Terraform uses your VCS provider's API to retrieve the changed files in your repository. You can choose one of the following options to specify which changes trigger Terraform runs. + +#### Always trigger runs + +This option instructs Terraform to begin a run when changes are pushed to any file within the repository. This can be useful for repositories that do not have multiple configurations but require a working directory for some other reason. However, we do not recommend this approach for true monorepos, as it queues unnecessary runs and slows down your ability to provision infrastructure. + +#### Only trigger runs when files in specified paths change + +This option instructs Terraform to begin new runs only for changes that affect specified files and directories. This behavior also applies to [speculative plans](/terraform/enterprise/run/remote-operations#speculative-plans) on pull requests. + +You can use trigger patterns and trigger prefixes in the **Add path** field to specify groups of files and directories. + +- **Trigger Patterns:** (Recommended) Use glob patterns to specify the files that should trigger a new run. For example, `/submodule/**/*.tf`, specifies all files with the `.tf` extension that are nested below the `submodule` directory. You can also use more complex patterns like `/**/networking/**/*`, which specifies all files that have a `networking` folder in their file path. (e.g., `/submodule/service-1/networking/private/main.tf`). Refer to [Glob Patterns for Automatic Run Triggering](#glob-patterns-for-automatic-run-triggering) for details. +- **Trigger Prefixes:** HCP Terraform will queue runs for changes in any of the specified trigger directories matching the provided prefixes (including the working directory). For example, if you use a top-level `modules` directory to share Terraform code across multiple configurations, changes to the shared modules are relevant to every workspace that uses that repository. You can add `modules` as a trigger directory for each workspace to track changes to shared code. + +-> **Note:** HCP Terraform triggers runs on all attached workspaces if it does not receive a list of changed files or if that list is too large to process. When this happens, HCP Terraform may show several runs with completed plans that do not result in infrastructure changes. + +#### Trigger runs when a git tag is published + +This option instructs Terraform to begin new runs only for changes that have a specific tag format. + +The tag format can be chosen between the following options: + +- **Semantic Versioning:** It matches tags in the popular [SemVer format](https://semver.org/). For example, `0.4.2`. +- **Version contains a prefix:** It matches tags which have an additional prefix before the [SemVer format](https://semver.org/). For example, `version-0.4.2`. +- **Version contains a suffix:** It matches tags which have an additional suffix after the [SemVer format](https://semver.org/). For example `0.4.2-alpha`. +- **Custom Regular Expression:** You can define your own regex for HCP Terraform to match against tags. + +You must include an additional `\` to escape the regex pattern when you manage your workspace with the [hashicorp/tfe provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/workspace#tags_regex) and trigger runs through matching git tags. Refer to [Terraform escape sequences](/terraform/language/expressions/strings#escape-sequences) for more details. + +| Tag Format | Regex Pattern | Regex Pattern (Escaped) | +| ----------------------------- | --------------- | ----------------------- | +| **Semantic Versioning** | `^\d+.\d+.\d+$` | `^\\d+.\\d+.\\d+$` | +| **Version contains a prefix** | `\d+.\d+.\d+$` | `\\d+.\\d+.\\d+$` | +| **Version contains a suffix** | `^\d+.\d+.\d+` | `^\\d+.\\d+.\\d+` | + +HCP Terraform triggers runs for all tags matching this pattern, regardless of the value in the [VCS Branch](#vcs-branch) setting. + +### VCS Branch + +This setting designates which branch of the repository HCP Terraform should use when the workspace is set to [Always Trigger Runs](#always-trigger-runs) or [Only trigger runs when files in specified paths change](#only-trigger-runs-when-files-in-specified-paths-change). If you leave this setting blank, HCP Terraform uses the repository's default branch. If the workspace is set to trigger runs when a [git tag is published](#trigger-runs-when-a-git-tag-is-published), all tags will trigger runs, regardless of the branch specified in this setting. + +### Automatic Speculative Plans + +Whether to perform [speculative plans on pull requests](/terraform/enterprise/run/ui#speculative-plans-on-pull-requests) to the connected repository, to assist in reviewing proposed changes. Automatic speculative plans are enabled by default, but you can disable them for any workspace. + +### Include Submodules on Clone + +Select **Include submodules on clone** to recursively clone all of the repository's Git submodules when HCP Terraform fetches a configuration. + +-> **Note:** The [SSH key for cloning Git submodules](/terraform/enterprise/vcs#ssh-keys) is set in the VCS provider settings for the organization and is not related to the workspace's SSH key for Terraform modules. + +## Glob Patterns for Automatic Run Triggering + +We support `glob` patterns to describe a set of triggers for automatic runs. Refer to [trigger patterns](#only-trigger-runs-when-files-in-specified-paths-change) for details. + +Supported wildcards: + +- `*` Matches zero or more characters. +- `?` Matches one or more characters. +- `**` Matches directories recursively. + +The following examples demonstrate how to use the supported wildcards: + +- `/**/*` matches every file in every directory +- `/module/**/*` matches all files in any directory below the `module` directory +- `/**/networking/*` matches every file that is inside any `networking` directory +- `/**/networking/**/*` matches every file that has `networking` directory on its path +- `/**/*.tf` matches every file in any directory that has the `.tf` extension +- `/submodule/*.???` matches every file inside `submodule` directory which has three characters long extension. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/state.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/state.mdx new file mode 100644 index 0000000000..4b070799df --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/state.mdx @@ -0,0 +1,257 @@ +--- +page_title: Manage workspace state in Terraform Enterprise +description: >- + Workspaces have their own separate state data. Learn how Terraform Enterprise + uses state and how to access state from across workspaces. +source: terraform-docs-common +--- + +# Manage workspace state + +Each HCP Terraform workspace has its own separate state data, used for runs within that workspace. + +-> **API:** See the [State Versions API](/terraform/enterprise/api-docs/state-versions). + +## State Usage in Terraform Runs + +In [remote runs](/terraform/enterprise/run/remote-operations), HCP Terraform automatically configures Terraform to use the workspace's state; the Terraform configuration does not need an explicit backend configuration. (If a backend configuration is present, it will be overridden.) + +In local runs (available for workspaces whose execution mode setting is set to "local"), you can use a workspace's state by configuring the [CLI integration](/terraform/cli/cloud) and authenticating with a user token that has permission to read and write state versions for the relevant workspace. When using a Terraform configuration that references outputs from another workspace, the authentication token must also have permission to read state outputs for that workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + + + +During an HCP Terraform run, Terraform incrementally creates intermediate state versions and marks them as finalized once it uploads the state content. + +When a workspace is unlocked, HCP Terraform selects the latest state and sets it as the current state version, deletes all other intermediate state versions that were saved as recovery snapshots for the duration of the lock, and discards all pending intermediate state versions that were superseded by newer state versions. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + + + +## State Versions + +In addition to the current state, HCP Terraform retains historical state versions, which can be used to analyze infrastructure changes over time. + +You can view a workspace's state versions from its **States** tab. Each state in the list indicates which run and which VCS commit (if applicable) it was associated with. Click a state in the list for more details, including a diff against the previous state and a link to the raw state file. + + + +## Managed Resources Count + +-> **Note:** A managed resources count for each organization is available in your organization's settings. + +Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces. + +HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each [resource](/terraform/language/resources/syntax) in the state equals one managed resource. HCP Terraform includes resources in modules and each resource instance created with the `count` or `for_each` meta-arguments. For example, `"aws_instance" "servers" { count = 10 }` creates ten separate managed resources in state. HCP Terraform does not include [data sources](/terraform/language/data-sources) in the count. + +### Examples - Managed Resources + +The following Terraform state excerpt describes a `random` resource. HCP Terraform counts `random` as one managed resource because `“mode”: “managed”`. + +```json +"resources": [ +{ + "mode": "managed", + "type": "random_pet", + "name": "random", + "provider": "provider[\"registry.terraform.io/hashicorp/random\"]", + "instances": [ + { + "schema_version": 0, + "attributes": { + "id": "puma", + "keepers": null, + "length": 1, + "prefix": null, + "separator": "-" + }, + "sensitive_attributes": [] + } + ] + } +] +``` + +A single resource configuration block can describe multiple resource instances with the [`count`](/terraform/language/meta-arguments/count) or [`for_each`](/terraform/language/meta-arguments/for_each) meta-arguments. Each of these instances counts as a managed resource. + +The following example shows a Terraform state excerpt with 2 instances of a `aws_subnet` resource. HCP Terraform counts each instance of `aws_subnet` as a separate managed resource. + +```json +{ + "module": "module.vpc", + "mode": "managed", + "type": "aws_subnet", + "name": "public", + "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]", + "instances": [ + { + "index_key": 0, + "schema_version": 1, + "attributes": { + "arn": "arn:aws:ec2:us-east-2:561656980159:subnet/subnet-024b05c4fba9c9733", + "assign_ipv6_address_on_creation": false, + "availability_zone": "us-east-2a", + ##... + "private_dns_hostname_type_on_launch": "ip-name", + "tags": { + "Name": "-public-us-east-2a" + }, + "tags_all": { + "Name": "-public-us-east-2a" + }, + "timeouts": null, + "vpc_id": "vpc-0f693f9721b61333b" + }, + "sensitive_attributes": [], + "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjo2MDAwMDAwMDAwMDAsImRlbGV0ZSI6MTIwMDAwMDAwMDAwMH0sInNjaGVtYV92ZXJzaW9uIjoiMSJ9", + "dependencies": [ + "data.aws_availability_zones.available", + "module.vpc.aws_vpc.this", + "module.vpc.aws_vpc_ipv4_cidr_block_association.this" + ] + }, + { + "index_key": 1, + "schema_version": 1, + "attributes": { + "arn": "arn:aws:ec2:us-east-2:561656980159:subnet/subnet-08924f16617e087b2", + "assign_ipv6_address_on_creation": false, + "availability_zone": "us-east-2b", + ##... + "private_dns_hostname_type_on_launch": "ip-name", + "tags": { + "Name": "-public-us-east-2b" + }, + "tags_all": { + "Name": "-public-us-east-2b" + }, + "timeouts": null, + "vpc_id": "vpc-0f693f9721b61333b" + }, + "sensitive_attributes": [], + "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjo2MDAwMDAwMDAwMDAsImRlbGV0ZSI6MTIwMDAwMDAwMDAwMH0sInNjaGVtYV92ZXJzaW9uIjoiMSJ9", + "dependencies": [ + "data.aws_availability_zones.available", + "module.vpc.aws_vpc.this", + "module.vpc.aws_vpc_ipv4_cidr_block_association.this" + ] + } + ] +} +``` + +### Example - Excluded Data Source + +The following Terraform state excerpt describes a `aws_availability_zones` data source. HCP Terraform does not include `aws_availability_zones` in the managed resource count because `”mode”: “data”`. + +```json + "resources": [ + { + "mode": "data", + "type": "aws_availability_zones", + "name": "available", + "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]", + "instances": [ + { + "schema_version": 0, + "attributes": { + "all_availability_zones": null, + "exclude_names": null, + "exclude_zone_ids": null, + "filter": null, + "group_names": [ + "us-east-2" + ], + "id": "us-east-2", + "names": [ + "us-east-2a", + "us-east-2b", + "us-east-2c" + ], + "state": null, + "zone_ids": [ + "use2-az1", + "use2-az2", + "use2-az3" + ] + }, + "sensitive_attributes": [] + } + ] + } + ] +``` + + + +## State Manipulation + +Certain tasks (including importing resources, tainting resources, moving or renaming existing resources to match a changed configuration, and more) may require modifying Terraform state outside the context of a run, depending on which version of Terraform your HCP Terraform workspace is configured to use. + +Newer Terraform features like [`moved` blocks](/terraform/language/modules/develop/refactoring), [`import` blocks](/terraform/language/import), and the [`replace` option](/terraform/enterprise/run/modes-and-options#replacing-selected-resources) allow you to accomplish these tasks using the usual plan and apply workflow. However, if the Terraform version you're using doesn't support these features, you may need to fall back to manual state manipulation. + +Manual state manipulation in HCP Terraform workspaces, with the exception of [rolling back to a previous state version](#rolling-back-to-a-previous-state), requires the use of Terraform CLI, using the same commands as would be used in a local workflow (`terraform import`, `terraform taint`, etc.). To manipulate state, you must configure the [CLI integration](/terraform/cli/cloud) and authenticate with a user token that has permission to read and write state versions for the relevant workspace. ([More about permissions.](/terraform/enterprise/users-teams-organizations/permissions)) + +### Rolling Back to a Previous State + +You can rollback to a previous, known good state version using the HCP Terraform UI. Navigate to the state you want to rollback to and click the **Advanced** toggle button. This option requires that you have access to create new state and that you lock the workspace. It works by duplicating the state that you specify and making it the workspace's current state version. The workspace remains locked. To undo the rollback operation, rollback to the state version that was previously the latest state. + +-> **Note:** You can rollback to any prior state, but you should use caution because replacing state improperly can result in orphaned or duplicated infrastructure resources. This feature is provided as a convenient alternative to manually downloading older state and using state manipulation commands in the CLI to push it to HCP Terraform. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Accessing State from Other Workspaces + +-> **Note:** Provider-specific [data sources](/terraform/language/data-sources) are usually the most resilient way to share information between separate Terraform configurations. `terraform_remote_state` is more flexible, but we recommend using specialized data sources whenever it is convenient to do so. + +Terraform's built-in [`terraform_remote_state` data source](/terraform/language/state/remote-state-data) lets you share arbitrary information between configurations via root module [outputs](/terraform/language/values/outputs). + +HCP Terraform automatically manages API credentials for `terraform_remote_state` access during [runs managed by HCP Terraform](/terraform/enterprise/run/remote-operations#remote-operations). This means you do not usually need to include an API token in a `terraform_remote_state` data source's configuration. + +## Upgrading State + +You can upgrade a workspace's state version to a new Terraform version without making any configuration changes. To upgrade, we recommend the following steps: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the workspace you want to upgrade. +2. Run a [speculative plan](/terraform/enterprise/run/ui#testing-terraform-upgrades-with-speculative-plans) to test whether your configuration is compatible with the new Terraform version. You can run speculative plans with a Terraform version that is different than the one currently selected for the workspace. +3. Select **Settings > General** and select the desired new **Terraform Version**. +4. Click **+ New run** and then select **Allow empty apply** as the run type. An [empty apply](/terraform/enterprise/run/modes-and-options#allow-empty-apply) allows Terraform to apply a plan that produces no infrastructure changes. Terraform upgrades the state file version during the apply process. + +-> **Note:** If the desired Terraform version is incompatible with a workspace's existing state version, the run fails and HCP Terraform prompts you to run an apply with a compatible version first. Refer to the [Terraform upgrade guides](/terraform/language/upgrade-guides) for details about upgrading between versions. + +### Remote State Access Controls + +Remote state access between workspaces is subject to access controls: + +- Only workspaces within the same organization can access each other's state. +- The workspace whose state is being read must be configured to allow that access. State access permissions are configured on a workspace's [general settings page](/terraform/enterprise/workspaces/settings). There are two ways a workspace can allow access: + - Globally, to all workspaces within the same organization. + - Selectively, to a list of specific approved workspaces. + +By default, new workspaces in HCP Terraform do not allow other workspaces to access their state. We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other. + +-> **Note:** The default access permissions for new workspaces in HCP Terraform changed in April 2021. Workspaces created before this change defaulted to allowing global access within their organization. These workspaces can be changed to more restrictive access at any time on their [general settings page](/terraform/enterprise/workspaces/settings). Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access. + +### Data Source Configuration + +To configure a `tfe_outputs` data source that references an HCP Terraform workspace, specify the organization and workspace in the `config` argument. + +You must still properly configure the `tfe` provider with a valid authentication token and correct permissions to HCP Terraform. + +```hcl +data "tfe_outputs" "vpc" { + config = { + organization = "example_corp" + workspaces = { + name = "vpc-prod" + } + } +} + +resource "aws_instance" "redis_server" { + # Terraform 0.12 and later: use the "outputs." attribute + subnet_id = data.tfe_outputs.vpc.outputs.subnet_id +} +``` + +-> **Note:** Remote state access controls do not apply when using the `tfe_outputs` data source. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/tags.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/tags.mdx new file mode 100644 index 0000000000..6617ddc9be --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/tags.mdx @@ -0,0 +1,94 @@ +--- +page_title: Create workspace tags +description: >- + Learn how to create tags for your workspaces so that you can organize + workspaces. Tagging workspaces also lets you sort and filter workspaces in the + UI. +source: terraform-docs-common +--- + +# Create workspace tags + +This topic describes how to create and attach tags to your workspaces. + +## Overview + +Tagging workspaces helps organization administrators organize, sort, and filter workspaces so that they can track resource consumption. For example, you could add a `cost-center` tag so that administrators can sort workspaces according to cost center. + +HCP Terraform stores tags as key-value pairs or as key-only tags. Key-only tags enable you to associate a single Terraform configuration file with several workspaces according to tag. Refer to the following topics in the Terraform CLI and configuration language documentation for additional information: + +- [`terraform{}.cloud{}.workspaces` reference](/terraform/language/terraform#terraform-cloud-workspaces) +- [Define connection settings](/terraform/cli/cloud/settings#define-connection-settings) + +### Reserved tags + +You can reserve a set of tag keys for each organization. Reserved tag keys appear as suggestions when people create tags for projects and workspaces so that you can use consistent terms for tags. Refer to [Create and manage reserved tags](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for additional information. + +### Single-value tags + +Your system may contain single-value tags created using Terraform v1.10 and older. You can migrate existing single-value tags to the key-value scheme. Refer to [Migrate single-value tags](#migrate-single-value-tags) for instructions. + +## Requirements + +- You must be member of a team with the **Write** permission group enabled for the workspace to create tags for a workspace. +- You must be member of a team with the **Admin** permission group enabled for the workspace to delete tags on a workspace. + +You cannot create tags for a workspace using the CLI. + +## Define tags + +1. Open your workspace. + +2. Click either the count link for the **Tags** label or **Manage Tags** in the **Tags** card on the right-sidebar to open the **Manage workspace tags** drawer. + +3. Click **+Add tag** and perform one of the following actions: + + - Specify a key-value pair: Lets you sort, filter, and search on either key or value. + - Specify a tag key and leave the **Value** field empty: Lets you sort, filter, and search on only the key name. + - Choose a reserved key from the suggested tag key list and specify a value: Ensures that you are using the key name consistently and lets you sort, filter, and search on either key or value. + - Choose a reserved key from the suggested tag key list and leave the **Value** field empty: Ensures that you are using the key name consistently and lets you sort, filter, and search on only the key name. + + Refer to [Tag syntax](#Tag-syntax) for information about supported characters. + +4. Tags inherited from the project appear in the **Inherited Tags** section. You can attach new key-value pairs to their projects to override inherited tags. Refer to [Manage projects](/terraform/enterprise/projects/manage) for additional information about using tags in projects. + + You cannot override reserved tag keys when the **Disable overrides** option is enabled. Refer to [Create and manage reserved tags](/terraform/enterprise/users-teams-organizations/organizations/manage-reserved-tags) for additional information. + + You can also click on tag links in the **Inherited Tags** section to view workspaces that use the same tag. + +5. Click **Save**. + +Tags that you create appear in the tags management screen in the organization settings. Refer to [Organizations](/terraform/enterprise/users-teams-organizations/organizations) for additional information. + +## Update tags + +1. Open your workspace. +2. Click either the count link for the **Tags** label or **Manage Tags** in the **Tags** card on the right-sidebar to open the **Manage workspace tags** drawer. +3. In the **Tags applied to this resource** section, modify a key, value, or both and click **Save**. + +## Migrate single-value tags + +You can use the API to convert existing single-value tags to key-value tags. You must have permissions in the workspace to perform the following task. Refer to [Requirements](#requirements) for additional information. + +Terraform v1.10 and older adds single-value workspace tags defined in the associated Terraform configuration to workspaces selected by the configuration. As result, your workspace may include duplicate tags. Refer to the [Terraform reference documentation](/terraform/language/terraform#terraform-cloud-workspaces) for additional information. + +### Re-create existing workspace tags as resource tags + +1. Send a `GET` request to the [`/organizations/:organization_name/tags`](/terraform/enterprise/api-docs/organization-tags#list-tags) endpoint to request all workspaces for your organization. The response may span several pages. +2. For each workspace, check the `tag-names` attribute for existing tags. +3. Send a `PATCH` request to the [`/workspaces/:workspace_id`](/terraform/enterprise/api-docs/workspaces#update-a-workspace) endpoint and include the `tag-binding` relationship in the request body for each workspace tag. + +### Delete single-value workspace tags + +1. Send a `GET` request to the [`/organizations/:organization_name/tags`](/terraform/enterprise/api-docs/organization-tags#list-tags) endpoint to request all workspaces for your organization. +2. Enumerate the external IDs for all tags. +3. Send a `DELETE` request to the [`/organizations/:organization_name/tags`](/terraform/enterprise/api-docs/organization-tags#delete-tags) endpoint to delete tags. + +## Tag syntax + +The following rules apply to tags: + +- Tags must be one or more characters. +- Tags have a 255 character limit. +- Tags can include letters, numbers, colons, hyphens, and underscores. +- For tags stored as key-value pairs, tag values are optional. diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/variables/index.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/variables/index.mdx new file mode 100644 index 0000000000..22c1581891 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/variables/index.mdx @@ -0,0 +1,237 @@ +--- +page_title: Workspace variables in Terraform Enterprise +description: >- + Terraform Enterprise workspaces allow you to customize Terraform runs. Learn + how to use Terraform variables and environment variables. +source: terraform-docs-common +--- + +# Workspace variables + +HCP Terraform workspace variables let you customize configurations, modify Terraform's behavior, setup [dynamic provider credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials), and store information like static provider credentials. + +You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. For example, you could define a variable set of provider credentials and automatically apply it to all of the workspaces using that provider. You can use the command line to specify variable values for each plan or apply. Otherwise, HCP Terraform applies workspace variables to all runs within that workspace. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +## Types + +You can create both environment variables and Terraform variables in HCP Terraform. + +> **Hands-on:** Try the [Create and Use a Variable Sets](/terraform/tutorials/cloud-get-started/cloud-create-variable-set) and [Create Infrastructure](/terraform/tutorials/cloud-get-started/cloud-workspace-configure) tutorials to set environment and Terraform variables in HCP Terraform. + +### Environment variables + +HCP Terraform performs Terraform runs on disposable Linux worker VMs using a POSIX-compatible shell. Before running Terraform operations, HCP Terraform uses the `export` command to populate the shell with environment variables. + +Environment variables can store provider credentials and other data. Refer to your provider's Terraform Registry documentation for a full list of supported shell environment variables (e.g., authentication variables for [AWS](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables), [Google Cloud Platform](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials), and [Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#argument-reference)). Environment variables can also [modify Terraform's behavior](/terraform/cli/config/environment-variables). For example, `TF_LOG` enables detailed logs for debugging. + +#### Parallelism + +You can use the `TFE_PARALLELISM` environment variable when your infrastructure providers produce errors on concurrent operations or use non-standard rate limiting. The `TFE_PARALLELISM` variable sets the `-parallelism=` flag for `terraform plan` and `terraform apply` ([more about `parallelism`](/terraform/internals/graph#walking-the-graph)). Valid values are between 1 and 256, inclusive, and the default is `10`. HCP Terraform agents do not support `TFE_PARALLELISM`, but you can specify flags as environment variables directly via [`TF_CLI_ARGS_name`](/terraform/cli/config/environment-variables#tf-cli-args). In these cases, use `TF_CLI_ARGS_plan="-parallelism="` or `TF_CLI_ARGS_apply="-parallelism="` instead. + +!> **Warning:** We recommend reading and understanding [Terraform parallelism](https://support.hashicorp.com/hc/en-us/articles/10348130482451) prior to setting `TFE_PARALLELISM`. You can also contact HashiCorp support for direct advice. + +#### Dynamic credentials + +You can configure [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials) for certain providers using environment variables [at the workspace level](/terraform/enterprise/workspaces/variables/managing-variables#workspace-specific-variables) or using [variable sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets). + +Dynamic credentials allows for using temporary per-run credentials and eliminates the need to manually rotate secrets. + +### Terraform variables + +Terraform variables refer to [input variables](/terraform/language/values/variables) that define parameters without hardcoding them into the configuration. For example, you could create variables that let users specify the number and type of Amazon Web Services EC2 instances they want to provision with a Terraform module. + +```hcl +variable "instance_count" { + description = "Number of instances to provision." + type = number + default = 2 +} +``` + +You can then reference this variable in your configuration. + +```hcl +module "ec2_instances" { + source = "./modules/aws-instance" + + instance_count = var.instance_count + ## ... +} +``` + +If a required input variable is missing, Terraform plans in the workspace will fail and print an explanation in the log. + +## Scope + +Each environment and Terraform variable can have one of the following scopes: + +| Scope | Description | Resources | +| ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Run-Specific | Apply to a specific run within a single workspace. | [Specify Run-Specific Variables](/terraform/enterprise/workspaces/variables/managing-variables#run-specific-variables) | +| Workspace-Specific | Apply to a single workspace. | [Create Workspace-Specific Variables](/terraform/enterprise/workspaces/variables/managing-variables#workspace-specific-variables), [Loading Variables from Files](/terraform/enterprise/workspaces/variables/managing-variables#loading-variables-from-files), [Workspace-Specific Variables API](/terraform/enterprise/api-docs/workspace-variables). | +| Workspace-Scoped Variable Set | Apply to multiple workspaces within the same organization. | [Create Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) and [Variable Sets API](/terraform/enterprise/api-docs/variable-sets) | +| Project-Scoped Variable Set | Automatically applied to all current and future workspaces within a project. | [Create Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) and [Variable Sets API](/terraform/enterprise/api-docs/variable-sets) | +| Global Variable Set | Automatically applied to all current and future workspaces within an organization. | [Create Variable Sets](/terraform/enterprise/workspaces/variables/managing-variables#variable-sets) and [Variable Sets API](/terraform/enterprise/api-docs/variable-sets) | + +## Variable set ownership + +Projects and organizations can both own variable sets. The owner of a variable set can determine the precedence of that set. + +Use organization-owned variable sets to share variables across multiple projects. Managing organization-owned variable sets [requires a higher permission level](/terraform/enterprise/workspaces/variables/managing-variables#permissions) because you can apply these sets to any project in your organization. + +Use project-owned variable sets to share variables across multiple workspaces within a single project. Project-owned variable sets only require permissions on the project itself, rather than organization-level permissions. + +Refer to [**Manage variable sets**](/terraform/enterprise/workspaces/variables/managing-variables#permissions) for more details on variable set permissions. + +## Precedence + +> **Hands On:** The [Manage Multiple Variable Sets in HCP Terraform](/terraform/tutorials/cloud/cloud-multiple-variable-sets) tutorial shows how to manage multiple variable sets and demonstrates variable precedence. + +There may be cases when a workspace contains conflicting variables of the same type with the same key. HCP Terraform marks overwritten variables in the UI. + +HCP Terraform prioritizes and overwrites conflicting variables according to the following precedence: + +### 1. Priority global variable sets + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a global variable set have precedence over all other variables with the same key. + +### 2. Priority project-scoped variable set owned by an organization + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope. Prioritized variables sets owned by organizations take precedence over priority variable sets owned by projects. + +### 3. Priority workspace-scoped variable set owned by an organization + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in an organization-owned variable set scoped to a workspace have precedence over variables with the same key set at a more specific scope. Prioritized variables sets owned by organizations take precedence over sets owned by projects. + +### 4. Priority project-scoped variable set owned by a project + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a priority project-scoped variable set have precedence over variables with the same key set at a more specific scope. + +### 5. Priority workspace-scoped variable set owned by a project + +If [prioritized](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets), variables in a priority workspace-scoped variable set have precedence over variables with the same key set at a more specific scope. + +### 6. Command line argument variables + +When using a CLI workflow, variables applied to a run with either `-var` or `-var-file` overwrite workspace-specific and variable set variables that have the same key. + +### 7. Local environment variables prefixed with `TF_VAR_` + +When using a CLI workflow, local environment variables prefixed with `TF_VAR_` (e.g., `TF_VAR_replicas`) overwrite workspace-specific, variable set, and `.auto.tfvars` file variables that have the same key. + +### 8. Workspace-specific variables + +Workspace-specific variables always overwrite variables from variable sets that have the same key. Refer to [overwrite variables from variable sets](/terraform/enterprise/workspaces/variables/managing-variables#overwrite-variable-sets) for details. + +### 9. Workspace-scoped variable owned by a project + +Variables in workspace-scoped variable sets are only applied to a subset of workspaces in a project. + +When workspace-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based on the lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same workspace, HCP Terraform will use any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +Variables sets scoped to workspaces that are owned by projects take precedence over sets with the same scope that are owned by organizations. + +### 10. Project-scoped variable set owned by a project + +Variables in project-scoped variable sets are only applied to the workspaces within the specified projects. + +When project-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based the on lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same project, HCP Terraform uses any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +Variables sets owned by projects take precedence over those owned by organizations. + +### 11. Workspace-scoped variable set owned by an organization + +Variables in workspace-scoped variable sets are only applied to the specified workspaces in an organization. + +When workspace-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based on the lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same workspace, HCP Terraform will use any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +### 12. Project-scoped variable set owned by an organization + +Variables in project-scoped variable sets are only applied to the workspaces within the specified projects. + +When project-scoped variable sets have conflicting variables, HCP Terraform compares the variable set names and uses values from the variable set with lexical precedence. Terraform and HCP Terraform operate on UTF-8 strings, and HCP Terraform sorts variable set names based the on lexical order of Unicode code points. + +For example, if you apply `A_Variable_Set` and `B_Variable_Set` to the same project, HCP Terraform uses any conflicting variables from `A_Variable_Set`. This is the case regardless of which variable set has been edited most recently. HCP Terraform only considers the lexical ordering of variable set names when determining precedence. + +### 13. Global variable sets + +Workspace and project-scoped variable sets always take precedence over global variable sets that are applied to all workspaces within an organization. Terraform does not allow global variable sets to contain variables with the same key, so they cannot conflict. + +### 14. `*.auto.tfvars` variable files + +Variables in the HCP Terraform workspace and variables provided through the command line always overwrite variables with the same key from files ending in `.auto.tfvars`. + +### 15. `terraform.tfvars` variable file + +Variables in the `.auto.tfvars` files take precedence over variables in the `terraform.tfvars` file. + + + +Although HCP Terraform uses variables from `terraform.tfvars`, Terraform Enterprise currently ignores this file. + + + +## Precedence with priority variable sets + +You can select to prioritize all values of the variables in a variable set. +When a variable set is priority, the values take precedence over any variables with the same key set at a more specific scope. + +For example, variables in a priority global variable set would take precedence over all variables with the same key. + +If two priority variable sets with the same scope and ownership include the same variable key, HCP Terraform will determine precedence by the alphabetical order of the variable sets' names. + +While a priority variable set can enforce that Terraform variables use designated values, it does not guarantee that the configuration uses the variable. A user can still directly modify the Terraform configuration to remove usage of a variable and replace it with a hard-coded value. For stricter enforcement, we recommend using policy checks or run tasks. + +## Precedence example + +Consider an example workspace that has the following different kinds of variables and variable sets: + +| Source | Priority | Ownership | Scope | +| ------------------------------------------------------------- | -------- | ------------ | --------- | +| Priority **global** variable set | true | organization | global | +| Priority organization-owned **project-scoped** variable set | true | organization | project | +| Priority organization-owned **workspace-scoped** variable set | true | organization | workspace | +| Priority project-owned **project-scoped** variable set | true | project | project | +| Priority project-owned **workspace-scoped** variable set | true | project | workspace | +| Command line argument | N/A | N/A | run | +| Local environment variable | N/A | N/A | workspace | +| **Workspace-specific** variable | N/A | N/A | workspace | +| Project-owned **workspace-scoped** variable set | false | project | workspace | +| Project-owned **project-scoped** variable set | false | project | project | +| Organization-owned **workspace-scoped** variable set | false | organization | workspace | +| Organization-owned **project-scoped** variable set | false | organization | project | +| **Global** variable set | false | organization | global | + +If these variables and variable sets had the following variables applied: + +| Source (priority/ownership/scope) | Region | Var1 | Replicas | +| ------------------------------------------------------------- | ----------- | ---- | -------- | +| Priority **global** variable set | `us-east-1` | | | +| Priority organization-owned **project-scoped** variable set | `us-east-2` | | | +| Priority organization-owned **workspace-scoped** variable set | `us-west-1` | | | +| Priority project-owned **project-scoped** variable set | `eu-east-2` | | | +| Priority project-owned **workspace-scoped** variable set | `eu-west-1` | | | +| Command line argument | `us-west-2` | | `9` | +| Local environment variable | | | `8` | +| **Workspace-specific** variable | | `h` | `1` | +| Project-owned **workspace-scoped** variable set | | `y` | `2` | +| Project-owned **project-scoped** variable set | | | `4` | +| Organization-owned **workspace-scoped** variable set | | `z` | `3` | +| Organization-owned **project-scoped** variable set | | | `5` | +| **Global** variable set | | | `6` | + +When you trigger a run through the command line, these are the final values HCP Terraform assigns to each variable: + +| Variable | Value | +| -------- | ----------- | +| Region | `us-east-1` | +| Var1 | `h` | +| Replicas | `9` | diff --git a/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/variables/managing-variables.mdx b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/variables/managing-variables.mdx new file mode 100644 index 0000000000..78dd91d594 --- /dev/null +++ b/content/ptfe-releases/v000011-1/docs/enterprise/workspaces/variables/managing-variables.mdx @@ -0,0 +1,248 @@ +--- +page_title: Manage variables and variable sets in Terraform Enterprise +description: >- + Use workspace variables and variable sets to customize Terraform Enterprise + runs. +source: terraform-docs-common +--- + +# Manage variables and variable sets + +You can set variables specifically for each workspace or you can create variable sets to reuse the same variables across multiple workspaces. Refer to the [variables overview](/terraform/enterprise/workspaces/variables) documentation for more information about variable types, scope, and precedence. You can also set variable values specifically for each run on the command line. + +You can create and edit workspace-specific variables through: + +- The HCP Terraform UI, as detailed below. +- The Variables API for [workspace-specific variables](/terraform/enterprise/api-docs/workspace-variables) and [variable sets](/terraform/enterprise/api-docs/variable-sets). +- The `tfe` provider's [`tfe_variable`](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/resources/variable) resource, which can be more convenient for bulk management. + +## Permissions + +You must have [**Read variables** permission](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) to view the variables for a particular workspace and to view the variable sets in your organization. To create or edit workspace-specific variables within a workspace, you must have [**Read and write variables**](/terraform/enterprise/users-teams-organizations/permissions#general-workspace-permissions) for that workspace. + +To create, update, or delete organization-owned variable sets, you must be one of the following: + +- A member of the [owners team](/terraform/enterprise/users-teams-organizations/permissions#organization-owners) +- A member of a team with [**Manage all projects**](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects) +- A member of a team with [**Manage all workspaces**](/terraform/enterprise/users-teams-organizations/permissions#manage-all-workspaces) + +To create, edit, or apply project-owned variable sets, you must be part of a team with one of the following: + +- **Write** project permissions +- **Maintain** project permissions +- **Admin** project permissions +- [**Manage variable sets**](/terraform/enterprise/users-teams-organizations/permissions#general-project-permissions) project permissions +- [**Manage all projects**](/terraform/enterprise/users-teams-organizations/permissions#manage-all-projects) organization permissions + +## Run-Specific Variables + +Terraform 1.1 and later lets you set [Terraform variable](/terraform/enterprise/workspaces/variables#terraform-variables) values for a particular plan or apply on the command line. These variable values will overwrite workspace-specific and variable set variables with the same key. Refer to the [variable precedence](/terraform/enterprise/workspaces/variables#precedence) documentation for more details. + +You can set run-specific Terraform variable values by: + +- Specifying `-var` and `-var-file` arguments. For example: + + terraform apply -var="key=value" -var-file="testing.tfvars" +- Creating local environment variables prefixed with `TF_VAR_`. For example, if you declare a variable called `replicas` in your configuration, you could create a local environment variable called `TF_VAR_replicas` and set it to a particular value. When you use the [CLI Workflow](/terraform/enterprise/run/cli), Terraform automatically identifies these environment variables and applies their values to the run. + +Refer to the [variables on the command line](/terraform/language/values/variables#variables-on-the-command-line) documentation for more details and examples. + +## Workspace-Specific Variables + +To view and manage a workspace's variables, go to the workspace and click the **Variables** tab. + +The **Variables** page appears, showing all workspace-specific variables and variable sets applied to the workspace. This is where you can add, edit, and delete workspace-specific variables. You can also apply and remove variable sets from the workspace. + +The **Variables** page is not available for workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode). HCP Terraform does not evaluate workspace variables or variable sets in local execution mode. + +### Add a Variable + +To add a variable: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and select the workspace you want to define a variable for. + +2. Go to the workspace **Variables** page and click **+ Add variable** in the **Workspace Variables** section. + +3. Choose a variable category (Terraform or environment), optionally mark the variable as [sensitive](#sensitive-values), and enter a variable key, value, and optional description. For Terraform variables only, you can check the **HCL** checkbox to enter a value in HashiCorp Configuration Language. + + Refer to [variable values and format](#variable-values-and-format) for variable limits, allowable values, and formatting. + +4. Click **Save variable**. The variable now appears in the list of the workspace's variables and HCP Terraform will apply it to runs. + +### Edit a Variable + +To edit a variable: + +1. Click the ellipses next to the variable you want to edit and select **Edit**. +2. Make any desired changes and click **Save variable**. + +### Delete a Variable + +To delete a variable: + +1. Click the ellipses next to the variable you want to delete and select **Delete**. +2. Click **Yes, delete variable** to confirm your action. + +## Loading Variables from Files + +You can set [Terraform variable](/terraform/enterprise/workspaces/variables#terraform-variables) values by providing any number of [files ending in `.auto.tfvars`](/terraform/language/values/variables#variable-files) to workspaces that use Terraform 0.10.0 or later. When you trigger a run, Terraform automatically loads and uses the variables defined in these files. If any variable from the workspace has the same key as a variable in the file, the workspace variable overwrites variable from the file. + +You can only do this with files ending in `auto.tfvars` or `terraform.tfvars`. You can apply other types of `.tfvars` files [using the command line](#run-specific-variables) for each run. + +~> **Note:** HCP Terraform loads variables from files ending in `auto.tfvars` for each Terraform run, but does not automatically persist those variables to the HCP Terraform workspace or display them in the **Variables** section of the workspace UI. + +## Variable Sets + +> **Hands On:** Try the [Manage Variable Sets in HCP Terraform tutorial](/terraform/tutorials/cloud/cloud-multiple-variable-sets) tutorial. + +Variable sets are reusable collections of variables that you can apply to multiple workspaces. You can create variable sets under an organization or a project. Whether the variable set is owned by an organization or a project determines the permissions required to manage that set. Learn more about [variable set permissions](#permissions). + +HCP Terraform does not evaluate variable sets during Terraform runs for workspaces configured with `Local` [execution mode](/terraform/enterprise/workspaces/settings#execution-mode). + +Organizations or projects can own variable sets. To view variable sets, click **Settings** in your organization or project, then click **Variable sets**. + +The **Variable sets** page lists all of the organization's or project's variable sets. Click on a variable set to open it and review details about its variables and scoping. + +### Create Variable Sets + +To create a variable set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the **Settings** page for your organization or project. + +2. Click **Variable Sets**. + +3. Click **Create variable set**. + +4. Choose a descriptive **Name** for the variable set. You can use any combination of numbers, letters, and characters. + +5. Write an optional **Description** that tells other users about the purpose of the variable set and what it contains. + +6. Choose a variable set scope: + - Organization-owned + - **Apply globally:** HCP Terraform automatically applies this global variable set to all existing and future workspaces. + - **Apply to specific projects and workspaces:** Use the text fields to search for and select workspaces and projects to apply this variable set to. This affects all current and future workspaces for any selected projects. After creation, users can also [add this variable set to their workspaces](#apply-or-remove-variable-sets-from-inside-a-workspace). + - Project-owned + - **Apply to the entire project:** HCP Terraform automatically applies this variable set to all existing and future workspaces in the project. + - **Apply to specific workspaces in the project:** Use the text fields to search for and select workspaces to apply this variable set to. After creation, users can also [add this variable set to their workspaces](#apply-or-remove-variable-sets-from-inside-a-workspace). + +7. Add one or more variables: Click **+ Add variable**, choose a variable type (Terraform or environment), optionally mark the variable as [sensitive](#sensitive-values), and enter a variable name, value, and optional description. Then, click **Save variable**. + + Refer to [variable values and format](#variable-values-and-format) for variable limits, allowable values, and formatting. + + ~> **Note:** HCP Terraform will error if you try to declare variables with the same key in multiple global variable sets. + +8. Click **Create variable set.** HCP Terraform adds the new variable set to any specified workspaces and displays it on the **Variable Sets** page. + +### Edit Variable Sets + +To edit or remove a variable set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the **Settings** page for your organization or project. + +2. Click **Variable Sets**. + +3. Select the variable set you want to edit. That specific variable set page appears, where you can change the variable set settings. Refer to [create variable sets](#create-variable-sets) for details. + +### Delete Variable Sets + +Deleting a variable set can be a disruptive action, especially if the variables are required to execute runs. We recommend informing organization, project, and workspace owners before removing a variable set. + +To delete a variable set: + +1. Sign in to [HCP Terraform](https://app.terraform.io/) or Terraform Enterprise and navigate to the **Settings** page for your organization or project. + +2. Click **Variable Sets**. + +3. Select **Delete variable set**. Enter the variable set name and click **Delete variable set** to confirm this action. HCP Terraform deletes the variable set and removes it from all workspaces. Runs within those workspaces will no longer use the variables from the variable set. + +### Apply or Remove Variable Sets From Inside a Workspace + +To apply a variable set to a specific workspace: + +1. Navigate to the workspace and click the **Variables** tab. The **Variables** page appears, showing all workspace-specific variables and variable sets applied to the workspace. + +2. In the **Variable sets** section, click **Apply Variable Set**. Select the variable set you want to apply to your workspace, and click **Apply variable set**. The variable set appears in the workspace's variable sets list and HCP Terraform will now apply the variables to runs. + +To remove a variable set from within a workspace: + +1. Navigate to the workspace and click the **Variables** tab. The **Variables** page appears, showing all workspace-specific variables and variable sets applied to the workspace. +2. Click the ellipses button next to the variable set and select **Remove variable set**. +3. Click **Remove variable set** in the dialog box. HCP Terraform removes the variable set from this workspace, but it remains available to other workspaces in the organization. + +## Overwrite Variable Sets + +You can overwrite variables defined in variable sets within a workspace. For example, you may want to use a different set of provider credentials in a specific workspace. + +To overwrite a variable from a variable set, [create a new workspace-specific variable](#workspace-specific-variables) of the same type with the same key. HCP Terraform marks any variables that you overwrite with a yellow **OVERWRITTEN** flag. When you click the overwritten variable, HCP Terraform highlights the variable it will use during runs. + +Variables within a variable set can also automatically overwrite variables with the same key in other variable sets applied to the same workspace. Though variable sets are created for the organization or project, these overwrites occur within each workspace. Refer to [variable precedence](/terraform/enterprise/workspaces/variables#precedence) for more details. + +## Priority Variable Sets + +The values in priority variable sets overwrite any variables with the same key set at more specific scopes. This includes variables set using command line flags, or through`.*auto.tfvars` and `terraform.tfvars` files. + +It is still possible for a user to directly modify the Terraform configuration and remove usage of a variable and replace it with a hard coded value. For stricter enforcement, we recommend using policy checks or run tasks. +Refer to [variable precedence](/terraform/enterprise/workspaces/variables#precedence-with-priority-variable-sets) for more details. + +## Variable Values and Format + +The limits, allowable values, and required format are the same for both workspace-specific variables and variable sets. + +### Security + +HCP Terraform encrypts all variable values securely using [Vault's transit backend](/vault/docs/secrets/transit) prior to saving them. This ensures that no out-of-band party can read these values without proper authorization. However, HCP Terraform stores variable [descriptions](#variable-description) in plain text, so be careful with the information you save in a variable description. + +We also recommend passing credentials to Terraform as environment variables instead of Terraform variables when possible, since Terraform runs receive the full text of all Terraform variable values, including [sensitive](#sensitive-values) ones. It may print the values in logs and state files if the configuration sends the value to an output or a resource parameter. Sentinel mocks downloaded from runs will also contain the sensitive values of Terraform variables. + +Although HCP Terraform does not store environment variables in state, it can include them in log files if `TF_LOG` is set to `TRACE`. + +#### Dynamic Credentials + +An alternative to passing static credentials for some providers is to use [dynamic credentials](/terraform/enterprise/workspaces/dynamic-provider-credentials). + +Dynamic credentials allows for using temporary per-run credentials and eliminates the need to manually rotate secrets. + +### Character Limits + +The following limits apply to variables: + +| Component | Limit | +| ----------- | -------------- | +| description | 512 characters | +| key | 128 characters | +| value | 256 kilobytes | + +### Multi-Line Text + +You can type or paste multi-line text into variable value text fields. + +### HashiCorp Configuration Language (HCL) + +You can use HCL for Terraform variables, but not for environment variables. The same Terraform version that performs runs in the workspace will interpret the HCL. + +Variable values are strings by default. To enter list or map values, click the variable’s **HCL** checkbox (visible when editing) and enter the value with the same HCL syntax you would use when writing Terraform code. For example: + +```hcl +{ + us-east-1 = "image-1234" + us-west-2 = "image-4567" +} +``` + +### Sensitive Values + +!> **Warning:** There are some cases when even sensitive variables are included in logs and state files. Refer to [security](#security) for more information. + +Terraform often needs cloud provider credentials and other sensitive information that should not be widely available within your organization. To protect these secrets, you can mark any Terraform or environment variable as sensitive data by clicking its **Sensitive** checkbox that is visible during editing. + +Marking a variable as sensitive makes it write-only and prevents all users (including you) from viewing its value in the HCP Terraform UI or reading it through the Variables API endpoint. + +Users with permission to read and write variables can set new values for sensitive variables, but other attributes of a sensitive variable cannot be modified. To update other attributes, delete the variable and create a new variable to replace it. + +[permissions-citation]: #intentionally-unused---keep-for-maintainers + +### Variable Description + +!> **Warning:** Variable descriptions are not encrypted, so do not include any sensitive information. + +Variable descriptions are optional, and help distinguish between similarly named variables. They are only shown on the **Variables** page and are completely independent from any variable descriptions declared in Terraform CLI. diff --git a/content/ptfe-releases/v000011-1/img/docs/ado-required-status-check.png b/content/ptfe-releases/v000011-1/img/docs/ado-required-status-check.png new file mode 100644 index 0000000000..0a584d490c Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/ado-required-status-check.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/azure-devops-server-public-keys.png b/content/ptfe-releases/v000011-1/img/docs/azure-devops-server-public-keys.png new file mode 100644 index 0000000000..fa9488c0dd Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/azure-devops-server-public-keys.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/azure-devops-services-application-permissions.png b/content/ptfe-releases/v000011-1/img/docs/azure-devops-services-application-permissions.png new file mode 100644 index 0000000000..b50cb74333 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/azure-devops-services-application-permissions.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/azure-devops-services-oauth-policies.png b/content/ptfe-releases/v000011-1/img/docs/azure-devops-services-oauth-policies.png new file mode 100644 index 0000000000..1b3221636a Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/azure-devops-services-oauth-policies.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/download-mocks.png b/content/ptfe-releases/v000011-1/img/docs/download-mocks.png new file mode 100644 index 0000000000..4963b475b7 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/download-mocks.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/json-viewer-intro.png b/content/ptfe-releases/v000011-1/img/docs/json-viewer-intro.png new file mode 100644 index 0000000000..4eb364c55a Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/json-viewer-intro.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/organization-vcs-general-aggregated-status-checks.png b/content/ptfe-releases/v000011-1/img/docs/organization-vcs-general-aggregated-status-checks.png new file mode 100644 index 0000000000..f4a82d0b26 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/organization-vcs-general-aggregated-status-checks.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/organization-vcs-general-non-aggregated-status-checks.png b/content/ptfe-releases/v000011-1/img/docs/organization-vcs-general-non-aggregated-status-checks.png new file mode 100644 index 0000000000..c328f6ce5c Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/organization-vcs-general-non-aggregated-status-checks.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/runs-confirm.png b/content/ptfe-releases/v000011-1/img/docs/runs-confirm.png new file mode 100644 index 0000000000..4e0f67cbe4 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/runs-confirm.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/sentinel-json-enter-filter.png b/content/ptfe-releases/v000011-1/img/docs/sentinel-json-enter-filter.png new file mode 100644 index 0000000000..aa466692bc Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/sentinel-json-enter-filter.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/sentinel-json-quick-filter.png b/content/ptfe-releases/v000011-1/img/docs/sentinel-json-quick-filter.png new file mode 100644 index 0000000000..89d4135702 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/sentinel-json-quick-filter.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/sentinel-view-json.png b/content/ptfe-releases/v000011-1/img/docs/sentinel-view-json.png new file mode 100644 index 0000000000..b107dd2647 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/sentinel-view-json.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-comments.png b/content/ptfe-releases/v000011-1/img/docs/service-now-comments.png new file mode 100644 index 0000000000..3c1587f52d Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-comments.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-apikey.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-apikey.png new file mode 100644 index 0000000000..ae921a6629 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-apikey.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-conditional-class-mapping.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-conditional-class-mapping.png new file mode 100644 index 0000000000..203e6d0cf0 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-conditional-class-mapping.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-deactivate-etl.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-deactivate-etl.png new file mode 100644 index 0000000000..7905293a69 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-deactivate-etl.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-design.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-design.png new file mode 100644 index 0000000000..98140a8aad Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-design.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-attribute-mapping.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-attribute-mapping.png new file mode 100644 index 0000000000..ebbb8e21a1 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-attribute-mapping.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-condition-update.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-condition-update.png new file mode 100644 index 0000000000..7fac298ed3 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-condition-update.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-editing-relationship.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-editing-relationship.png new file mode 100644 index 0000000000..33c18f0722 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-editing-relationship.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-setting-relationship.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-setting-relationship.png new file mode 100644 index 0000000000..16b6e5c765 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-etl-setting-relationship.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-import-set.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-import-set.png new file mode 100644 index 0000000000..745a6d302c Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-import-set.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-scheduled-import.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-scheduled-import.png new file mode 100644 index 0000000000..c7aa394cbe Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-scheduled-import.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-state-object-url.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-state-object-url.png new file mode 100644 index 0000000000..b687b2a90f Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-state-object-url.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-tags.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-tags.png new file mode 100644 index 0000000000..c5db95a3e3 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-tags.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-team-token-gen.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-team-token-gen.png new file mode 100644 index 0000000000..3e2de6f2b7 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-team-token-gen.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-tfconn.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-tfconn.png new file mode 100644 index 0000000000..34e8d9aef9 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-tfconn.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-schedule.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-schedule.png new file mode 100644 index 0000000000..d4e4701c71 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-schedule.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-tfc.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-tfc.png new file mode 100644 index 0000000000..b6aa99ef80 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-tfc.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-token.png b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-token.png new file mode 100644 index 0000000000..e65e962b78 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-service-graph-webhook-token.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-store.png b/content/ptfe-releases/v000011-1/img/docs/service-now-store.png new file mode 100644 index 0000000000..89483f4b2c Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-store.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-updated-config.png b/content/ptfe-releases/v000011-1/img/docs/service-now-updated-config.png new file mode 100644 index 0000000000..30f01cde82 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-updated-config.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/service-now-vcs-repository.png b/content/ptfe-releases/v000011-1/img/docs/service-now-vcs-repository.png new file mode 100644 index 0000000000..7280c87164 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/service-now-vcs-repository.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-add-variables-to-action.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-add-variables-to-action.png new file mode 100644 index 0000000000..a8347388c9 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-add-variables-to-action.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-adjust-script-variables.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-adjust-script-variables.png new file mode 100644 index 0000000000..90e1e4ebc3 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-adjust-script-variables.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-configure-item.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-configure-item.png new file mode 100644 index 0000000000..461b290b2d Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-configure-item.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copied-item.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copied-item.png new file mode 100644 index 0000000000..f29726c373 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copied-item.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copy-action.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copy-action.png new file mode 100644 index 0000000000..71ec9c7d0d Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copy-action.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copy-flow.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copy-flow.png new file mode 100644 index 0000000000..a1632b6c32 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-copy-flow.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-edit-flow.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-edit-flow.png new file mode 100644 index 0000000000..2c21653e95 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-edit-flow.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-fill-new-action-step.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-fill-new-action-step.png new file mode 100644 index 0000000000..bf51f5f65b Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-fill-new-action-step.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-get-variables.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-get-variables.png new file mode 100644 index 0000000000..94821fc4da Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-get-variables.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-new-varset-form.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-new-varset-form.png new file mode 100644 index 0000000000..d6bf2f3d65 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-new-varset-form.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-new-varset.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-new-varset.png new file mode 100644 index 0000000000..051ac6eba3 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-new-varset.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-open-action.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-open-action.png new file mode 100644 index 0000000000..fdc4f97274 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-open-action.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-original-flow.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-original-flow.png new file mode 100644 index 0000000000..2456b8bbe2 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-original-flow.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-process-engine.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-process-engine.png new file mode 100644 index 0000000000..979d5c3a70 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-process-engine.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-remove-example-variables-from-action.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-remove-example-variables-from-action.png new file mode 100644 index 0000000000..09d558eb39 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-remove-example-variables-from-action.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-remove-example-variables.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-remove-example-variables.png new file mode 100644 index 0000000000..214822eb84 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-remove-example-variables.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-rename-action.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-rename-action.png new file mode 100644 index 0000000000..cb18e2b96d Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-rename-action.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-replace-action.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-replace-action.png new file mode 100644 index 0000000000..2757f6cdce Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-replace-action.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-service-portal.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-service-portal.png new file mode 100644 index 0000000000..d54402d3ef Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-service-portal.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-update-process-engine.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-update-process-engine.png new file mode 100644 index 0000000000..1c3cbfdce8 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-update-process-engine.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-variables.png b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-variables.png new file mode 100644 index 0000000000..0a7aa95de8 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/servicenow-catalog-variables.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/terraform-cloud-run-tasks-diagram.png b/content/ptfe-releases/v000011-1/img/docs/terraform-cloud-run-tasks-diagram.png new file mode 100644 index 0000000000..f07ba3396f Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/terraform-cloud-run-tasks-diagram.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/tfc-explorer-health.png b/content/ptfe-releases/v000011-1/img/docs/tfc-explorer-health.png new file mode 100644 index 0000000000..de8f58bf5b Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/tfc-explorer-health.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/workspace-net-infra-combined.png b/content/ptfe-releases/v000011-1/img/docs/workspace-net-infra-combined.png new file mode 100644 index 0000000000..de0d770d54 Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/workspace-net-infra-combined.png differ diff --git a/content/ptfe-releases/v000011-1/img/docs/workspace-net-infra-split.png b/content/ptfe-releases/v000011-1/img/docs/workspace-net-infra-split.png new file mode 100644 index 0000000000..33bb2d03fb Binary files /dev/null and b/content/ptfe-releases/v000011-1/img/docs/workspace-net-infra-split.png differ