github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/website/docs/language/settings/backends/cos.mdx (about)

     1  ---
     2  page_title: 'Backend Type: cos'
     3  description: >-
     4    Terraform can store the state remotely, making it easier to version and work
     5    with in a team.
     6  ---
     7  
     8  # COS
     9  
    10  Stores the state as an object in a configurable prefix in a given bucket on [Tencent Cloud Object Storage](https://intl.cloud.tencent.com/product/cos) (COS).
    11  
    12  This backend supports [state locking](/terraform/language/state/locking). Storing your state in a COS bucket requires the following permissions:
    13  
    14  - `CreateTag`, `DeleteTag`, and `DescribeTags` on the tag key `tencentcloud-terraform-lock`
    15  - `Put`, `Get`, and `Delete` files for the specified bucket's prefix
    16  
    17  ~> **Warning!** It is highly recommended that you enable [Object Versioning](https://intl.cloud.tencent.com/document/product/436/19883)
    18  on the COS bucket to allow for state recovery in the case of accidental deletions and human error.
    19  
    20  ## Example Configuration
    21  
    22  ```hcl
    23  terraform {
    24    backend "cos" {
    25      region = "ap-guangzhou"
    26      bucket = "bucket-for-terraform-state-1258798060"
    27      prefix = "terraform/state"
    28    }
    29  }
    30  ```
    31  
    32  This assumes we have a [COS Bucket](https://registry.terraform.io/providers/tencentcloudstack/tencentcloud/latest/docs/resources/cos_bucket) created named `bucket-for-terraform-state-1258798060`,
    33  Terraform state will be written into the file `terraform/state/terraform.tfstate`.
    34  
    35  ## Data Source Configuration
    36  
    37  To make use of the COS remote state in another configuration, use the [`terraform_remote_state` data source](/terraform/language/state/remote-state-data).
    38  
    39  ```hcl
    40  data "terraform_remote_state" "foo" {
    41    backend = "cos"
    42  
    43    config = {
    44      region = "ap-guangzhou"
    45      bucket = "bucket-for-terraform-state-1258798060"
    46      prefix = "terraform/state"
    47    }
    48  }
    49  ```
    50  
    51  ## Configuration Variables
    52  
    53  !> **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](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
    54  
    55  The following configuration options or environment variables are supported:
    56  
    57  - `secret_id` - (Optional) Secret id of Tencent Cloud. It supports environment variables `TENCENTCLOUD_SECRET_ID`.
    58  - `secret_key` - (Optional) Secret key of Tencent Cloud. It supports environment variables `TENCENTCLOUD_SECRET_KEY`.
    59  - `security_token` - (Optional) TencentCloud Security Token of temporary access credentials. It supports environment variables `TENCENTCLOUD_SECURITY_TOKEN`.
    60  - `region` - (Optional) The region of the COS bucket. It supports environment variables `TENCENTCLOUD_REGION`.
    61  - `bucket` - (Required) The name of the COS bucket. You shall manually create it first.
    62  - `prefix` - (Optional) The directory for saving the state file in bucket. Default to "env:".
    63  - `key` - (Optional) The path for saving the state file in bucket. Defaults to `terraform.tfstate`.
    64  - `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.
    65  - `acl` - (Optional) Object ACL to be applied to the state file, allows `private` and `public-read`. Defaults to `private`.
    66  - `accelerate` - (Optional) Whether to enable global Acceleration. Defaults to `false`.
    67  
    68  ### Assume Role
    69  If provided with an assume role, Terraform will attempt to assume this role using the supplied credentials.
    70  Assume role can be provided by adding an `assume_role` block in the cos backend block.
    71  
    72  - `assume_role` - (Optional) The `assume_role` block. If provided, terraform will attempt to assume this role using the supplied credentials.
    73  
    74  The details of `assume_role` block as following:
    75  - `role_arn` - (Required) The ARN of the role to assume. It can be sourced from the `TENCENTCLOUD_ASSUME_ROLE_ARN`.
    76  - `session_name` - (Required) The session name to use when making the AssumeRole call. It can be sourced from the `TENCENTCLOUD_ASSUME_ROLE_SESSION_NAME`.
    77  - `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`.
    78  - `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](https://intl.cloud.tencent.com/document/product/598/10603).
    79  
    80  Usage:
    81  
    82  ```hcl
    83  terraform {
    84    backend "cos" {
    85      region = "ap-guangzhou"
    86      bucket = "bucket-for-terraform-state-{appid}"
    87      prefix = "terraform/state"
    88      assume_role {
    89        role_arn = "qcs::cam::uin/xxx:roleName/yyy"
    90        session_name = "my-session-name"
    91        session_duration = 3600
    92      }
    93    }
    94  }
    95  ```
    96  
    97  In addition, these `assume_role` configurations can also be provided by environment variables.
    98  
    99  Usage:
   100  
   101  ```shell
   102  $ export TENCENTCLOUD_SECRET_ID="my-secret-id"
   103  $ export TENCENTCLOUD_SECRET_KEY="my-secret-key"
   104  $ export TENCENTCLOUD_REGION="ap-guangzhou"
   105  $ export TENCENTCLOUD_ASSUME_ROLE_ARN="qcs::cam::uin/xxx:roleName/yyy"
   106  $ export TENCENTCLOUD_ASSUME_ROLE_SESSION_NAME="my-session-name"
   107  $ export TENCENTCLOUD_ASSUME_ROLE_SESSION_DURATION=3600
   108  $ terraform plan
   109  ```