Dynamic Credentials with the HCP Provider

You can use HCP Terraform’s native OpenID Connect integration with HCP to authenticate with the HCP provider using dynamic credentials in your HCP Terraform runs. Configuring dynamic credentials for the HCP provider requires the following steps:

1. Configure HCP: Set up a trust configuration between HCP and HCP Terraform. Then, you must create a service principal in HPC 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 HCP during each run.

Configure HCP

You must enable and configure a workload identity pool and provider on HCP. These instructions use the HCP CLI, but you can also use Terraform to configure HCP. Refer to our example Terraform configuration.

Create a Service Principal

Create a service principal for HCP Terraform to assume during runs by running the following HCP command. Note the ID of the service principal you create because you will need it in the following steps. For all remaining steps, replace HCP_PROJECT_ID with the ID of the project that contains all the resources and workspaces that you want to manage with this service principal. If you wish to manage more than one project with dynamic credentials, it is recommended that you create multiple service principals, one for each project.

hcp iam service-principals create hcp-terraform --project=HCP_PROJECT_ID

Grant your service principal the necessary permissions to manage your infrastructure during runs.

hcp projects add-binding \
  --project=HCP_PROJECT_ID \
  --member=HCP_PRINCIPAL_ID \
  --role=roles/contributor

Add a Workload Identity Provider

Next, create a workload identity provider that HCP uses to authenticate the HCP Terraform run. Make sure to replace HCP_PROJECT_ID, ORG_NAME, PROJECT_NAME, and WORKSPACE_NAME with their respective values before running the command.

hcp iam workload-identity-providers create-oidc hcp-terraform-dynamic-credentials \
  --service-principal=iam/project/HCP_PROJECT_ID/service-principal/hcp-terraform \
  --issuer=https://app.terraform.io \
  --allowed-audience=hcp.workload.identity
  --conditional-access='jwt_claims.sub matches `^organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:.*`' \
  --description="Allow HCP Terraform agents to act as the hcp-terraform service principal"

Configure HCP Terraform

Next, you need to set environment variables in your HCP Terraform workspace to configure HCP Terraform to authenticate with HCP using dynamic credentials. You can set these as workspace variables or use a variable set to share one HCP service principal across multiple workspaces. 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

Optional Environment Variables

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

Configure the HCP Provider

Do not set the HCP_CRED_FILE environment variable when configuring the HCP provider, or HCP_CRED_FILE will conflict with the dynamic credentials authentication process.

Specifying Multiple Configurations

You can add additional variables to handle multiple distinct HCP 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, refer to Specifying Multiple Configurations.

Required Terraform Variable

Add the following variable to your Terraform configuration to set up additional dynamic credential configurations with the HCP provider. This variable lets HCP Terraform supply variable values that you can then use to map authentication and configuration details to the correct provider blocks.

variable "tfc_hcp_dynamic_credentials" {
  description = "Object containing HCP dynamic credentials configuration"
  type = object({
    default = object({
      credential_file = string
    })
    aliases = map(object({
      credential_file = string
    }))
  })
}

Example Usage

provider "hcp" {
  credential_file = var.tfc_hcp_dynamic_credentials.default.credential_file
}

provider "hcp" {
  alias = "ALIAS1"
  credential_file = var.tfc_hcp_dynamic_credentials.aliases["ALIAS1"].credential_file
}