로컬 상태를 S3로 옮기기

소개

유지관리 담당자는 사용 중인 스택의 리소스 매핑을 보관할 공유 위치가 필요합니다. 기존 보고서를 보존하면서 로컬 상태를 버전 관리가 활성화된 별도의 S3 백엔드로 마이그레이션한 다음, 상태 기록과 백엔드의 독립적인 수명 주기를 살펴봅니다.

Terraform 상태, 가져오기, 저장된 계획, S3 객체 버전을 이해하고 있어야 합니다. 이 실습의 모든 리소스는 새로운 환경에 준비되어 있습니다. 이전 상태나 개인 AWS 계정은 필요하지 않습니다.

자격증	시험 과제	실습 내용
CloudOps Engineer – Associate (SOA-C03)	Task 3.1, Skill 3.1.6	사용 중인 리소스를 보존하면서 검토된 구성 및 상태 변경으로 인프라를 유지관리하는 Terraform 기초 실습입니다.

실습 개요

개념도: 유지관리 작업은 구성, 상태, 기존 보고서 스토리지 사이의 관계를 보존합니다.

로컬 상태와 백엔드의 경계 확인하기

이 단계에서는 업무용 버킷과 별도의 상태 저장 대상을 식별합니다. 제공된 보고서 루트는 이미 migration-daily-reports를 관리하며, 그 로컬 상태는 재무 참조 리소스와 독립적입니다. 버전 관리가 활성화된 maintenance-team-state 버킷은 플랫폼 팀이 준비하므로 이 루트에서 사용하기 전에 이미 존재합니다.

cd /home/labex/project/state-migration
terraform state list
terraform state show aws_s3_bucket.reports

원격 버킷 ID가 migration-daily-reports인지 확인하세요. 백엔드는 리소스 매핑을 저장합니다. AWS 리소스를 생성하고 읽는 프로바이더와는 다릅니다. 이 환경에서는 프로바이더와 백엔드의 연결 설정이 별도로 준비되어 있습니다.

상태 저장 위치를 변경하기 전에 비공개 로컬 백업을 저장합니다. 리디렉션(>)은 상태 JSON을 파일에 씁니다. 상태나 계획을 공개 소스 저장소에 커밋하지 마세요.

terraform state pull > local-before-migration.json
chmod 600 local-before-migration.json

백엔드의 버전 관리와 처음에 비어 있는 객체 목록을 확인합니다.

aws s3api \
  get-bucket-versioning \
  --bucket maintenance-team-state

Status: Enabled가 표시되어야 합니다.

aws s3api \
  list-objects-v2 \
  --bucket maintenance-team-state

아직 상태 객체가 없어야 합니다. 비어 있는 대상을 선택하는 것이 중요합니다. 이미 다른 환경에 속한 키로 마이그레이션하면 해당 환경의 관리 기록을 덮어쓸 수 있습니다. migration-finance-reference는 변경하지 마세요.

기존 매핑을 의도한 S3 키로 마이그레이션하기

이 단계에서는 원격 백엔드를 구성하고 기존 로컬 리소스 매핑을 비어 있는 대상에 복사합니다. 키는 백엔드 버킷 안의 상태 객체 이름입니다. 하나의 특정 환경을 위한 키를 선택하세요.

일부 설정만 포함한 S3 백엔드 선언을 작성합니다. 연결 설정은 별도로 제공되며, 다음 파일에서 사용할 버킷과 키를 지정합니다.

cat > backend.tf <<'HCL'
terraform {
  backend "s3" {}
}
HCL

환경별 백엔드 구성을 생성합니다. use_lockfile = true는 이후 쓰기 작업을 위해 Terraform 자체의 S3 잠금 파일 기능을 활성화합니다.

cat > reports.s3.tfbackend <<'HCL'
bucket       = "maintenance-team-state"
key          = "reports/production.tfstate"
region       = "us-east-1"
use_lockfile = true
HCL

-migrate-state는 기존 매핑을 새 백엔드로 옮기도록 Terraform에 요청합니다. Terraform은 기존 상태를 복사할지 묻습니다. printf 파이프라인이 yes라는 답을 전달합니다. 이 실습의 대상 키가 비어 있음을 확인한 뒤에만 실행하세요.

printf 'yes\n' | terraform init \
  -backend-config=backend-connection.hcl \
  -backend-config=reports.s3.tfbackend \
  -migrate-state

S3 백엔드 구성이 성공하고 초기화가 완료되어야 합니다. 이미 존재하는 환경으로 전환하기 위한 방법으로 마이그레이션을 사용하지 마세요. 기존 상태를 선택하는 것은 다른 작업이며 이 과정의 뒷부분에서 다룹니다.

새 위치에서 매핑을 확인합니다.

terraform state show aws_s3_bucket.reports

리소스 ID는 여전히 migration-daily-reports여야 합니다. 이제 S3에 실제 상태 객체가 있는지 확인합니다.

aws s3api \
  head-object \
  --bucket maintenance-team-state \
  --key reports/production.tfstate

ETag와 VersionId는 저장된 상태 객체를 보여 줍니다. 이 메타데이터만으로는 충분하지 않습니다. 백그라운드 검사는 리소스 매핑도 읽고 기존 보고서의 식별 정보와 바이트를 비교합니다.

terraform plan

No changes가 표시되어야 합니다. 상태 마이그레이션으로 업무용 버킷이 다시 생성되어서는 안 됩니다.

원격 상태의 새 버전 살펴보기

이 단계에서는 검토한 구성 업데이트 하나를 수행하고 그 결과로 생긴 상태 기록을 살펴봅니다. 버전 관리는 이전 상태 객체를 보존합니다. 이 실습에서는 손상된 상태를 복구하는 대신 기록을 관찰합니다.

버킷 이름, 소유자, 삭제 설정은 변경하지 않고 리비전 태그를 추가합니다.

cat > main.tf <<'HCL'
resource "aws_s3_bucket" "reports" {
  bucket        = "migration-daily-reports"
  force_destroy = false
  tags = { Owner = "reporting", Revision = "two" }
}
HCL

계획을 저장하여 검토합니다.

terraform plan -out=revision.tfplan

0 to add, 1 to change, 0 to destroy가 표시되어야 합니다. 이 제자리 업데이트만 적용합니다.

terraform apply revision.tfplan

백엔드 객체의 버전을 확인합니다.

aws s3api \
  list-object-versions \
  --bucket maintenance-team-state \
  --prefix reports/production.tfstate

마이그레이션과 업데이트 후에는 최소 두 개의 상태 버전이 있어야 합니다. 이는 관리 기록을 나타내며, 다른 버킷에 있는 업무용 보고서의 버전과는 별개입니다.

aws s3 \
  cp s3://migration-daily-reports/report.txt -

보고서는 Daily sales: 120 orders로 유지됩니다. AWS View에는 업무용 버킷, 재무 참조 버킷, 백엔드 버킷이 각각 별도로 표시됩니다. 상태 파일에는 민감한 값이 포함될 수 있으므로 이 연습에 필요한 메타데이터만 확인하세요.

terraform plan

No changes가 표시되어야 합니다. 별도의 정리 단계를 시작하기 전에 이 상태가 정상 작동하는지 확인하세요.

백엔드를 유지하면서 업무용 리소스 삭제하기

이 단계에서는 기능과 데이터 보존 검사를 통과한 뒤 이 일회용 업무 스택의 사용을 종료합니다. 플랫폼 팀의 백엔드와 독립적인 재무 참조 리소스는 스택의 삭제 범위 밖에 있습니다.

force_destroy = false는 Terraform이 버전 관리되는 보고서 버킷의 내용을 자동으로 지우지 못하게 합니다. 이 실습의 보고서를 삭제하기 전에 원래 보고서 버전을 명확히 식별하세요. 명령 치환으로 ID를 저장하고, 비밀이 아닌 이 식별자를 표시합니다.

VERSION_ID=$(aws s3api \
  head-object \
  --bucket migration-daily-reports \
  --key report.txt \
  --query VersionId \
  --output text)
echo "$VERSION_ID"

정확히 해당하는 일회용 버전을 삭제한 다음 업무용 리소스를 삭제합니다. 이 명령들은 이전 단계의 보존 검사를 마친 후에만 의도적으로 보고서 제공을 종료합니다.

aws s3api \
  delete-object \
  --bucket migration-daily-reports \
  --key report.txt \
  --version-id "$VERSION_ID"
terraform destroy -auto-approve

-auto-approve는 확인 프롬프트를 건너뜁니다. 여기서는 방금 검토한 일회용 업무 버킷 하나에만 사용하세요. 1 destroyed가 표시되어야 합니다.

관리 기록이 여전히 백엔드에 존재하는지 확인합니다.

aws s3api \
  head-object \
  --bucket maintenance-team-state \
  --key reports/production.tfstate

백엔드는 남아 있으며, 이제 관리 중인 업무용 리소스가 없는 상태를 보관합니다. 재무 참조 리소스는 여전히 사용할 수 있어야 합니다. 스택을 삭제해도 백엔드에서 사용하는 스토리지는 삭제되지 않습니다. 소유자를 위해 해당 백엔드를 온전히 보존하세요. 일반 apply를 다시 실행하면 구성에 정의된 업무용 버킷이 재생성되므로 실행하지 마세요.

백엔드 구성과 Terraform 자체 잠금 파일에 대한 내용은 S3 백엔드 문서를 참고하세요.

요약

프로바이더와 백엔드의 역할을 구분하고, 기존 매핑을 백업한 뒤 S3로 마이그레이션하고, 상태 버전을 관찰하며, 독립적으로 소유된 백엔드를 삭제하지 않고 업무 스택을 삭제했습니다.