Amazon S3를 사용한 Terraform 상태 관리

Source: Dev.to

위의 링크에 있는 글의 내용을 제공해 주시면, 해당 텍스트를 한국어로 번역해 드리겠습니다. (코드 블록, URL 및 마크다운 형식은 그대로 유지됩니다.)

Terraform 상태가 중요한 이유

Terraform은 상태 파일(terraform.tfstate)을 사용하여 관리하는 인프라를 추적합니다. 이 파일에는 구성과 실제 리소스 간의 매핑이 포함되어 있어, Terraform이 향후 실행 시 안전하고 예측 가능한 변경을 수행할 수 있습니다.

기본적으로 Terraform은 상태를 로컬에 저장합니다. 이는 실험에는 괜찮지만 협업, 자동화 및 프로덕션 사용에는 안전하지 않습니다.

S3와 같은 원격 백엔드를 사용하는 이유

Terraform 공식 문서에 따르면 S3는 상태를 저장하고 잠금을 지원할 수 있는 지원되는 백엔드 유형이며, AWS 환경에서 가장 널리 사용되고 신뢰받는 백엔드 중 하나입니다.

상태 잠금 — 충돌 방지

Terraform은 두 사람(또는 CI 작업)이 동시에 동일한 상태 파일에 변경을 기록하는 것을 방지해야 합니다. 그렇지 않으면 상태가 손상될 수 있습니다.

최신 잠금 (S3 네이티브)

Terraform은 이제 잠금 파일 메커니즘을 통해 S3에서 네이티브 상태 잠금을 지원합니다. Terraform은 상태 파일과 함께 버킷에 .tflock 파일을 생성하여 동시 실행을 방지합니다.

terraform {
  backend "s3" {
    bucket       = "my-terraform-state-bucket2z"
    key          = "envs/prod/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

• use_lockfile = true는 S3‑네이티브 잠금을 활성화합니다.
• Terraform 실행 중에 S3가 .tflock 파일을 생성합니다.
• 다른 프로세스는 잠금이 해제될 때까지 대기해야 합니다.

이는 상태 잠금을 위한 별도의 DynamoDB 테이블이 필요 없게 하며, 해당 방식은 공식적으로 사용 중단(deprecated) 되었고 향후 Terraform 릴리스에서 제거될 예정입니다.

Note: DynamoDB 잠금은 이전 호환성을 위해 여전히 지원되지만, Terraform은 이제 새로운 구성에 대해 S3 네이티브 잠금을 선호합니다.

사전 요구 사항

Step 1 — Terraform 상태를 위한 S3 버킷 생성

Terraform은 백엔드 버킷을 자동으로 생성할 수 없으므로, 먼저 직접 생성해야 합니다.

aws s3api create-bucket \
  --bucket my-terraform-state-bucket2z \
  --region us-east-1

my-terraform-state-bucket2z를 전 세계에서 고유한 이름으로 바꾸세요.

2단계 — 버킷 버전 관리 활성화 (모범 사례)

버전 관리는 실수로 인한 삭제나 손상으로부터 복구하는 데 도움이 됩니다.

aws s3api put-bucket-versioning \
  --bucket my-terraform-state-bucket2z \
  --versioning-configuration Status=Enabled

Step 3 — 버킷에 암호화 활성화

Encrypting state at rest is essential for security.

aws s3api put-bucket-encryption \
  --bucket my-terraform-state-bucket2z \
  --server-side-encryption-configuration '{
    "Rules": [{
      "ApplyServerSideEncryptionByDefault": {
        "SSEAlgorithm": "AES256"
      }
    }]
  }'

문제 해결: AccessDenied 오류

If you encounter an AccessDenied error when running the encryption command:

An error occurred (AccessDenied) when calling the PutBucketEncryption operation: Access Denied

일반적인 원인 및 해결책

Step 4 — Terraform 백엔드 구성

Terraform 디렉터리에서 백엔드를 다음과 같이 정의합니다:

terraform {
  backend "s3" {
    bucket       = "my-terraform-state-bucket2z"
    key          = "demo/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

Demo: Using S3 Remote State

1. Create a Terraform Project

mkdir terraform-s3-state-demo
cd terraform-s3-state-demo

2. Add Terraform Code

Create a file main.tf:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    bucket       = "my-terraform-state-bucket2z"
    key          = "demo/terraform.tfstate"
    region       = "us-east-1"
    use_lockfile = true
  }
}

(Add the rest of your infrastructure resources below this block as needed.)

Run the usual Terraform workflow:

terraform init      # Initializes the backend and downloads providers
terraform plan      # Shows the execution plan
terraform apply      # Applies the changes and stores state in S3

상태 파일은 s3://my-terraform-state-bucket2z/demo/terraform.tfstate에 저장되며, Terraform은 각 실행 시 동시 수정 방지를 위해 .tflock 파일을 생성합니다.

마무리

Amazon S3 원격 백엔드에 네이티브 잠금을 사용해 Terraform 상태를 저장하면 다음과 같은 이점을 얻을 수 있습니다:

• 중앙 집중식이며 버전 관리되고 암호화된 상태 저장소
• 팀 간 안전한 협업
• DynamoDB 테이블의 부하 없이 자동 상태 잠금

이러한 실천 방안을 AWS에서의 모든 프로덕션 Terraform 워크플로에 적용하면, 상태 손상 및 배포 실패를 초래하는 일반적인 함정을 많이 피할 수 있습니다. 즐거운 프로비저닝 되세요!

terraform {
  backend "s3" {
    bucket        = "my-terraform-state-bucket2z"
    key           = "demo/terraform.tfstate"
    region        = "us-east-1"
    encrypt       = true
    use_lockfile  = true
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_s3_bucket" "example" {
  bucket = "tf-s3-backend-demo-example"
}

백엔드 초기화

terraform init

Terraform은 백엔드를 초기화하고 자동으로 구성합니다.

변경 적용

terraform apply

이제 상태 파일이 S3에 저장되며, 상태 잠금이 활성화되었습니다.

유용한 Terraform 백엔드 명령

로컬 상태를 원격으로 마이그레이션

terraform init -migrate-state

백엔드 재구성

terraform init -reconfigure

상태 리소스 목록

terraform state list

리소스 상세 보기

terraform state show aws_s3_bucket.example

추가 모범 사례

상태를 원격에 저장

S3 또는 Terraform Cloud를 사용하세요 — 팀 환경에서는 절대로 로컬에 상태를 저장하지 마세요.

상태를 수동으로 편집하거나 삭제하지 않기

수동 변경은 상태를 손상시킵니다.

환경별로 상태 격리

환경마다 다른 키를 사용하세요:

envs/dev/terraform.tfstate
envs/staging/terraform.tfstate
envs/prod/terraform.tfstate

정기 백업

S3 버전 관리를 활성화하여 실수로 덮어쓰이거나 삭제된 상태를 롤백할 수 있게 하세요.

모든 쓰기 작업에서 상태 잠금

use_lockfile = true를 활성화하세요. 이는 한 번에 하나의 Terraform 프로세스만 상태를 수정하도록 보장하여 충돌 및 손상을 방지합니다.

정리: 데모 리소스 안전하게 제거

단계 1: Terraform 리소스 파괴

terraform destroy

• 이 명령은:
  • S3에서 상태 파일을 읽고
  • 모든 관리 리소스를 식별하고
  • AWS에서 안전하게 삭제합니다

확인 후, 모든 데모 인프라가 제거되지만 Terraform 상태 파일은 여전히 S3에 남아 있습니다(이는 정상적인 동작입니다).

단계 2: S3에서 상태 파일 확인 (선택 사항)

aws s3 ls s3://my-terraform-state-bucket2z/demo/

Terraform은 상태 파일을 보관하여 다음을 유지합니다:

• 관리된 인프라의 기록
• (버전 관리가 활성화된 경우) 히스토리 버전

단계 3: Terraform 상태 파일 삭제 (선택 사항)

aws s3 rm s3://my-terraform-state-bucket2z/demo/terraform.tfstate

경고: 인프라가 아직 존재하는 동안 상태 파일을 삭제하지 마세요 — 리소스가 고아가 됩니다.

단계 4: (선택 사항) 잠금 파일 비활성화 또는 제거

S3 네이티브 잠금을 사용한 경우, Terraform은 작업이 완료된 후 자동으로 .tflock 파일을 제거합니다. 수동 제거는 일반적으로 필요하지 않습니다.

단계 5: S3 백엔드 버킷 삭제 (선택 사항)

버킷이 이 데모 전용으로 생성된 경우:

버킷 비우기

aws s3 rm s3://my-terraform-state-bucket2z --recursive

버킷 삭제

aws s3api delete-bucket \
  --bucket my-terraform-state-bucket2z \
  --region us-east-1

Cleanup Best Practices

• 항상 먼저 terraform destroy를 실행하십시오.
• 리소스를 파괴하기 전에 상태 파일을 절대 삭제하지 마십시오.
• 장기 프로젝트를 위해 상태 버킷을 유지하십시오.
• 복구를 위해 버전 관리를 활성화하십시오.
• IAM 정책을 사용하여 접근을 제한하십시오.

요약

Terraform 상태는 인프라 자동화의 기반입니다. 원격 S3 백엔드에 네이티브 상태 잠금을 사용해 저장하면:

• 안전한 협업을 가능하게 함
• 동시 수정 방지
• 제어된 복구 허용
• CI/CD 워크플로 지원

네이티브 잠금이 적용된 S3 원격 상태는 이제 Terraform이 권장하는 모범 사례이며, 대부분의 경우 별도의 DynamoDB 잠금 테이블이 필요하지 않게 됩니다.

References

• Terraform S3 백엔드 (공식 문서)
• Terraform 상태 잠금 (공식 문서)
• Terraform 상태 잠금

최종 생각

Terraform 상태 정리는 프로비저닝만큼 중요합니다.

안전한 정리 프로세스는 다음을 보장합니다:

• 고아 리소스 없음
• 예상치 못한 AWS 요금 없음
• 향후 작업을 위한 깨끗한 환경

원격 상태를 사용할 때: Terraform은 언제나 진실의 원천 — 시작부터 끝까지 라이프사이클을 관리하도록 하세요.