diff --git a/website/content/docs/secrets/terraform.mdx b/website/content/docs/secrets/terraform.mdx index f3da5b0e0a..bff612db3d 100644 --- a/website/content/docs/secrets/terraform.mdx +++ b/website/content/docs/secrets/terraform.mdx @@ -58,7 +58,7 @@ management tool. desired User ID. ```shell-session - $ vault write terraform/role/my-role user_id=user-12345abcde + $ vault write terraform/role/my-role user_id=user-12345abcde credential_type=user Success! Data written to: terraform/role/my-role ``` @@ -81,21 +81,21 @@ token TJFDSIFDSKFEKZX.FKFKA.akjlfdiouajlkdakadfiowe token_id at-123acbdfask ``` -## Organization, team, and user roles +## Organization, legacy team, team, and user roles -HCP Terraform supports three distinct types of API tokens; Organizations, -Teams, and Users. Each token type has distinct access levels and generation -workflows. A given Vault role can manage any one of the three types at a time, -however there are important differences to be aware of. +HCP Terraform supports four distinct types of API tokens; Organizations, +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 +three types at a time, however there are important differences to be aware of. -### Organization and team roles +### Organization roles Generating a new Organization or Team API token by reading the credentials in Vault or otherwise generating them on [app.terraform.io](https://app.terraform.io/session) will effectively revoke **any** existing API token for that Organization or Team. -Due to this behavior, Organization and Team API tokens created by Vault will be +Due to this behavior, Organization API tokens created by Vault will be stored and returned on future requests, until the credentials get rotated. This is to prevent unintentional revocation of tokens that are currently in-use. @@ -103,7 +103,7 @@ 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}" +$ 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 @@ -152,18 +152,78 @@ token token_id at-fqvtdTQ5kQWcjUfG ``` -Please see the [HCP Terraform API -Token documentation for more -information](/terraform/cloud-docs/users-teams-organizations/api-tokens). +### Team roles -## Tutorial +The HCP Terraform secret engine creates dynamic Team API tokens by +configuring a Vault role to manage an existing HCP Terraform Team. +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 +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`. -Refer to [HCP Terraform Secrets -Engine](/vault/tutorials/secrets-management/terraform-secrets-engine) -for a step-by-step tutorial. +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. -## API +Below is an example of creating a Vault role to manage manage User API tokens: -The HCP Terraform secrets engine has a full HTTP API. Please see the -[HCP Terraform secrets engine API](/vault/api-docs/secret/terraform) for more -details. +```shell-session +$ 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 +``` + +The API token is retrieved by reading the credentials for the role: + +```shell-session +$ vault read terraform/creds/team-testing + +Key Value +--- ----- +lease_id terraform/creds/team-testing/4oNxB4X0x77IrP51lBMJBiJi +lease_duration 3m20s +lease_renewable true +description testing token(74) +expired_at 2025-05-01T20:10:55Z +token +token_id at-GDMeMTvn3NhUernt +``` + +### Legacy team roles (Deprecated) + +The HCP Terraform API limits Legacy Team roles to **one active +token at any given time**. Generating a new Legacy Team API token by +reading the credentials in Vault or otherwise generating them on +[app.terraform.io](https://app.terraform.io/session) will effectively revoke **any** +existing API token for that Team. + +Due to this behavior, Team API tokens created by Vault will be stored and +returned on future requests, until the credentials get rotated. This +is to prevent unintentional revocation of tokens that are currently in-use. + +Below is an example of creating a Vault role to manage a Legacy Team API token and +rotating the token: + +```shell-session +$ 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 +Success! Data written to: terraform/rotate-role/legacy-team +``` + +The API token is retrieved by reading the credentials for the role: + +```shell-session +$ vault read terraform/creds/legacy-team + +Key Value +--- ----- +organization n/a +role legacy-team +team_id team- +token +token_id at-fqvtdTQ5kQWcjUfG +```