Use dynamic credentials with the Tencent Cloud provider

You can use HCP Terraform's native OpenID Connect integration with Tencent Cloud to get dynamic credentials for the Tencent Cloud provider in your HCP Terraform runs. Configuring the integration requires the following steps:

1. Configure Tencent Cloud: Set up a trust configuration between Tencent Cloud and HCP Terraform. Then, you must create Tencent Cloud Cloud Access Management (CAM) 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.

If you are configuring a Stack, refer to Authenticate a Stack to learn about the workflow of authenticating your Stack deployments with dynamic credentials.

Once you complete the setup, HCP Terraform automatically authenticates to Tencent Cloud during each run. The Tencent Cloud provider authentication is valid for the length of the plan or apply.

Requirements for agents

If you are self-hosting HCP Terraform agents, ensure your agents use v1.28.8 or above. To use the latest dynamic credentials features, upgrade your agents to the latest version.

Configure Tencent Cloud

You must enable and configure a CAM OIDC identity provider and accompanying role and trust policy on Tencent Cloud. These instructions use the Tencent Cloud console, but you can also use Terraform to configure Tencent Cloud.

Create a CAM OIDC Identity Provider

Tencent Cloud documentation for setting this up through the console can be found here: Creating an OIDC Identity Provider.

Configure the OIDC identity provider with the following settings:

• Identity provider name: A name for the provider, such as hcp-terraform.
• Identity provider URL: The address of HCP Terraform (e.g., https://app.terraform.io). Make sure this value starts with https:// and does not have a trailing slash.
• Client ID: Set this to tencentcloud.workload.identity. If you want to use a different Client ID, you must also set the TFC_TENCENTCLOUD_WORKLOAD_IDENTITY_AUDIENCE environment variable when you configure HCP Terraform in the next step.

Configure a CAM Role and Trust Policy

You must create a CAM role that trusts the OIDC identity provider you created above. Refer to Creating a Role for an Identity Provider in the Tencent Cloud documentation for instructions.

The following example shows the trust policy format:

{
    "version": "2.0",
    "statement": [
        {
            "effect": "allow",
            "action": "name/sts:AssumeRoleWithWebIdentity",
            "principal": {
                "federated": [
                    "qcs::cam::uin/ACCOUNT_ID:oidc-provider/PROVIDER_NAME"
                ]
            },
            "condition": {
                "string_equal": {
                    "oidc:aud": "AUDIENCE_VALUE",
                    "oidc:sub": "organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:RUN_PHASE"
                }
            }
        }
    ]
}

Replace the capitalized values with the following:

• ACCOUNT_ID: Your Tencent Cloud account UIN
• PROVIDER_NAME: The name of the OIDC identity provider created in the previous step
• AUDIENCE_VALUE: This should be set to tencentcloud.workload.identity unless a non-default audience has been specified in HCP Terraform
• ORG_NAME: The organization name this policy will apply to, such as my-org-name
• PROJECT_NAME: The project name that this policy will apply to, such as my-project-name
• WORKSPACE_NAME: The workspace name this policy will apply to, such as my-workspace-name
• RUN_PHASE: The run phase this policy will apply to, currently one of plan or apply.

If you wish to configure the same permissions regardless of run phase, then you must modify the condition to match the example below, which uses string_like for the sub and includes a * after run_phase: to perform a wildcard match:

{
    "condition": {
        "string_equal": {
            "oidc:aud": "AUDIENCE_VALUE"
        },
        "string_like": {
            "oidc:sub": "organization:ORG_NAME:project:PROJECT_NAME:workspace:WORKSPACE_NAME:run_phase:*"
        }
    }
}

You must also add a permissions policy to the role, which defines what operations within Tencent Cloud the role is allowed to perform. As an example, the below policy allows read-only access to Cloud Object Storage (COS):

{
    "version": "2.0",
    "statement": [
        {
            "effect": "allow",
            "action": [
                "cos:GetBucket",
                "cos:HeadBucket"
            ],
            "resource": "*"
        }
    ]
}

Configure HCP Terraform

If you are configuring a Stack, refer to Authenticate a Stack to learn how to use the identity_token block to authenticate your Stack deployments with dynamic credentials.

You'll need to set some environment variables in your HCP Terraform workspace in order to configure HCP Terraform to authenticate with Tencent Cloud using dynamic credentials. You can set these as workspace variables, or if you'd like to share one Tencent Cloud role 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

Optional Environment Variables

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

Configure the Tencent Cloud Provider

Make sure that you're passing values for the region argument into the provider configuration block or setting the TENCENTCLOUD_REGION environment variable in your workspace.

Make sure that you're not setting values for the TENCENTCLOUD_SECRET_ID or TENCENTCLOUD_SECRET_KEY environment variables as these will conflict with the dynamic credentials authentication process.

The following example shows a basic Terraform configuration that uses dynamic credentials to authenticate to Tencent Cloud:

provider "tencentcloud" {
  region = "ap-guangzhou"

  assume_role_with_web_identity {
    # HCP Terraform automatically sets these during runs
  }
}

Specifying Multiple Configurations

You can add additional variables to handle multiple distinct Tencent Cloud 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_tencentcloud_dynamic_credentials" {
  description = "Object containing Tencent Cloud dynamic credentials configuration"
  type = object({
    default = object({
      role_arn_file    = string
      web_identity_token_file = string
    })
    aliases = map(object({
      role_arn_file    = string
      web_identity_token_file = string
    }))
  })
}

Example Usage

provider "tencentcloud" {
  region = "ap-guangzhou"

  assume_role_with_web_identity {
    role_arn_file           = var.tfc_tencentcloud_dynamic_credentials.default.role_arn_file
    web_identity_token_file = var.tfc_tencentcloud_dynamic_credentials.default.web_identity_token_file
  }
}

provider "tencentcloud" {
  alias  = "ALIAS1"
  region = "ap-shanghai"

  assume_role_with_web_identity {
    role_arn_file           = var.tfc_tencentcloud_dynamic_credentials.aliases["ALIAS1"].role_arn_file
    web_identity_token_file = var.tfc_tencentcloud_dynamic_credentials.aliases["ALIAS1"].web_identity_token_file
  }
}