diff --git a/content/vault/v1.21.x/content/docs/secrets/terraform.mdx b/content/vault/v1.21.x/content/docs/secrets/terraform.mdx index fca9c76b7b..b4ef09ed2a 100644 --- a/content/vault/v1.21.x/content/docs/secrets/terraform.mdx +++ b/content/vault/v1.21.x/content/docs/secrets/terraform.mdx @@ -22,8 +22,7 @@ features that require them, if any. ## Quick start Most secrets engines must be configured in advance before they can perform their -functions. These steps are usually completed by an operator or configuration -management tool. +functions. An operator or configuration management tool usually completes these steps. 1. Enable the HCP Terraform secrets engine: @@ -39,46 +38,70 @@ management tool. ```shell-session $ vault write terraform/config \ - token=Vhz7652ba4c-0f6e-8e75-5724-5e083d72cfe4 + token= Success! Data written to: terraform/config ``` + Specify the `address` parameter when configuring Terraform Enterprise to + override the default `https://app.terraform.io`: + + ```shell-session + $ vault write terraform/config \ + address="https://tfe.example.com" \ + token= + Success! Data written to: terraform/config + ``` + See [HCP Terraform's documentation on API tokens](/terraform/cloud-docs/users-teams-organizations/api-tokens) - to determine the appropriate API token for use with the secret engine. In - order to perform all operations, a User API token is recommended. - -3. Configure a role that maps a name in Vault to a HCP Terraform user. At - this time the HCP Terraform API does not allow dynamic user generation. As - a result this secret engine creates dynamic API tokens for an existing user, - and manages the lifecycle of that API token. You will need to know the User - ID in order to generate User API tokens for that user. You can use the - HCP Terraform [Account - API](/terraform/cloud-docs/api-docs/account) to find the - desired User ID. + to determine the appropriate API token for use with the Terraform plugin. + Choose a token that matches your intended scope. See + [Organization, legacy team, team, and user roles](#organization-legacy-team-team-and-user-roles) + section for additional considerations. + +3. Configure a role for an HCP Terraform Team + + Vault issues dynamic API tokens by mapping the Terraform secret role to an existing HCP Terraform + team. Vault also manages the API token lifecycle and automatically expires the token according + to the `ttl` and `max_ttl` setting on the role. + + You need to know your Terraform team ID or user ID to generate API tokens for that client: + - To find your team ID, use the + [HCP Terraform Teams API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/teams) + or navigate to the **Teams** section in the HCP Terraform GUI. + - To find a user ID, use the + [Account Details + API](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/account#show-the-current-user) + or check your user profile in the HCP Terraform GUI. ```shell-session - $ vault write terraform/role/my-role user_id=user-12345abcde credential_type=user - Success! Data written to: terraform/role/my-role + $ vault write terraform/role/my-team-role \ + team_id=team-12345abcde \ + credential_type=team \ + description="CI/CD automation token" \ + ttl=300 \ + max_ttl=1800 + Success! Data written to: terraform/role/my-team-role ``` ## Usage -After the secrets engine is configured and a user/machine has a Vault token with -the proper permission, it can generate credentials. +After the secrets engine is configured, a Vault token with the proper permissions can generate +short-lived Team API tokens. -Generate a new credential by reading from the `/creds` endpoint with the name -of the role: +Generate a new token by calling the `/creds` endpoint with the role name: ```shell-session -$ vault read terraform/creds/my-role +$ vault read terraform/creds/my-team-role Key Value --- ----- -lease_id terraform/creds/my-user/A_LEASE_ID_PdvmJjACTtKrY2I -lease_duration 180s +lease_id terraform/creds/my-team-role/A_LEASE_ID_abc123 +lease_duration 300s lease_renewable true -token TJFDSIFDSKFEKZX.FKFKA.akjlfdiouajlkdakadfiowe -token_id at-123acbdfask +token tftk.abcdef1234567890 +token_id at-456defghi789 +description CI/CD automation token(42) +expired_at 2025-11-08T21:30:00Z ``` ## Organization, legacy team, team, and user roles @@ -88,6 +111,14 @@ Teams, Legacy Team Tokens and Users. Each token type has distinct access levels and generation workflows. A given Vault role can manage any one of the supported types at a time, however there are important differences to be aware of. +When you select an anchor credential for the Terraform plugin, always choose a +token with a scope that matches your intended use case. +User tokens should only have permission to manage the resources owned by that +user. Team tokens should only have permission to manage team-level resources +owned by that team. Only create tokens with cross-team permissions when a more +narrowly-defined scope prevents Vault from issuing appropriate tokens or +interferes with your intended workflows. + ### Organization roles Generating a new Organization API token by reading the credentials in @@ -103,7 +134,9 @@ Below is an example of creating a Vault role to manage an Organization API token and rotating the token: ```shell-session -$ vault write terraform/role/testing organization="${TF_ORGANIZATION}" credential_type=organization +$ vault write terraform/role/testing \ + organization="${TF_ORGANIZATION}" \ + credential_type=organization Success! Data written to: terraform/role/testing $ vault write -f terraform/rotate-role/testing @@ -112,7 +145,7 @@ Success! Data written to: terraform/rotate-role/testing The API token is retrieved by reading the credentials for the role: -``` +```shell-session $ vault read terraform/creds/testing Key Value @@ -125,24 +158,27 @@ token_id at-fqvtdTQ5kQWcjUfG ### User roles -Traditionally, Vault secret engines create dynamic users and dynamic credentials -along with them. At the time of writing, the HCP Terraform API does not allow -for creating dynamic users. Instead, the HCP Terraform secret engine creates -dynamic User API tokens by configuring a Vault role to manage an existing -HCP Terraform user. The lifecycle of these tokens is managed by Vault and -will auto expire according to the configured TTL and max TTL of the Vault -role. +Traditionally, Vault secrets engines create dynamic users and credentials for those users. +The HCP Terraform API does not support creating dynamic users so the Terraform +plugin issues dynamic User API tokens by configuring Vault roles to manage +existing HCP Terraform users. +Vault manages the lifecycle of user tokens and automatically expires them based +on the `ttl` and `max_ttl` values of the role. Vault scopes User API tokens to +the individual user account. As a result, the associated account cannot create +or manage tokens for other users. Use a team API token if you need Vault to +issue tokens that operate across teams or support automation workflows. -Below is an example of creating a Vault role to manage manage User API tokens: +The `terraform/role/{user}` endpoint can create a Vault role to manage User API tokens. For example: ```shell-session -$ vault write terraform/role/user-testing user_id="${TF_USER_ID}" +$ vault write terraform/role/user-testing \ + user_id="${TF_USER_ID}" Success! Data written to: terraform/role/user-testing ``` -The API token is retrieved by reading the credentials for the role: +Retrieve the API token by reading the credentials for the role: -``` +```shell-session $ vault read terraform/creds/user-testing Key Value @@ -160,18 +196,23 @@ The lifecycle of these tokens is managed by Vault and/or HCP Terraform. Generally, Vault aims to manage tokens in external APIs with revoke actions taken according to `ttl` and `max_ttl` settings. In addition to that behavior, using the `max_ttl` Vault will set an `ExpiredAt` date in HCP Terraform -which will ensure the token expires at the Max TTL time. This prevents +which ensures that the token expires at the `max_ttl` time and prevents Team tokens living past their `max_ttl` if Vault is unable to revoke the token. Omitting the `max_ttl` value will default to Vault's system `max_ttl`. In HCP Terraform, team tokens cannot have matching descriptions. In order to avoid -collisions, the secret engine generates a random string as a suffix to the description. It is -highly recommended you set an additional description. +collisions, the secret engine generates a random string as a suffix to the description. +We highly recommended setting an additional description. -Below is an example of creating a Vault role to manage manage Team API tokens: +For example, to set a description when you create a Vault role to manage Team API tokens, use the `description` parameter: ```shell-session -$ vault write terraform/role/team-testing team_id="${TF_TEAM_ID}" credential_type=team description="testing token" ttl=200 max_ttl=600 +$ vault write terraform/role/team-testing \ + team_id="${TF_TEAM_ID}" \ + credential_type=team \ + description="testing token" \ + ttl=200 \ + max_ttl=600 Success! Data written to: terraform/role/team-testing ``` @@ -207,7 +248,9 @@ Below is an example of creating a Vault role to manage a Legacy Team API token a rotating the token: ```shell-session -$ vault write terraform/role/legacy-team team_id="${TF_TEAM_ID}" credential_type=team_legacy +$ vault write terraform/role/legacy-team \ + team_id="${TF_TEAM_ID}" \ + credential_type=team_legacy Success! Data written to: terraform/role/legacy-team $ vault write -f terraform/rotate-role/legacy-team