Vault-Backed Dynamic Credentials with the GCP Provider

Important: If using self-managed agents, make sure you’re using v1.8.0 or later.

Warning: Dynamic Credentials with the GCP provider do not work when your TFE instance is using a custom or self-signed certificate due to restrictions on GCP's end.

You can use Terraform Cloud’s native OpenID Connect integration with Vault to use Vault-backed dynamic credentials with the GCP provider in your Terraform Cloud runs. Configuring the integration requires the following steps:

Configure Vault Dynamic Provider Credentials: Set up a trust configuration between Vault and Terraform Cloud, create Vault roles and policies for your Terraform Cloud workspaces, and add environment variables to those workspaces.
Configure the Vault GCP Secrets Engine: Set up the GCP secrets engine in your Vault instance.
Configure Terraform Cloud: Add additional environment variables to the Terraform Cloud workspaces where you want to use Vault-Backed Dynamic Credentials.
Configure Terraform Providers: Configure your Terraform providers to work with Vault-backed dynamic credentials.

Once you complete this setup, Terraform Cloud 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 Terraform Cloud and Vault, and populating the required environment variables in your Terraform Cloud workspace.

See the setup instructions for Vault dynamic provider credentials.

Configure Vault GCP Secrets Engine

Follow the instructions in the Vault documentation for setting up the GCP secrets engine in your Vault instance. You can also do this configuration through Terraform. Refer to our example Terraform configuration.

Important: carefully consider the limitations and differences between each supported credential type in the GCP secrets engine. These limitations carry over to Terraform Cloud’s usage of these credentials for authenticating the GCP provider.

Configure Terraform Cloud

Next, you need to set certain environment variables in your Terraform Cloud workspace to authenticate Terraform Cloud with GCP using Vault-backed dynamic credentials. These variables are in addition to those you previously set while configuring Vault dynamic provider credentials. You can add these as workspace variables or as a variable set.

Common Environment Variables

The below variables apply to all GCP auth types.

Required Common Environment Variables

Variable	Value	Notes
`TFC_VAULT_BACKED_GCP_AUTH`	`true`	Must be present and set to `true`, or Terraform Cloud will not attempt to authenticate with GCP.
`TFC_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`.

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`	The mount path of the GCP secrets engine in Vault.	Defaults to `gcp`.

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`	The roleset to use in Vault.	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

You may need to set these variables, depending on your use case.

Variable	Value	Notes
`TFC_VAULT_BACKED_GCP_PLAN_VAULT_ROLESET`	The roleset to use for the plan phase of a run.	Will fall back to the value of `TFC_VAULT_BACKED_GCP_RUN_VAULT_ROLESET` if not provided.
`TFC_VAULT_BACKED_GCP_APPLY_VAULT_ROLESET`	The roleset to use for the apply phase of a run.	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`	The static account to use in Vault.	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

You may need to set these variables, depending on your use case.

Variable	Value	Notes
`TFC_VAULT_BACKED_GCP_PLAN_VAULT_STATIC_ACCOUNT`	The static account to use for the plan phase of a run.	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`	The static account to use for the apply phase of a run.	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 that you previously used to generate GCP credentials.