PPI Web prod 배포 실패 분석
마지막 업데이트 2026-11-12
대상 버전 3.20.0 · 분석 기준 커밋 b0e1e91c0c18e1e530221c9f7e0dfb12068f4cdf
배포가 서버의 정적 파일 설치 단계에서 static_budget_exceeded 오류로 중단됐다. Prometheus 기록에 따르면 신규 이미지 다운로드 중 2a 서버의 일반 사용자 가용 공간이 0 GiB에 도달했다. 정적 저장소 자체 제한 검사도 같은 오류를 출력하므로 로그만으로 개별 검사 조건을 구분할 수는 없다.
확인된 배포 흐름
- Web 이미지 빌드와 업로드가 완료됐다.
- 배포 스크립트가 새 이미지의 정적 파일을 준비하고 서버에 설치했다.
- 설치 작업이
install: static_budget_exceeded를 반환했고 배포 작업이 실패했다.
정적 파일 준비는 롤링 배포의 트래픽 전환보다 먼저 실행된다. 따라서 이 실패로 새 버전으로의 롤링 전환은 시작되지 않았다. 현재 서비스 상태는 별도 확인이 필요하다.
같은 오류가 발생하는 두 조건
- 실제 디스크 여유 공간 부족. 저장소가 위치한 파일시스템의 남은 공간이 설치할 파일과 예비 공간 1 MiB의 합보다 적다.
- 정적 저장소 예산 초과. 저장소 사용량과 설치할 파일, 예비 공간의 합이 자체 제한인 256 MiB를 넘는다.
원격 처리기는 두 경우를 모두 static_budget_exceeded로 변환한다. 로그에는 어느 조건에 걸렸는지, 당시 사용량이나 실패한 서버가 기록되지 않았다.
재발 가능성이 있는 구조
정적 저장소는 현재 버전과 이전 버전, 보호 기간 중인 릴리스 등을 보존하면서 새 릴리스를 추가한다. 정리는 양쪽 서버 배포가 성공한 후에 실행된다.
따라서 보존된 파일과 새 파일의 설치 중 사용량이 제한을 넘으면 정리 단계에 도달하지 못할 수 있다. 이번 실패에서 실제로 이 조건이 발생했는지는 확인되지 않았다.
원인 확정을 위한 확인
- 두 prod 서버에서
/var/lib/ppi-web-static/prod가 위치한 파일시스템의 여유 공간과 저장소 사용량을 확인한다. - 릴리스별 크기와 보호 상태를 확인하고 신규 이미지의 정적 파일 크기와 비교한다.
- 결과에 따라 실제 디스크 부족을 해결하거나, 필요한 보존량을 기준으로 256 MiB 제한과 정리 순서를 검토한다.
운영 서버 조회와 파일 삭제는 이 분석에서 수행하지 않았다.
운영 서버 확인 결과
11월 12일 11:37 KST에 2a로 추정되는 인스턴스 i-0d11c2fac01c0255d를 SSM으로 조회했다. 긴급 삭제 이후 루트 디스크는 20 GiB 중 63%를 사용했고 7.1 GiB가 남아 있었다. 삭제 전 개별 이미지 목록과 각 이미지의 점유량은 확인하지 못했다.
/var/lib/docker는 약 8.4 GiB를 사용했다. 웹 이미지 두 개는 각각 약 3.5 GB였고 이미지별 고유 데이터는 약 3.4 GB였다.- 현재 웹 이미지에는
node_modules복사 레이어 약 884 MB,.next복사 레이어 약 469 MB,chown -R레이어 약 1.45 GB가 있다. - Nginx 로그는 약 900 MiB, systemd 저널은 약 356 MiB, 정적 파일 저장소는 약 27 MiB였다. 모두 긴급 삭제 이후 측정값이다.
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이며 수치는 일반 사용자에게 사용 가능한 공간이다.
- 11월 11일 11:00: 약 7.12 GiB. #305 이미지 다운로드 전이다.
- 11월 11일 11:03~11:07: 웹 이미지 pull 이벤트가 기록됐다. 11:10의 가용 공간은 약 3.67 GiB였다.
- 11월 12일 10:44: #306 다운로드 직전 가용 공간은 약 3.55 GiB였다.
- 10:45: 약 1.04 GiB로 감소했고, 10:46에는 0 GiB였다. #306은 정적 파일 설치 단계에서 실패했다.
- 10:51과 10:56: Docker 이미지 삭제 이벤트가 기록됐다. 10:52에는 약 3.54 GiB, 10:57에는 약 7.09 GiB가 사용 가능했다.
#305는 성공 후 정리를 실행했다. 코드는 현재·직전 이미지와 컨테이너가 참조하는 이미지 등을 보호한다. 따라서 정리 실행 자체가 이전 이미지의 삭제를 뜻하지는 않는다. #305 후 감소한 공간이 새 이미지 추가 시점과 맞물리지만 당시 이미지별 목록과 크기는 남지 않아 개별 점유량을 확정할 수 없다.
HA 전환과 3.17.0 이미지 보존
11월 12일 10:56 KST에 삭제된 이미지 ae5d2b6019b2의 코드 리비전은 3.17.0 배포 #302와 일치한다. 서버의 단일 서버 보존 기록에서도 이 이미지 ID가 직전 이미지로 기록돼 있다.
- 11월 10일 단일 서버 배포 #304는 기존 3.17.0 이미지를 롤백용 직전 이미지로 보존했다. 단일 서버 기록
/var/lib/ppi-web-images/prod/state.json의previous가 삭제된 이미지 ID와 일치한다. 이 기록의 관리 목록에는 3.17.0 배포 digest5f5189a…도 있다. - 이후 HA 전환 작업은 별도의 정적 저장소 상태
/var/lib/ppi-web-static/prod/state.json을 사용했다. 조사 시점의 HAmanaged_images목록에는 3.17.0 digest가 없었다. - HA 정리는 HA 관리 목록에 기록된 digest만 검사한다. 단일 서버 관리 목록을 가져오는 경로는 조사한 코드에서 확인되지 않았다. 그 결과 이전 이미지가 정리 대상에서 빠졌을 가능성이 높다.
단일 서버 상태와 HA 상태는 긴급 삭제 이후 조회한 기록이다. 삭제 당시 이미지의 전체 태그·digest 목록과 각 정리 시도의 상세 결과는 남아 있지 않으므로 개별 이미지가 어떤 조건으로 제외됐는지는 직접 확인하지 못했다.
디스크 부족 시 수동 이미지 정리
이 절차는 조사 당시 확인한 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.jsonstate.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는 사용 중이 아닌 롤백 이미지를 삭제할 수 있다. 강제 삭제 옵션을 사용하지 않는다.
근거와 확인 범위
- GitHub Actions 배포 로그. 2026-11-12 10:46 KST에
install: static_budget_exceeded로 종료했다. 원본 로그는 로컬 보관본을 분석했다. - 정적 저장소 용량 검사와 보호 정책
- 정적 파일 준비와 배포 후 정리 순서
- 오류 분류와 관리 이미지 정리
- 긴급 삭제 이후 SSM으로 확인한
df, Docker 이미지와 이벤트, 디렉터리별 사용량. 삭제 전 디스크의 구성은 포함하지 않는다.