COS

Stores the state as an object in a configurable prefix in a given bucket on Tencent Cloud Object Storage (COS).

This backend supports state locking. Storing your state in a COS bucket requires the following permissions:

CreateTag, DeleteTag, and DescribeTags on the tag key tencentcloud-terraform-lock
Put, Get, and Delete files for the specified bucket's prefix

Warning! It is highly recommended that you enable Object Versioning on the COS bucket to allow for state recovery in the case of accidental deletions and human error.

Example Configuration

terraform {
  backend "cos" {
    region = "ap-guangzhou"
    bucket = "bucket-for-terraform-state-1258798060"
    prefix = "terraform/state"
  }
}

This assumes we have a COS Bucket created named bucket-for-terraform-state-1258798060, Terraform state will be written into the file terraform/state/terraform.tfstate.

Data Source Configuration

To make use of the COS remote state in another configuration, use the terraform_remote_state data source.

data "terraform_remote_state" "foo" {
  backend = "cos"

  config = {
    region = "ap-guangzhou"
    bucket = "bucket-for-terraform-state-1258798060"
    prefix = "terraform/state"
  }
}

Configuration Variables

Warning: We recommend using environment variables to supply credentials and other sensitive data. If you use -backend-config or hardcode these values directly in your configuration, Terraform will include these values in both the .terraform subdirectory and in plan files. Refer to Credentials and Sensitive Data for details.

The following configuration options or environment variables are supported:

secret_id - (Optional) Secret id of Tencent Cloud. It supports environment variables TENCENTCLOUD_SECRET_ID.
secret_key - (Optional) Secret key of Tencent Cloud. It supports environment variables TENCENTCLOUD_SECRET_KEY.
security_token - (Optional) TencentCloud Security Token of temporary access credentials. It supports environment variables TENCENTCLOUD_SECURITY_TOKEN.
region - (Optional) The region of the COS bucket. It supports environment variables TENCENTCLOUD_REGION.
bucket - (Required) The name of the COS bucket. You shall manually create it first.
prefix - (Optional) The directory for saving the state file in bucket. Default to "env:".
key - (Optional) The path for saving the state file in bucket. Defaults to terraform.tfstate.
encrypt - (Optional) Whether to enable server side encryption of the state file. If it is true, COS will use 'AES256' encryption algorithm to encrypt state file.
acl - (Optional) Object ACL to be applied to the state file, allows private and public-read. Defaults to private.
accelerate - (Optional) Whether to enable global Acceleration. Defaults to false.
endpoint - (Optional) The Custom Endpoint for the COS backend. It supports the environment variable TENCENTCLOUD_ENDPOINT.
domain - (Optional) The root domain of the API request. Defaults to tencentcloudapi.com. It supports the environment variable TENCENTCLOUD_DOMAIN.

Assume Role

If provided with an assume role, Terraform will attempt to assume this role using the supplied credentials. Assume role can be provided by adding an assume_role block in the cos backend block.

assume_role - (Optional) The assume_role block. If provided, terraform will attempt to assume this role using the supplied credentials.

The details of assume_role block as following:

role_arn - (Required) The ARN of the role to assume. It can be sourced from the TENCENTCLOUD_ASSUME_ROLE_ARN.
session_name - (Required) The session name to use when making the AssumeRole call. It can be sourced from the TENCENTCLOUD_ASSUME_ROLE_SESSION_NAME.
session_duration - (Required) The duration of the session when making the AssumeRole call. Its value ranges from 0 to 43200(seconds), and default is 7200 seconds. It can be sourced from the TENCENTCLOUD_ASSUME_ROLE_SESSION_DURATION.
policy - (Optional) A more restrictive policy when making the AssumeRole call. Its content must not contains principal elements. Notice: more syntax references, please refer to: policies syntax logic.

Usage:

terraform {
  backend "cos" {
    region = "ap-guangzhou"
    bucket = "bucket-for-terraform-state-{appid}"
    prefix = "terraform/state"
    assume_role {
      role_arn = "qcs::cam::uin/xxx:roleName/yyy"
      session_name = "my-session-name"
      session_duration = 3600
    }
  }
}

In addition, these assume_role configurations can also be provided by environment variables.

Usage:

$ export TENCENTCLOUD_SECRET_ID="my-secret-id"
$ export TENCENTCLOUD_SECRET_KEY="my-secret-key"
$ export TENCENTCLOUD_REGION="ap-guangzhou"
$ export TENCENTCLOUD_ASSUME_ROLE_ARN="qcs::cam::uin/xxx:roleName/yyy"
$ export TENCENTCLOUD_ASSUME_ROLE_SESSION_NAME="my-session-name"
$ export TENCENTCLOUD_ASSUME_ROLE_SESSION_DURATION=3600
$ terraform plan

Endpoint

If provided with an endpoint URL, Terraform will attempt to access the COS backend by the endpoint configuration or the environment variable TENCENTCLOUD_ENDPOINT.

A typical endpoint looks like this: http://cos-internal.{Region}.tencentcos.cn. Both HTTP and HTTPS are accepted.

Usage:

terraform {
  backend "cos" {
    region   = "ap-guangzhou"
    bucket   = "bucket-for-terraform-state-1258798060"
    prefix   = "terraform/state"
    endpoint = "http://cos-internal.ap-guangzhou.tencentcos.cn"
  }
}