oci 백엔드

oci 백엔드

Oracle Cloud Infrastructure(OCI) Object Storage에 Terraform state 파일을 저장하는 oci 백엔드를 설명해 드릴게요. 여러 사용자가 공유 원격 state로 협업할 수 있고 state 잠금과 워크스페이스를 지원해요.

출처: 문서

본문

oci 백엔드는 Terraform state 파일을 Oracle Cloud Infrastructure (OCI) Object Storage에 저장해서, 여러 사용자가 공유 원격 state로 협업하고 state 잠금과 워크스페이스 같은 기능을 활용할 수 있게 해요.

⚠️ 경고: 우발적 삭제와 사람 실수로 인한 state 복구를 위해 객체 스토리지 버킷에서 Bucket Versioning을 활성화하는 것을 강력히 권장해요.

예시 구성 (Example Configuration)

terraform {
  backend "oci" {
    # 필수
    bucket            = "mybucket"
    namespace         = "my-namespace"
    # 선택
    tenancy_ocid      = "ocid1.tenancy.oc1..xxxxxxx"
    user_ocid         = "ocid1.user.oc1..xxxxxxxx"
    fingerprint       = "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
    private_key_path  = "~/.oci/oci_api_key.pem"
    region            = "us-ashburn-1"
    key               = "path/to/my/key"
    workspace_key_prefix = "envs/"
    kms_key_id        = "ocid1.key.oc1.iad.xxxxxxxxxxxxxx"
    auth              = "APIKey"
    config_file_profile = "DEFAULT"
  }
}

이 예시는 mybucket이라는 버킷이 이미 생성되어 있다고 가정해요. Terraform state는 path/to/my/key 키에 작성돼요. 접근 자격 증명에는 부분 구성(partial configuration)을 권장해요.

State 저장 (State Storage)

oci 백엔드는 Terraform state 파일을 OCI Object Storage의 bucket 파라미터가 지정한 버킷 안에서 key 파라미터가 정의한 경로에 저장해요. 위 예시를 사용하면 state 파일은 mybucket 버킷의 path/to/my/key에 저장돼요.

Terraform 워크스페이스를 사용할 때 기본 워크스페이스의 state는 위에서 설명한 경로에 정확히 저장돼요. 기본이 아닌 워크스페이스의 state는 <workspace_key_prefix>/<workspace_name>/<key> 경로 형식으로 저장돼요.

• 기본 workspace_key_prefix는 tf-state-env이지만 workspace_key_prefix 백엔드 파라미터로 커스터마이즈할 수 있어요.
• 예를 들어 development 워크스페이스라면 state는 tf-state-env/development/path/to/my/key에 저장돼요.

State 잠금 (State Locking)

• oci 백엔드는 OCI Object Storage의 If-None-Match: * 헤더 기능을 활용해 state 잠금을 지원해요.
• 사용자가 terraform plan/apply/destroy를 시작하면 백엔드가 state 파일과 같은 버킷에 잠금 객체를 만들어요.
• 예를 들어 development 워크스페이스의 잠금 파일은 tf-state-env/development/path/to/my/key.lock에 저장돼요.

이 잠금 메커니즘은 같은 state 파일에 대한 동시 연산을 방지해 손상이나 충돌 변경의 위험을 줄여요.

필요한 권한 (Permissions Required)

OCI Object Storage 버킷 권한

Terraform은 state 파일과 관련 잠금 파일을 관리하기 위해 대상 백엔드 버킷에 다음 OCI IAM 권한을 요구해요:

• OBJECT_INSPECT (HeadObject 포함)
• OBJECT_CREATE (PutObject, CreateMultipartUpload, UploadPart, CommitMultipartUpload 포함)
• OBJECT_DELETE (DeleteObject 포함)
• OBJECT_READ (GetObject 포함)

또는 세분화된(fine-grained) 정책을 사용한다면 정확한 연산을 지정할 수 있어요: GetObject, PutObject, DeleteObject, HeadObject, CreateMultipartUpload, UploadPart, CommitMultipart.

참고: 이 권한은 Terraform state 저장에 사용되는 특정 버킷에 부여되어야 해요.

OCI IAM 정책 레퍼런스

OCI IAM 정책 레퍼런스는 필요한 권한과 Object Storage 리소스에 Terraform에게 적절한 접근을 부여하기 위해 정책을 구성하는 방법에 대한 포괄적 세부 사항을 제공해요.

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

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

data "terraform_remote_state" "mystate" {
  backend = "oci"
  config = {
    bucket            = "mybucket"
    key               = "path/to/my/key"
    namespace         = "my-namespace"
    tenancy_ocid      = "ocid1.tenancy.oc1..xxxxxxx"
    user_ocid         = "ocid1.user.oc1..xxxxxxxx"
    fingerprint       = "xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx"
    private_key_path  = "~/.oci/oci_api_key.pem"
    region            = "us-ashburn-1"
  }
}

terraform_remote_state 데이터 소스는 참조된 원격 state에 정의된 루트 모듈 출력을 모두 반환해요 (중첩 모듈의 출력은 루트에서 명시적으로 다시 출력되지 않는 한 반환하지 않아요).

구성 (Configuration)

oci 백엔드는 Terraform state 파일이 저장될 OCI namespace와 Object Storage 버킷의 구성을 요구해요.

자격 증명과 공유 구성 (Credentials and Shared Configuration)

⚠️ 경고: 자격 증명과 기타 민감 데이터는 환경 변수로 제공하는 것을 강력히 권장해요. 이 값을 구성에 직접 하드코딩하거나 평문 시크릿과 함께 -backend-config 플래그를 사용하는 것을 피해요. 이런 방식으로 전달된 민감 값은 다음에 저장될 수 있어요: .terraform 하위 디렉터리, Terraform plan 파일(*.tfplan). 더 많은 지침은 Credentials and Sensitive Data 문서를 참고해요.

속성 레퍼런스 (Attribute reference)

필수 속성 (Required Properties)

선택 속성 (Optional Properties)

환경 변수로 백엔드 구성 설정하기

환경 변수로 OCI Terraform 백엔드를 구성할 수 있어요. 이는 유연성을 제공하고 자동화 워크플로를 단순화해요. region 같은 선택 백엔드 속성은 다음 환경 변수 형식 중 하나로 값을 설정할 수 있어요.

지원되는 환경 변수 접두사 (우선순위 순서):

• OCI_ - OCI SDK 호환 환경 변수. Terraform Provider OCI 자격 증명에도 사용할 수 있어요. export OCI_region=us-ashburn-1
• 접두사 없음 - 일반(최저 우선순위). export region=us-ashburn-1

Terraform은 위 우선순위 순서에 따라 찾은 첫 번째 일치 항목으로 속성 값을 해결해요.

⚠️ 참고: bucket과 namespace 같은 필수 속성은 환경 변수로 구성할 수 없어요. 반드시 백엔드 구성 블록에 명시적으로 지정해야 해요.

커스텀 암호화 키 (Custom encryption key)

커스텀 암호화 키를 사용하려면 다음 명령으로 새 키와 그 SHA256 해시를 생성할 수 있어요:

• 256비트(32바이트) base64 인코딩된 AES 키 생성:

openssl rand -base64 32

• 복호화된 키의 SHA-256 해시 생성:

echo -n <base64_key> | base64 -d | openssl dgst -sha256 -binary | base64

<base64_key>를 1단계에서 생성한 값으로 바꿔요.

더 알아보기 (Learn more)

• 백엔드 (Backends)
• state 잠금
• 워크스페이스
• terraform_remote_state 데이터 소스