Vault-Backed Dynamic Credentials with the GCP Provider
Important: If you are self-hosting HCP Terraform agents, ensure your agents use v1.8.0 or above. To use the latest dynamic credentials features, upgrade your agents to the latest version.
You can use HCP Terraform’s native OpenID Connect integration with Vault to use Vault-backed dynamic credentials with the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps:
- 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.
- Configure the Vault GCP Secrets Engine: Set up the GCP secrets engine in your Vault instance.
- Configure HCP Terraform: Add additional environment variables to the HCP Terraform 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, 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.
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 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. You can add these as workspace variables or as 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 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. | 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
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
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
that you previously used to generate GCP credentials.
Specifying Multiple Configurations
Important: If you are self-hosting HCP Terraform agents, ensure your agents use v1.12.0 or above. To use the latest dynamic credentials features, upgrade your agents to the latest version.
You can add additional variables to handle multiple distinct Vault-backed GCP setups, enabling you to use multiple provider aliases 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.
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.
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
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
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}