gcs 백엔드

gcs 백엔드

Terraform state를 Google Cloud Storage(GCS) 버킷의 객체로 저장하는 gcs 백엔드 설정을 설명해 드릴게요. 인증 방법과 암호화 옵션까지 함께 다뤄요.

출처: 문서

본문

gcs 백엔드는 Google Cloud Storage(GCS)의 기존 버킷에서 구성 가능한 접두사(prefix) 아래 객체로 state를 저장해요. 버킷은 백엔드를 구성하기 전에 이미 존재해야 해요. 이 백엔드는 state 잠금을 지원해요.

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

예시 구성 (Example Configuration)

terraform {
  backend "gcs" {
    bucket  = "tf-state-prod"
    prefix  = "terraform/state"
  }
}

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

data "terraform_remote_state" "foo" {
  backend = "gcs"
  config = {
    bucket  = "terraform-state"
    prefix  = "prod"
  }
}

# Terraform >= 0.12
resource "local_file" "foo" {
  content  = data.terraform_remote_state.foo.outputs.greeting
  filename = "${path.module}/outputs.txt"
}

참고: 버킷에 대한 Terraform IAM 변경은 결과적 일관성(eventually consistent)을 가지며 적용되는 데 몇 분까지 걸릴 수 있어요. Terraform은 일관성이 생길 때까지 403 오류를 반환해요.

워크스테이션에서 Terraform 실행 (Running Terraform on your workstation)

워크스테이션에서 Terraform을 사용한다면 Google Cloud SDK를 설치하고 User Application Default Credentials로 인증해야 해요. User ADC는 만료되며 gcloud auth application-default login을 실행해 갱신할 수 있어요.

Google Cloud에서 Terraform 실행 (Running Terraform on Google Cloud)

Google Cloud에서 Terraform을 실행한다면 인스턴스나 클러스터를 Google Service Account를 사용하도록 구성할 수 있어요. 그러면 별도의 자격 증명/인증 파일을 구울 필요 없이 Terraform이 Google Cloud에 인증할 수 있어요. VM/클러스터의 scope가 cloud-platform으로 설정되어 있는지 확인해요.

Google Cloud 밖에서 Terraform 실행 (Running Terraform outside of Google Cloud)

Google Cloud 밖에서 Terraform을 실행한다면 서비스 계정 키를 생성하고 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 키의 경로로 설정해요. Terraform이 그 키로 인증해요.

서비스 계정 위장 (Impersonating Service Accounts)

Terraform은 여기에 설명된 대로 Google Service Account를 위장(impersonate)할 수 있어요. 앞 섹션에서 언급한 대로 유효한 자격 증명을 제공해야 하며, 그 신원이 위장하는 서비스 계정에 대해 roles/iam.serviceAccountTokenCreator 역할을 가져야 해요.

암호화 (Encryption)

경고: 암호화 키를 잘 관리하세요. 잃어버리거나 삭제된 키로 암호화된 state 데이터는 복구할 수 없어요. 고객 제공 암호화 키를 사용한다면 키를 안전하게 관리하고 잃지 않도록 해야 해요. state를 암호화하는 데 사용하는 Cloud KMS의 고객 관리 암호화 키는 삭제하면 안 돼요. 하지만 실수로 키를 삭제했다면 복구할 수 있는 시간 창이 있어요.

고객 제공 암호화 키 (Customer-supplied encryption keys)

시작하려면 이 가이드를 따라요: 고객 제공 암호화 키 사용

백엔드 구성에서 고객 제공 키를 제거하거나 다른 고객 제공 키로 변경하려면, Terraform이 state 마이그레이션을 자동으로 수행할 수 없고 수동 개입이 필요해요. Google이 고객 제공 암호화 키를 저장하지 않기 때문에 Cloud Storage API에 보내는 모든 요청이 이를 대신 제공해야 하기 때문이에요 (Customer-supplied Encryption Keys 참고). state 마이그레이션 시점에 백엔드 구성이 이전 키의 세부 사항을 잃게 되고 Terraform이 마이그레이션 과정에서 그 키를 사용할 수 없어요.

중요: 고객 제공 암호화 키를 사용하지 않고 state를 마이그레이션하거나 백엔드가 사용하는 키를 변경하려면, rewrite (gsutil CLI) 또는 cp (gcloud CLI) 연산을 수행해 state 파일에서 이전 고객 제공 암호화 키의 사용을 제거해야 해요. 암호화를 제거하면 새 백엔드 구성으로 terraform init -migrate-state를 성공적으로 실행할 수 있어요.

고객 관리 암호화 키 (Cloud KMS) (Customer-managed encryption keys (Cloud KMS))

시작하려면 이 가이드를 따라요: 고객 관리 암호화 키 사용

백엔드 구성에서 고객 관리 키를 제거하거나 다른 고객 관리 키로 변경하려면, Terraform이 수동 개입 없이 state 마이그레이션을 관리할 수 있어요. GCP가 고객 관리 암호화 키를 저장하고 state 마이그레이션 과정에서 접근할 수 있기 때문이에요. 하지만 이런 변경은 state 마이그레이션 후 state 파일에 첫 번째 쓰기 연산이 일어날 때까지 완전히 적용되지 않아요. 마이그레이션 후 첫 쓰기 연산에서 파일은 이전 키로 복호화된 다음 새 암호화 방식으로 작성돼요. 이 방식은 고객 제공 암호화 키 섹션에서 설명한 rewrite 연산과 동등해요. 마이그레이션 후 state에 대한 첫 번째 쓰기의 중요성 때문에, 그 키로 암호화된 state 파일이 업데이트될 때까지 이전 KMS 키를 삭제하면 안 돼요.

고객 관리 키는 복호화가 GCS 내에서 자동으로 일어나므로 GCS 버킷에서 파일을 읽는 요청에 보낼 필요가 없어요. 이 말은 terraform_remote_state 데이터 소스로 KMS 암호화 state에 접근한다면 데이터 소스의 config 객체에 KMS 키를 지정할 필요가 없다는 뜻이에요.

중요: 고객 관리 암호화 키를 사용하려면 키를 만들고 프로젝트의 GCS 서비스 에이전트에 Cloud KMS CryptoKey Encrypter/Decrypter 사전 정의 역할로 사용 권한을 부여해야 해요.

구성 변수 (Configuration Variables)

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

다음 구성 옵션을 지원해요:

  • bucket - (필수) GCS 버킷 이름. 이 이름은 전역적으로 고유해야 해요. 자세한 내용은 Bucket Naming Guidelines 참고.
  • credentials / GOOGLE_BACKEND_CREDENTIALS / GOOGLE_CREDENTIALS - (선택) JSON 형식의 Google Cloud Platform 계정 자격 증명의 로컬 경로. 설정하지 않으면 Google Application Default Credentials 경로를 사용해요. 제공된 자격 증명은 버킷에 대해 Storage Object Admin 역할을 가져야 해요.

    경고: Google Cloud Platform 프로바이더도 함께 사용하면 GOOGLE_CREDENTIALS 환경 변수를 역시 읽게 돼요.

  • impersonate_service_account / GOOGLE_BACKEND_IMPERSONATE_SERVICE_ACCOUNT / GOOGLE_IMPERSONATE_SERVICE_ACCOUNT - (선택) State 버킷에 접근하기 위해 위장할 서비스 계정. 위장이 성공하려면 그 계정에 roles/iam.serviceAccountTokenCreator 역할이 있어야 해요. 위임 체인을 사용한다면 impersonate_service_account_delegates 필드로 지정할 수 있어요.
  • impersonate_service_account_delegates - (선택) 여기에 설명된 서비스 계정 위장을 위한 위임 체인.
  • access_token - (선택) Google Authorization 서버에서 얻은 임시 OAuth 2.0 access token로, 즉 GCP API에 HTTP 요청을 인증하는 데 사용하는 Authorization: Bearer <access_token> 헤더에요. credentials의 대안이에요. 둘 다 지정하면 access_token이 credentials 필드보다 우선해요.
  • prefix - (선택) 버킷 안의 GCS 접두사. 워크스페이스의 명명된 state는 <prefix>/<workspace>.tfstate라고 불리는 객체에 저장돼요.
  • encryption_key / GOOGLE_ENCRYPTION_KEY - (선택) 버킷에서 state 파일을 읽고 쓸 때 사용하는 32바이트 base64 인코딩된 '고객 제공 암호화 키'. 자세한 내용은 Customer-supplied Encryption Keys 참고.
  • kms_encryption_key / GOOGLE_KMS_ENCRYPTION_KEY - (선택) 버킷에서 state 파일을 읽고 쓸 때 사용하는 Cloud KMS 키('고객 관리 암호화 키'). 형식은 projects/{{project}}/locations/{{location}}/keyRings/{{keyRing}}/cryptoKeys/{{name}}이어야 해요. IAM 요구사항을 포함한 자세한 내용은 Customer-managed Encryption Keys 참고.
  • storage_custom_endpoint / GOOGLE_BACKEND_STORAGE_CUSTOM_ENDPOINT / GOOGLE_STORAGE_CUSTOM_ENDPOINT - (선택) 세 부분을 포함하는 URL: 프로토콜, Private Service Connect 엔드포인트를 가리키는 DNS 이름, Cloud Storage API 경로(/storage/v1/b, 여기 참고). Service Directory가 자동으로 만든 DNS 이름이나 직접 만든 커스텀 DNS 이름을 사용할 수 있어요. 예를 들어 xyz라는 엔드포인트를 만들고 자동 생성 DNS 이름을 사용하려면 필드 값을 https://storage-xyz.p.googleapis.com/storage/v1/b로 설정해요. Terraform으로 Private Service Connect 엔드포인트를 만드는 데 도움이 필요하면 이 가이드를 참고해요.

더 알아보기 (Learn more)