Specify multiple dynamic credential configurations

You can create multiple dynamic credential configurations of the same provider in a workspace.

Each configuration generates a distinct workload identity token, allowing you to create aliases for different provider configurations within the same workspace. You can specify unique audience values per configuration, and manually generate multiple tokens.

Specifying multiple dynamic credential configurations in HCP Terraform builds on the existing method of providing each provider's environment variables to a workspace. The process requires mapping well-known authentication input variables to the correct providers.

Configure HCP Terraform

You can specify additional dynamic credentials configurations by defining and appending a “tag” to the end of your existing required environment variables: [DYNAMIC_CREDENTIALS_VAR_NAME]_[YOUR_TAG].

Your tag can only contain letters, numbers, and underscores and can not use reserved keywords. The following keywords are reserved: TYPE.

Example

Using Vault's dynamic credentials setup as an example, we can create additional configurations by setting new tagged variables that match Vault's required environment variables. So, if you want to add a configuration with the tag ALIAS1, you must set environment variables for TFC_VAULT_PROVIDER_AUTH_ALIAS1, TFC_VAULT_ADDR_ALIAS1, and TFC_VAULT_RUN_ROLE_ALIAS1.

Default Values for Multiple Configurations

Each environment variable has a corresponding default variable which you can use to share values across multiple configurations. In this way, you can set values common to multiple configurations a single time, rather than repeating them for each configuration. If you explicitly set the corresponding environment variable in addition to the default variable, the explicit value is given precedence.

Example

In the example above, if each of your Vault configurations used the same underlying Vault instance, you could define the Vault address a single time using the TFC_DEFAULT_VAULT_ADDR variable, and omit TFC_VAULT_ADDR and TFC_VAULT_ADDR_ALIAS1. If you add a third Vault configuration for a different Vault instance with the tag ALIAS2, you could set the variable TFC_VAULT_ADDR_ALIAS2 to override the Vault address specifically for the ALIAS2 configuration.

Configure Terraform Code

Each supported provider has input variables you must declare in your Terraform code to use dynamic credentials with that provider. Each dynamic provider's documentation page lists the required variables for that provider. HCP Terraform provides values for these variables during runs, which you can use to authenticate HCP Terraform with providers using dynamic credentials.

Use the input variable values that HCP Terraform provides to map configuration values to the correct provider blocks. Authentication information for the default provider exists in a variable's top-level default object, while each additional configuration exists under a variable's aliases map. HCP Terraform generates the keys of the aliases map based on the tag you define in your HCP Terraform configuration.

Example

Continuing from the example above, after setting the required environment variables for your provider, add the following code to your Terraform configuration. This lets HCP Terraform supply variable values that you can use to map authentication and configuration details to the correct provider blocks.

variable "tfc_vault_dynamic_credentials" {
  description = "Object containing Vault dynamic credentials configuration"
  type = object({
    default = object({
      token_filename = string
      address = string
      namespace = string
      ca_cert_file = string
    })
    aliases = map(object({
      token_filename = string
      address = string
      namespace = string
      ca_cert_file = string
    }))
  })
}

Use the above object to map authentication information to the correct provider block. For this example, index into the aliases map with your alias's tag (ALIAS1) and the default provider object.

provider "vault" {
  // Set this to true as HCP Terraform manages the token lifecycle
  skip_child_token = true
  address = var.tfc_vault_dynamic_credentials.default.address
  namespace = var.tfc_vault_dynamic_credentials.default.namespace

  auth_login_token_file {
    filename = var.tfc_vault_dynamic_credentials.default.token_filename
  }
}

provider "vault" {
  // Set this to true as HCP Terraform manages the token lifecycle
  skip_child_token = true
  alias = "ALIAS1"
  address = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].address
  namespace = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].namespace

  auth_login_token_file {
    filename = var.tfc_vault_dynamic_credentials.aliases["ALIAS1"].token_filename
  }
}