Use dynamic credentials with the GCP provider

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:

1. 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.
2. 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.

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 of TFC_GCP_WORKLOAD_IDENTITY_AUDIENCE, if configured.
• Provider attributes mapping: At the minimum this must include assertion.sub for the google.subject entry. Other mappings can be added for other claims in the identity token to attributes by adding attribute.[claim name] on the Google side and assertion.[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.

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

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:

1. By providing one unified variable containing the canonical name of the workload identity provider.
2. 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

Separate Variables

Optional Environment Variables

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

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

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.

variable "tfc_gcp_dynamic_credentials" {
  description = "Object containing GCP dynamic credentials configuration"
  type = object({
    default = object({
      credentials = string
    })
    aliases = map(object({
      credentials = string
    }))
  })
}

Example Usage

provider "google" {
  credentials = var.tfc_gcp_dynamic_credentials.default.credentials
}

provider "google" {
  alias = "ALIAS1"
  credentials = var.tfc_gcp_dynamic_credentials.aliases["ALIAS1"].credentials
}