Dynamic Credentials with the GCP Provider
Important: If you are self-hosting HCP Terraform agents, ensure your agents use v1.7.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 GCP to get dynamic credentials for the GCP provider in your HCP Terraform runs. Configuring the integration requires the following steps:
- 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.
- 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.
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.
Before starting to create the resources, you must enable the APIs mentioned at the start of the Configure workload Identity federation.
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 https://app.terraform.io
- 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 ofTFC_GCP_WORKLOAD_IDENTITY_AUDIENCE
, if configured.
- Important: you must select the
- Provider attributes mapping: At the minimum this must include
assertion.sub
for thegoogle.subject
entry. Other mappings can be added for other claims in the identity token to attributes by addingattribute.[claim name]
on the Google side andassertion.[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.
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.
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.
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 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 |
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:
- By providing one unified variable containing the canonical name of the workload identity provider.
- 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 | 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 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, 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 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.
Example Usage