INCIDENT ANALYSIS · 2026.11.12

PPI Web prod 배포 실패 분석

마지막 업데이트 2026-11-12

대상 버전 3.20.0 · 분석 기준 커밋 b0e1e91c0c18e1e530221c9f7e0dfb12068f4cdf

디스크 공간 소진 경위 확인

배포가 서버의 정적 파일 설치 단계에서 static_budget_exceeded 오류로 중단됐다. Prometheus 기록에 따르면 신규 이미지 다운로드 중 2a 서버의 일반 사용자 가용 공간이 0 GiB에 도달했다. 정적 저장소 자체 제한 검사도 같은 오류를 출력하므로 로그만으로 개별 검사 조건을 구분할 수는 없다.

확인된 배포 흐름

  1. Web 이미지 빌드와 업로드가 완료됐다.
  2. 배포 스크립트가 새 이미지의 정적 파일을 준비하고 서버에 설치했다.
  3. 설치 작업이 install: static_budget_exceeded를 반환했고 배포 작업이 실패했다.

정적 파일 준비는 롤링 배포의 트래픽 전환보다 먼저 실행된다. 따라서 이 실패로 새 버전으로의 롤링 전환은 시작되지 않았다. 현재 서비스 상태는 별도 확인이 필요하다.

같은 오류가 발생하는 두 조건

원격 처리기는 두 경우를 모두 static_budget_exceeded로 변환한다. 로그에는 어느 조건에 걸렸는지, 당시 사용량이나 실패한 서버가 기록되지 않았다.

재발 가능성이 있는 구조

정적 저장소는 현재 버전과 이전 버전, 보호 기간 중인 릴리스 등을 보존하면서 새 릴리스를 추가한다. 정리는 양쪽 서버 배포가 성공한 후에 실행된다.

따라서 보존된 파일과 새 파일의 설치 중 사용량이 제한을 넘으면 정리 단계에 도달하지 못할 수 있다. 이번 실패에서 실제로 이 조건이 발생했는지는 확인되지 않았다.

원인 확정을 위한 확인

  1. 두 prod 서버에서 /var/lib/ppi-web-static/prod가 위치한 파일시스템의 여유 공간과 저장소 사용량을 확인한다.
  2. 릴리스별 크기와 보호 상태를 확인하고 신규 이미지의 정적 파일 크기와 비교한다.
  3. 결과에 따라 실제 디스크 부족을 해결하거나, 필요한 보존량을 기준으로 256 MiB 제한과 정리 순서를 검토한다.

운영 서버 조회와 파일 삭제는 이 분석에서 수행하지 않았다.

운영 서버 확인 결과

11월 12일 11:37 KST에 2a로 추정되는 인스턴스 i-0d11c2fac01c0255d를 SSM으로 조회했다. 긴급 삭제 이후 루트 디스크는 20 GiB 중 63%를 사용했고 7.1 GiB가 남아 있었다. 삭제 전 개별 이미지 목록과 각 이미지의 점유량은 확인하지 못했다.

Docker 이벤트에는 10:45 KST 웹 이미지 다운로드와 10:51, 10:56 이미지 삭제가 기록되어 있다. 삭제 전 각 이미지의 크기와 삭제 주체는 확인되지 않았다.

이미지 보관과 실패 시 정리

배포는 GHCR의 ghcr.io/dobraindev/ppi/ppi-web-prod에서 새 이미지를 서버로 내려받는다. 정상 배포 후 정리는 현재 이미지와 직전 이미지를 보호한다. 두 개는 보존 정책이며 저장 개수의 상한은 아니다.

새 이미지를 내려받는 동안 기존 이미지와 새 이미지가 함께 존재한다. 다운로드 완료 후 배포가 실패하면 양쪽 서버의 성공 후에 실행되는 정리에 도달하지 못하므로 이미지가 남을 수 있다. 다운로드 도중 실패한 경우에는 Docker가 받은 레이어와 임시 데이터를 어떻게 정리했는지에 따라 다르다.

이번 배포는 이미지 다운로드가 완료된 뒤 정적 파일 설치 단계에서 실패했다. Prometheus 가용 공간 감소와 Docker pull 이벤트의 시점은 일치한다. 실패 후 정리 누락은 재발 위험이지만, #306 이전 공간 부족의 원인으로 입증되지는 않았다.

실패 시 자동 정리를 추가하려면 배포 코드 수정이 필요하다. 롤링 배포 중인 서버의 현재 이미지와 롤백에 필요한 이전 이미지를 보호하고, 컨테이너가 참조하지 않는 관리 대상 이미지만 삭제해야 한다.

삭제 전 가용 공간 추이

모니터링 서버의 Prometheus node_filesystem_avail_bytes와 2a 서버의 Docker 이벤트를 대조했다. 아래 시각은 KST이며 수치는 일반 사용자에게 사용 가능한 공간이다.

#305는 성공 후 정리를 실행했다. 코드는 현재·직전 이미지와 컨테이너가 참조하는 이미지 등을 보호한다. 따라서 정리 실행 자체가 이전 이미지의 삭제를 뜻하지는 않는다. #305 후 감소한 공간이 새 이미지 추가 시점과 맞물리지만 당시 이미지별 목록과 크기는 남지 않아 개별 점유량을 확정할 수 없다.

배포 #305 · 배포 #306

HA 전환과 3.17.0 이미지 보존

11월 12일 10:56 KST에 삭제된 이미지 ae5d2b6019b2의 코드 리비전은 3.17.0 배포 #302와 일치한다. 서버의 단일 서버 보존 기록에서도 이 이미지 ID가 직전 이미지로 기록돼 있다.

  1. 11월 10일 단일 서버 배포 #304는 기존 3.17.0 이미지를 롤백용 직전 이미지로 보존했다. 단일 서버 기록 /var/lib/ppi-web-images/prod/state.json의 previous가 삭제된 이미지 ID와 일치한다. 이 기록의 관리 목록에는 3.17.0 배포 digest 5f5189a…도 있다.
  2. 이후 HA 전환 작업은 별도의 정적 저장소 상태 /var/lib/ppi-web-static/prod/state.json을 사용했다. 조사 시점의 HA managed_images 목록에는 3.17.0 digest가 없었다.
  3. HA 정리는 HA 관리 목록에 기록된 digest만 검사한다. 단일 서버 관리 목록을 가져오는 경로는 조사한 코드에서 확인되지 않았다. 그 결과 이전 이미지가 정리 대상에서 빠졌을 가능성이 높다.

단일 서버 상태와 HA 상태는 긴급 삭제 이후 조회한 기록이다. 삭제 당시 이미지의 전체 태그·digest 목록과 각 정리 시도의 상세 결과는 남아 있지 않으므로 개별 이미지가 어떤 조건으로 제외됐는지는 직접 확인하지 못했다.

HA 이미지 정리 코드 · HA 준비 및 정리 순서

디스크 부족 시 수동 이미지 정리

이 절차는 조사 당시 확인한 prod 2a 인스턴스를 대상으로 한다. 접속 대상과 환경을 먼저 확인한다. 현재 이미지와 롤백에 필요한 직전 이미지, 컨테이너가 참조하는 이미지는 보존한다.

aws ssm start-session --profile ppi-diagnostics --region ap-northeast-2 \
  --target i-0d11c2fac01c0255d

파일시스템 여유 공간, 이미지 사용량, 컨테이너와 보존 상태를 확인한다.

df -h /
sudo docker system df -v
sudo docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
sudo docker inspect ppi-web-prod --format '{{.Image}}'
sudo cat /var/lib/ppi-web-static/prod/state.json

state.json의 current와 previous는 보호해야 할 릴리스 digest다. 삭제 후보의 이미지 ID, digest, 태그와 컨테이너 참조를 비교한다. digest가 없거나 현재·직전 이미지와의 대응이 불확실하면 삭제하지 않는다. 다른 서비스 이미지도 삭제 대상으로 추정하지 않는다.

sudo docker image inspect <이미지_ID> \
  --format 'ID={{.Id}} Digests={{json .RepoDigests}} Tags={{json .RepoTags}}'
sudo docker ps -a --filter ancestor=<이미지_ID> \
  --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'

불필요한 이미지이며 보호 대상과 컨테이너에서 사용하지 않는 것을 확인한 경우에만 해당 ID를 지정해 삭제한다. 공유 레이어가 있으면 표시된 이미지 크기와 실제 회수 공간이 다를 수 있다.

sudo docker image rm <이미지_ID>
df -h /

일괄 정리 금지. docker system prune -a와 docker image prune -a는 사용 중이 아닌 롤백 이미지를 삭제할 수 있다. 강제 삭제 옵션을 사용하지 않는다.

근거와 확인 범위