Fullmoon System

Terraform state 이전: 원격 백엔드·잠금·드리프트를 검증하는 절차

AI Editter

Terraform state는 다시 만들 수 있는 캐시가 아닙니다. 실제 리소스와 Terraform 주소의 연결 정보가 들어 있으므로 잘못된 state로 plan을 실행하면 이미 존재하는 리소스를 새로 만들거나 삭제하려는 결과가 나올 수 있습니다.

백엔드 이전에서 먼저 멈춰야 하는 것은 서버가 아니라 state를 변경하는 작업입니다. 개발자 PC와 CI가 서로 다른 백엔드를 사용해 동시에 apply하지 않도록 전환 시간을 정합니다.

이전 전 기록할 다섯 가지

기록확인 목적
Terraform·provider 버전과 lock 파일이전과 업그레이드를 분리
현재 backend와 workspace잘못된 환경 이전 방지
state lineage·serial·리소스 주소이전 전후 동일성 확인
CI backend 설정·환경 변수개인 PC만 바뀌는 문제 방지
state 백업과 접근 권한복구 경로 확보
terraform version
terraform workspace show
terraform workspace list
terraform state list

state 자체에는 비밀값이 들어 있을 수 있습니다. pull로 백업한다면 권한이 제한된 경로에 저장하고 Git에 커밋하지 않습니다. CI artifact로 장기 보관하는 경우에도 암호화·열람 권한·보존 기간을 정해야 합니다.

S3 백엔드 설정 예시

아래는 해당 기능을 지원하는 Terraform에서 사용할 예시입니다. 버킷은 미리 만들고 이름·리전·경로를 실제 값으로 바꿉니다. 이 글은 기존 인프라를 새로 생성하는 작업을 포함하지 않습니다.

terraform {
  backend "s3" {
    bucket       = "YOUR-STATE-BUCKET"
    key          = "prod/network/terraform.tfstate"
    region       = "ap-northeast-2"
    encrypt      = true
    use_lockfile = true
  }
}

S3 backend 공식 문서에 따르면 S3 잠금 파일 사용은 opt-in입니다. 기존 DynamoDB 기반 잠금은 deprecated로 안내되므로 새 구성에 과거 예시를 그대로 적용하기 전에 현재 지원 상태를 확인합니다.

S3 객체 버전 관리를 켜 두면 state의 과거 버전을 복구하는 데 도움이 됩니다. 잠금 파일에는 생성·조회·삭제 권한이 필요하며 state 객체의 권한과 정확한 경로를 구분합니다. 자격 증명은 backend 코드에 직접 적지 않습니다.

migrate-state와 reconfigure를 혼동하지 않기

기존 백엔드 설정을 인식하는 작업 디렉터리에서 변경할 backend를 준비한 뒤 terraform init -migrate-state를 사용하면 state 이동 절차를 진행할 수 있습니다. 화면에 표시되는 원본·대상·workspace를 읽고 진행합니다.

반면 -reconfigure는 기존 backend 구성을 무시하고 다시 설정하는 옵션이며 state를 옮기는 목적의 대체 명령이 아닙니다. init 명령 설명에서 두 옵션의 차이를 확인합니다.

작업 전 .terraform 디렉터리를 무작정 지우면 도구가 기억하는 이전 backend 정보를 잃을 수 있습니다. 오류가 났다면 먼저 어느 단계까지 이동했는지 원본과 대상 state를 확인합니다. 실패했다고 즉시 빈 state를 만들어 진행하지 않습니다.

이전 성공을 판정하는 검증표

검사기대 결과
workspace 목록·현재 선택이전 계획과 일치
리소스 주소 목록누락·추가 없음
state lineage·serial의도한 계보와 최신 버전 확인
대상 객체·버전예상 bucket·key에 기록
plan설명되지 않는 생성·삭제 없음
CI 읽기같은 backend·workspace 사용

plan은 실제 변경을 적용하지 않지만 provider API를 조회하므로 적절한 자격 증명과 네트워크가 필요합니다. 이전과 무관한 기존 드리프트가 있을 수 있어 “변경 0이 아니면 무조건 이전 실패”로 판단하지는 않습니다. 변경 항목을 이전 전 기록과 비교합니다.

잠금 검증은 운영 apply를 동시에 실행해 시험하지 않습니다. 별도 시험 backend에서 의도적으로 잠금을 유지하는 통제된 작업과 두 번째 작업을 사용해 경쟁 실행이 차단되는지 확인합니다. 운영에서는 잠금 객체와 정상 실행 로그를 점검합니다.

복구할 때 가장 위험한 순간

이전 직후 아무 쓰기도 없었다면 원본으로 돌아가는 판단이 비교적 단순합니다. 그러나 새 backend에서 apply가 한 번이라도 수행됐다면 원본 state는 과거 상태일 수 있습니다. 원본 파일을 덮어 복구하면 실제 리소스와 state가 어긋납니다.

복구 전에 모든 실행을 멈추고 양쪽 state와 실제 리소스를 비교합니다. force-unlock은 소유한 작업이 종료됐음을 확인한 뒤 해당 잠금에 한해 사용해야 합니다. 잠금이 오래됐다는 이유만으로 해제하면 아직 실행 중인 작업과 충돌할 수 있습니다.

전환이 끝나면 이전 backend에 대한 쓰기 경로를 닫고 CI 설정·운영 문서도 갱신합니다. 리소스를 건드리지 않은 이전이라도 팀 전체가 하나의 최신 state를 사용해야 완료입니다.

관련 절차: Ansible 플레이북 실전 가이드: 인벤토리·멱등성·Vault·롤링 배포