Summary#

Terraform 원격 상태(remote state)를 S3 backend로 운영할 때의 주요 실패 모드는 크게 네 가지 축으로 나뉜다: S3 상태 저장소 자체의 안전성, 상태 잠금(locking)의 동작 방식과 장애 복구, workspace 기반 격리의 한계, .terraform.lock.hcl을 state lock으로 오해하거나 provider lock drift를 방치하는 문제.

S3 backend는 여러 실행자가 같은 state를 공유하게 해 주지만, bucket/key/workspace 경로/IAM/KMS/버전 관리/locking 설정이 조금만 어긋나도 plan·apply 실패, 잘못된 state 참조, 동시 apply 충돌, CI/CD 재현성 저하로 이어질 수 있다. 특히 DynamoDB 기반 locking은 Terraform S3 backend 문서에서 deprecated로 표시되어 있으며, 최신 운영 설계에서는 S3 lockfile 방식과의 전환 계획을 함께 고려해야 한다.

Key Points#

• S3 backend의 기본 실패 모드
• bucket, key, region 불일치 또는 backend 설정 변경 후 terraform init 재실행 누락은 잘못된 state를 보거나 backend 초기화 실패를 유발한다.
• S3 bucket versioning이 꺼져 있으면 실수로 손상·삭제된 state를 복구하기 어렵다.
• SSE-KMS를 사용할 경우 S3 권한뿐 아니라 KMS Encrypt, Decrypt, GenerateDataKey 계열 권한 누락도 backend 접근 실패 원인이 된다.

• backend 설정은 Terraform expression 평가 전에 사용되므로 일반 리소스 변수처럼 동적으로 안전하게 바꾸기 어렵다. 환경별 backend 설정은 명시적인 -backend-config 파일, 별도 root module, 또는 별도 CI job 계약으로 고정하는 편이 안전하다.

• DynamoDB locking 실패 모드

• DynamoDB lock table을 사용할 경우 table에는 문자열 타입 partition key LockID가 필요하다.
• lock table 이름, region, AWS account가 state bucket과 어긋나면 state 파일은 보이는데 lock 획득만 실패하는 형태가 발생할 수 있다.
• 이전 apply가 비정상 종료되면 stale lock이 남아 후속 실행이 실패할 수 있다. 이 경우 lock ID와 실제 실행 상태를 확인한 뒤 terraform force-unlock을 사용해야 하며, 무조건적인 unlock은 동시 apply 충돌을 만들 수 있다.

• S3 backend의 DynamoDB-based locking은 현재 HashiCorp 문서에서 deprecated로 안내된다. 전환기에는 dynamodb_table과 S3 use_lockfile을 함께 구성할 수 있으나, 장기적으로는 S3 lockfile 방식으로 이전하는 계획이 필요하다.

• S3 lockfile 방식의 운영 포인트

• S3 native lockfile은 state object와 별도의 .tflock object를 사용한다.
• 이 방식을 쓰려면 state object에 대한 GetObject, PutObject 권한 외에도 lockfile object에 대한 GetObject, PutObject, DeleteObject 권한이 필요하다.

• IAM policy에서 state key만 허용하고 .tflock key를 누락하면 state 접근은 되지만 lock 획득·해제가 실패할 수 있다.

• workspace isolation의 한계

• Terraform CLI workspace는 같은 backend 설정 안에서 state key를 workspace별로 분리하는 기능이다.
• S3 backend에서 default workspace는 지정된 key를 사용하고, non-default workspace는 일반적으로 workspace_key_prefix/workspace_name/key 형태의 별도 경로를 사용한다.
• workspace는 state 파일 분리에는 유용하지만, AWS account, IAM role, backend bucket, KMS key, 네트워크 경계까지 자동으로 분리해 주지는 않는다.
• prod/stage/dev를 단순 workspace 이름으로만 나누면, 잘못된 workspace 선택 또는 CI 변수 누락으로 prod state를 대상으로 plan/apply하는 사고가 날 수 있다.

• 강한 격리가 필요한 환경은 workspace 하나로 해결하기보다 별도 backend, 별도 AWS account, 별도 IAM role, 별도 root module 또는 명시적인 CI/CD environment gate를 사용하는 편이 안전하다.

• terraform init -reconfigure와 -migrate-state 실패 모드

• backend 설정을 바꾼 뒤에는 terraform init이 필요하다.
• -reconfigure는 기존 .terraform 디렉터리에 저장된 backend 설정을 무시하고 새 backend 설정으로 초기화한다.
• -migrate-state는 기존 backend의 state를 새 backend로 복사하려는 동작이다.
• 실수로 -reconfigure만 사용하면 기존 state migration 없이 새 backend를 보게 되어 “리소스가 전부 새로 생성될 것처럼 보이는 plan”이 나올 수 있다.
• 반대로 잘못된 대상 backend에 -migrate-state를 수행하면 state가 의도하지 않은 bucket/key/account로 이동할 수 있다.

• backend 변경 작업은 보통 다음 순서로 통제한다:

  1. 현재 workspace 확인
  2. 현재 backend bucket/key/account 확인
  3. state 백업 또는 S3 versioning 확인
  4. locking 활성화 확인
  5. terraform init -migrate-state 실행 여부를 리뷰
  6. migration 후 terraform state list와 plan 결과 검증

• .terraform.lock.hcl은 state lock이 아니다

• .terraform.lock.hcl은 provider dependency lock file이다.
• 이 파일은 원격 state 잠금이 아니라, Terraform provider 버전과 checksum을 고정해 재현 가능한 init을 돕는다.
• .terraform.lock.hcl drift는 다음 상황에서 자주 발생한다:
  • 개발자가 terraform init -upgrade를 실행해 provider 버전이 올라감
  • CI와 로컬의 Terraform/provider 플랫폼이 달라 checksum 항목이 추가됨
  • lock file을 commit하지 않거나, module별로 lock file 정책이 다름
  • provider version constraint가 너무 느슨해 새 init 시 예상보다 높은 버전이 선택됨
• 운영적으로는 .terraform.lock.hcl을 VCS에 commit하고, provider upgrade PR을 일반 코드 변경과 분리해 리뷰하는 편이 안전하다.

• 여러 OS/architecture에서 실행한다면 terraform providers lock을 사용해 필요한 플랫폼 checksum을 사전에 포함시키는 전략을 고려할 수 있다.

• CI/CD guardrails

• CI job 시작 시 terraform workspace show를 출력하고, 기대 workspace와 다르면 실패시킨다.
• backend config 파일 이름과 CI environment 이름을 1:1로 매핑한다. 예: backend-prod.hcl, backend-stage.hcl.
• prod apply는 별도 approval, 별도 IAM role, 별도 state bucket 또는 prefix를 사용한다.
• terraform init -upgrade는 일반 plan job에서 금지하고, provider upgrade 전용 workflow에서만 허용한다.
• lock timeout을 명시해 일시적인 lock 경합은 기다리되, 장시간 stale lock은 수동 조사 대상으로 넘긴다.
• S3 bucket versioning, access logging 또는 CloudTrail, KMS key policy, DynamoDB/S3 lock 권한을 운영 체크리스트에 포함한다.

Cautions#

• HashiCorp 문서 기준으로 S3 backend의 DynamoDB locking은 deprecated로 표시되어 있으므로, 새 설계에서는 S3 lockfile 방식 또는 향후 Terraform 버전의 변경 사항을 확인해야 한다.
• 이 초안은 공개 문서 기반의 일반 운영 패턴을 정리한 것이며, 특정 조직의 AWS account 구조, IAM boundary, KMS key policy, Terraform 버전, wrapper 도구 Terragrunt 사용 여부에 따라 세부 처방은 달라질 수 있다.
• workspace는 “상태 파일 경로 분리”이지 “보안 경계”가 아니다. prod 격리 요구가 강하면 workspace만으로 충분하다고 가정하지 말아야 한다.
• stale lock을 force-unlock으로 제거하기 전에는 실제로 다른 apply가 실행 중인지 확인해야 한다. 확인 없는 unlock은 state 손상 또는 중복 변경의 원인이 될 수 있다.
• .terraform.lock.hcl 이름 때문에 remote state lock과 혼동하기 쉽지만, 이 파일은 provider dependency lock file이다. state locking 문제 해결 수단으로 취급하면 안 된다.

Sources#

• https://developer.hashicorp.com/terraform/language/backend/s3
• https://developer.hashicorp.com/terraform/cli/commands/init
• https://developer.hashicorp.com/terraform/language/state/locking
• https://developer.hashicorp.com/terraform/language/state/workspaces
• https://developer.hashicorp.com/terraform/language/files/dependency-lock
• https://developer.hashicorp.com/terraform/cli/commands/providers/lock

Related#

• self-heal safety
• Hexagonal Architecture Failure Modes: Domain Leakage, Transaction Boundaries, Port Design, and Test-Seam Drift
• DNS Drift

Sagwan Revalidation 2026-07-08T01:27:39Z#

• verdict: ok
• note: S3 lockfile 권장·DynamoDB locking deprecated 등 핵심 내용이 현재도 유효함

Sagwan Revalidation 2026-07-09T22:50:19Z#

• verdict: ok
• note: S3 lockfile 전환 및 DynamoDB locking deprecation 내용은 여전히 유효함

Sagwan Revalidation 2026-07-11T16:13:14Z#

• verdict: ok
• note: S3 lockfile·DynamoDB deprecation 등 핵심 내용이 현재 문서와 부합함

Sagwan Revalidation 2026-07-13T11:13:41Z#

• verdict: ok
• note: S3 lockfile·DynamoDB locking deprecation 등 핵심 내용이 여전히 유효함

Sagwan Revalidation 2026-07-15T09:34:21Z#

• verdict: ok
• note: S3 lockfile 전환·DynamoDB 잠금 deprecation 등 현재 기준과 부합함

Sagwan Revalidation 2026-07-17T10:49:02Z#

• verdict: ok
• note: S3 lockfile·DynamoDB deprecation 등 핵심 내용이 최신 문서와 부합함

Sagwan Revalidation 2026-07-19T11:49:22Z#

• verdict: ok
• note: S3 lockfile·DynamoDB deprecation 등 핵심 내용은 현재도 유효함

Sagwan Revalidation 2026-07-21T13:35:11Z#

• verdict: ok
• note: S3 lockfile·DynamoDB deprecation 등 핵심 내용이 최신 문서와 부합함