COS 백엔드

COS 백엔드

Tencent Cloud Object Storage(COS) 버킷에 state를 객체로 저장하는 cos 백엔드를 설명해 드릴게요. 인증 방법과 state 잠금을 지원해요.

출처: 문서

본문

cos 백엔드는 Tencent Cloud Object Storage(COS)의 주어진 버킷에서 구성 가능한 접두사 아래 객체로 state를 저장해요. 이 백엔드는 state 잠금을 지원해요. COS 버킷에 state를 저장하려면 다음 권한이 필요해요:

  • tencentcloud-terraform-lock 태그 키에 대한 CreateTag, DeleteTag, DescribeTags
  • 지정된 버킷의 접두사에 대한 Put, Get, Delete 파일 권한

경고: 우발적 삭제와 사람 실수로 인한 state 복구를 위해 COS 버킷에서 Object Versioning을 활성화하는 것을 강력히 권장해요.

예시 구성 (Example Configuration)

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

이 예시는 bucket-for-terraform-state-1258798060라는 이름의 COS 버킷이 생성되어 있다고 가정해요. Terraform state는 terraform/state/terraform.tfstate 파일에 작성돼요.

데이터 소스 구성 (Data Source Configuration)

다른 구성에서 COS 원격 state를 사용하려면 terraform_remote_state 데이터 소스를 사용해요.

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

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

구성 변수 (Configuration Variables)

경고: 자격 증명과 기타 민감 데이터를 제공할 때는 환경 변수를 사용하는 것을 권장해요. -backend-config를 사용하거나 이런 값을 구성에 직접 하드코딩하면 Terraform이 .terraform 하위 디렉터리와 plan 파일 양쪽에 이 값을 포함해요. 자세한 내용은 Credentials and Sensitive Data를 참고해요.

지원하는 구성 옵션 / 환경 변수:

  • secret_id - (선택) Tencent Cloud의 Secret id. 환경 변수 TENCENTCLOUD_SECRET_ID를 지원해요.
  • secret_key - (선택) Tencent Cloud의 Secret key. 환경 변수 TENCENTCLOUD_SECRET_KEY를 지원해요.
  • security_token - (선택) 임시 접근 자격 증명의 TencentCloud Security Token. 환경 변수 TENCENTCLOUD_SECURITY_TOKEN을 지원해요.
  • region - (선택) COS 버킷의 리전. 환경 변수 TENCENTCLOUD_REGION을 지원해요.
  • bucket - (필수) COS 버킷의 이름. 먼저 수동으로 생성해야 해요.
  • prefix - (선택) 버킷에서 state 파일을 저장할 디렉터리. 기본값은 "env:".
  • key - (선택) 버킷에서 state 파일을 저장할 경로. 기본값은 terraform.tfstate.
  • encrypt - (선택) state 파일의 서버 측 암호화 활성화 여부. true면 COS가 'AES256' 암호화 알고리즘으로 state 파일을 암호화해요.
  • acl - (선택) state 파일에 적용할 객체 ACL. private와 public-read를 허용하고 기본값은 private.
  • accelerate - (선택) 전역 가속 활성화 여부. 기본값은 false.
  • endpoint - (선택) COS 백엔드용 커스텀 엔드포인트. 환경 변수 TENCENTCLOUD_ENDPOINT를 지원해요.
  • domain - (선택) API 요청의 루트 도메인. 기본값은 tencentcloudapi.com. 환경 변수 TENCENTCLOUD_DOMAIN을 지원해요.

역할 위임 (Assume Role)

assume role이 제공되면 Terraform은 제공된 자격 증명으로 이 역할을 위임하려 시도해요. cos 백엔드 블록에 assume_role 블록을 추가해 assume role을 제공할 수 있어요.

  • assume_role - (선택) assume_role 블록. 제공되면 Terraform은 제공된 자격 증명으로 이 역할을 위임하려 시도해요.

assume_role 블록의 세부 사항:

  • role_arn - (필수) 위임할 역할의 ARN. TENCENTCLOUD_ASSUME_ROLE_ARN에서 가져올 수 있어요.
  • session_name - (필수) AssumeRole 호출 시 사용할 세션 이름. TENCENTCLOUD_ASSUME_ROLE_SESSION_NAME에서 가져올 수 있어요.
  • session_duration - (필수) AssumeRole 호출 시 세션의 기간. 값 범위는 0~43200(초)이며 기본값은 7200초. TENCENTCLOUD_ASSUME_ROLE_SESSION_DURATION에서 가져올 수 있어요.
  • policy - (선택) AssumeRole 호출 시 더 제한적인 정책. 내용에 principal 요소가 포함되면 안 돼요. 문법 참조는 정책 문법 로직 참고.

사용:

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 = 7200
    }
  }
}

또한 이 assume_role 구성은 환경 변수로도 제공할 수 있어요.

$ 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=7200
$ terraform plan

공유 자격 증명 (Shared credentials)

Tencent Cloud 자격 증명으로 자격 증명을 지정할 수 있어요. 기본 위치는 Linux/macOS에서 $HOME/.tccli, Windows에서 "%USERPROFILE%\.tccli"예요. shared_credentials_dir 인자를 제공하거나 TENCENTCLOUD_SHARED_CREDENTIALS_DIR 환경 변수를 사용해 Terraform 구성에서 다른 위치를 선택적으로 지정할 수 있어요. 이 방법은 profile 구성과 일치하는 TENCENTCLOUD_PROFILE 환경 변수도 지원해요:

  • shared_credentials_dir - (선택) 공유 자격 증명의 디렉터리. TENCENTCLOUD_SHARED_CREDENTIALS_DIR 환경 변수에서도 가져올 수 있어요. 설정하지 않으면 기본값은 ~/.tccli.
  • profile - (선택) 공유 자격 증명에 설정된 프로필 이름. TENCENTCLOUD_PROFILE 환경 변수에서도 가져올 수 있어요. 설정하지 않으면 tccli configure로 만든 기본 프로필을 사용해요.

Linux/MacOS에서의 사용:

terraform {
  backend "cos" {
    region                 = "ap-guangzhou"
    bucket                 = "bucket-for-terraform-state-{appid}"
    prefix                 = "terraform/state"
    shared_credentials_dir = "/Users/tf_user/.tccli"
    profile                = "default"
  }
}

Windows에서의 사용:

terraform {
  backend "cos" {
    region                 = "ap-guangzhou"
    bucket                 = "bucket-for-terraform-state-{appid}"
    prefix                 = "terraform/state"
    shared_credentials_dir = "C:\\Users\\tf_user\\.tccli"
    profile                = "default"
  }
}

또한 이 shared_credentials_dir, profile 구성은 환경 변수로도 제공할 수 있어요.

$ export PROVIDER_SHARED_CREDENTIALS_DIR="/Users/tf_user/.tccli"
$ export PROVIDER_PROFILE="default"
$ terraform plan

CAM 역할 이름 (Cam role name)

CAM 역할 이름이 제공되면 Terraform은 메타데이터 URL http://metadata.tencentyun.com/latest/meta-data/cam/security-credentials/에만 접근해 STS 자격 증명을 얻어요. CVM 인스턴스 역할은 TENCENTCLOUD_CAM_ROLE_NAME 환경 변수로도 설정할 수 있어요.

  • cam_role_name - (선택) CVM 인스턴스 CAM 역할의 이름. TENCENTCLOUD_CAM_ROLE_NAME 환경 변수에서 가져올 수 있어요.
terraform {
  backend "cos" {
    region        = "ap-guangzhou"
    bucket        = "bucket-for-terraform-state-{appid}"
    prefix        = "terraform/state"
    cam_role_name = "my-cam-role-name"
  }
}

또한 Assume role 방식과 함께 인증할 수도 있어요. 인증 과정: 먼저 CAM 인증을 수행한 다음 Assume role 인증을 진행해요.

이 cam_role_name 구성은 환경 변수로도 제공할 수 있어요.

$ export PROVIDER_CAM_ROLE_NAME="my-cam-role-name"
$ terraform plan

엔드포인트 (Endpoint)

엔드포인트 URL이 제공되면 Terraform은 endpoint 구성 또는 환경 변수 TENCENTCLOUD_ENDPOINT로 COS 백엔드에 접근하려 시도해요. 일반적인 엔드포인트는 http://cos-internal.{Region}.tencentcos.cn처럼 보여요. HTTP와 HTTPS 둘 다 허용돼요.

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

더 알아보기 (Learn more)