Terraform과 같은 IaC(Infrastructure as Code) 도구에서 State 파일은 현재 클라우드 인프라의 실제 상태와 Terraform이 관리하는 상태를 매핑하는 가장 중요한 단일 정보 출처입니다. terraform apply 실행 중 충돌이나 오류가 발생하면, State 파일이 실제 인프라와 동기화되지 않아 상태 불일치(State Drift)가 발생하거나, State 파일 자체가 잠금 해제되지 않아(Locking Issue) 다음 작업이 불가능해집니다.
State 파일 손상 및 충돌 발생 시 복구하는 핵심 전략은 terraform state 명령어를 사용하여 State 파일을 수동으로 편집하거나, Lock을 강제로 해제하는 것입니다.
Terraform과 같은 IaC(Infrastructure as Code) 도구에서 State 파일은 현재 클라우드 인프라의 실제 상태와 Terraform이 관리하는 상태를 매핑하는 가장 중요한 단일 정보 출처입니다. terraform apply 실행 중 충돌이나 오류가 발생하면, State 파일이 실제 인프라와 동기화되지 않아 상태 불일치(State Drift)가 발생하거나, State 파일 자체가 잠금 해제되지 않아(Locking Issue) 다음 작업이 불가능해집니다.
State 파일 손상 및 충돌 발생 시 복구하는 핵심 전략은 terraform state 명령어를 사용하여 State 파일을 수동으로 편집하거나, Lock을 강제로 해제하는 것입니다.
1. State 파일 잠금(Locking) 문제 해결
배포 중 충돌이 발생하면, Terraform은 다른 사용자의 동시 작업을 방지하기 위해 State 파일에 잠금(Lock)을 설정합니다. 충돌로 인해 작업이 비정상적으로 종료되면, 이 잠금이 해제되지 않고 남아 다음 apply나 plan 작업을 막습니다.
1.1. Lock 강제 해제 (Force Unlock)
State 파일 Lock은 원격 백엔드(Remote Backend, 예: S3, GCS)에서 관리됩니다.
| 명령어 | 설명 | 조치 시점 |
terraform force-unlock <LOCK_ID> | Lock이 걸린 State 파일의 Lock ID를 강제로 해제합니다. Lock ID는 잠금 오류 메시지에 표시됩니다. | apply 또는 plan 시 “Error acquiring state lock” 메시지가 나타날 때. |
| 주의 사항 | force-unlock은 다른 작업이 실제로 실행 중이 아닐 때만 사용해야 합니다. 동시 작업 중 강제 해제 시 데이터 손실이 발생할 수 있습니다. |
1.2. State 파일 백업 확인
원격 백엔드를 사용할 경우, Terraform은 상태를 변경하기 전에 State 파일의 이전 버전(Backup)을 자동으로 저장합니다. Lock이 해제된 후에도 상태 불일치가 의심되면, 백엔드 저장소(예: S3 버킷의 버전 관리)에서 마지막으로 성공했던 State 파일 버전을 복원하는 것을 고려합니다.
2. 상태 불일치(Drift) 및 리소스 동기화 복구
충돌 후 State 파일에 기록된 리소스 정보와 실제 클라우드에 존재하는 리소스 정보가 일치하지 않을 때 수동으로 상태를 동기화해야 합니다.
2.1. 실제 인프라 정보 가져오기 (Import)
실제 클라우드에 리소스가 생성되었지만, State 파일에 해당 정보가 누락된 경우(예: DB 인스턴스 생성 직후 충돌), import 명령을 사용하여 해당 리소스를 관리 대상으로 추가합니다.
| 명령어 | 설명 |
terraform import <RESOURCE_ADDRESS> <RESOURCE_ID> | **<RESOURCE_ADDRESS>**는 .tf 파일 내의 리소스 주소(예: aws_instance.web), **<RESOURCE_ID>**는 클라우드 콘솔에서 확인한 실제 리소스 ID를 사용합니다. |
| 예시 | terraform import aws_instance.web i-0498db7a19d8d67c9 |
2.2. State 파일에서 리소스 제거 (Remove)
State 파일에는 리소스 정보가 남아 있지만, 실제 클라우드에서는 리소스가 삭제되었거나 Terraform의 관리 대상에서 제외해야 할 때 사용합니다.
| 명령어 | 설명 |
terraform state rm <RESOURCE_ADDRESS> | State 파일에서 해당 리소스 주소와 관련된 정보를 제거합니다. 제거된 리소스는 다음 plan부터는 Terraform이 인식하지 않습니다. |
| 예시 | terraform state rm aws_instance.old_db |
2.3. State 파일 수동 편집 (Danger Zone)
terraform state pull로 현재 State 파일을 로컬로 다운로드하고, terraform state push로 수정한 파일을 원격 백엔드에 업로드할 수 있습니다. 이 방법은 JSON 파일 내부의 특정 필드만 수정해야 할 때 사용되지만, 오류 발생 위험이 매우 크므로 다른 방법이 없을 때만 사용해야 합니다.
- 주의: State 파일의 JSON 구조를 완벽하게 이해하고 있을 때만 시도하며, 수정 전 반드시 백업을 수행해야 합니다.
3. 재시도를 위한 환경 정리
재시도를 위한 환경 정리 State 파일이 성공적으로 복구된 후에도, 다음 terraform apply 명령이 원활하게 성공적으로 실행될 수 있도록 하기 위해 전체 환경을 철저히 정리하는 과정이 반드시 필요합니다.
State 파일이 복구된 후에도, 다음 apply가 성공적으로 실행되도록 하기 위해 환경을 정리해야 합니다.
- 실제 인프라 상태 점검: 충돌이 발생한 정확한 시점에 클라우드 환경에서 생성된 리소스들 중 불완전하게 배포되었거나, 유휴 상태로 방치되어 있는 리소스가 존재하는지 면밀히 확인해야 합니다. 이러한 리소스들은 수동으로 직접 삭제하거나, 앞서 설명한 terraform import 명령어를 통해 State 파일에 정상적으로 등록하거나, terraform state rm 명령어를 활용하여 State 파일에서 완전히 제거함으로써 깔끔하게 정리합니다.
taint상태 복구: terraform apply 과정에서 충돌이 발생하면 특정 리소스가 tainted 상태(즉, 손상된 것으로 표시된 상태)로 남게 됩니다. 이 경우 다음 apply 실행 시 해당 리소스는 강제로 삭제된 후 재생성되도록 설계되어 있습니다. 그러나 해당 리소스를 반드시 보존해야 하는 상황이라면, terraform untaint <RESOURCE_ADDRESS> 명령어를 사용하여 taint 표시를 명시적으로 해제함으로써 불필요한 삭제와 재생성을 방지할 수 있습니다.- 코드 오류 수정: State 파일의 복구 작업과는 별개로, Terraform 코드(.tf 파일) 자체에 존재하는 논리적 오류나 버그가 충돌의 근본 원인일 가능성을 배제할 수 없으므로, 관련 코드를 신속히 수정한 후 terraform validate 명령으로 문법 및 구조적 유효성을 확인하고, terraform plan 명령을 실행하여 예상되는 변경 사항을 사전에 철저히 검증해야 합니다.
Disclaimer: 본 블로그의 정보는 개인의 단순 참고 및 기록용으로 작성된 것이며, 개인적인 조사와 생각을 담은 내용이기에 오류가 있거나 편향된 내용이 있을 수 있습니다.