Dynamic Credentials with the GCP Provider
Important: If using self-managed agents, make sure you’re using v1.7.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 GCP to get dynamic credentials for the GCP provider in your Terraform Cloud runs. Configuring the integration requires the following steps:
- Configure GCP: Set up a trust configuration between GCP and Terraform Cloud. Then, you must create GCP roles and policies for your Terraform Cloud workspaces.
- Configure Terraform Cloud: Add environment variables to the Terraform Cloud workspaces where you want to use Dynamic Credentials.
Once you complete the setup, Terraform Cloud automatically authenticates to GCP during each run. The GCP provider authentication is valid for the length of the plan or apply.
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 TFC 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 Terraform Cloud 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 Terraform Cloud
You’ll need to set some environment variables in your Terraform Cloud workspace in order to configure Terraform Cloud 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.
Required Environment Variables
Variable | Value | Notes |
---|---|---|
TFC_GCP_PROVIDER_AUTH | true | Must be present and set to true , or Terraform Cloud will not attempt to use dynamic credentials to authenticate to GCP. |
TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL | The service account email Terraform Cloud will use when authenticating to GCP. | 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 Terraform Cloud 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 | The canonical name of the workload identity provider. This must be in the form mentioned for the name attribute here | 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 | The project number where the pool and other resources live. | This is not the project ID and is a separate number. |
TFC_GCP_WORKLOAD_POOL_ID | The workload pool ID. | |
TFC_GCP_WORKLOAD_PROVIDER_ID | The workload identity provider ID. |
Optional Environment Variables
You may need to set these variables, depending on your use case.
Variable | Value | Notes |
---|---|---|
TFC_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. | This is one of the default aud formats that GCP accepts. |
TFC_GCP_PLAN_SERVICE_ACCOUNT_EMAIL | The service account email to use for the plan phase of a run. | Will fall back to the value of TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL if not provided. |
TFC_GCP_APPLY_SERVICE_ACCOUNT_EMAIL | The service account email to use for the apply phase of a run. | 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.