--atomic 과 --wait 이 실제로 하는 일

한 줄 요약

--wait 은 "다 뜰 때까지 기다린다", --atomic 은 "다 못 뜨면 되돌린다" 이다. 이 둘을 안 쓰면 실패한 배포가 성공으로 보고된다.

왜 이게 필요했나

helm upgrade 는 기본적으로 매니페스트를 API 서버에 보내고 바로 성공을 반환한다. 파드가 실제로 뜨는지는 보지 않는다. 이미지 태그를 잘못 적어 ImagePullBackOff 가 나도 helm 은 STATUS: deployed 를 출력한다. CI 로그는 초록색이고, 사용자만 장애를 겪는다.

--wait 을 붙이면 helm 이 Deployment·StatefulSet·DaemonSet 의 준비 상태를 폴링한다. --timeout(기본 5분) 안에 준비되지 않으면 실패로 처리한다. 이제 CI 가 빨간불이 된다.

그런데 실패한 채로 두면 문제가 남는다. 새 리비전은 이미 만들어졌고 리소스는 반쯤 바뀐 상태다. --atomic 은 여기서 자동으로 helm rollback 을 걸어 이전 상태로 되돌린다. --atomic 은 --wait 을 포함한다 — 기다리지 않으면 실패를 알 수 없으니 당연하다.

어떻게 동작하나

helm upgrade demo ./chart \  --atomic \  --timeout 5m \  --history-max 10

이 한 줄이 배포 스크립트의 기본형이어야 한다. 그리고 timeout 값은 가장 느린 파드의 기동 시간 + 여유로 잡는다. 너무 짧으면 멀쩡한 배포가 롤백되고, 너무 길면 장애를 늦게 안다.

흔한 착각

--atomic 이 있으면 안전하다는 착각. atomic 은 쿠버네티스 리소스만 되돌린다. 훅으로 돌린 마이그레이션 Job 이 DB 를 이미 바꿨다면 그건 그대로 남는다. 그래서 스키마 변경은 앞뒤 버전이 모두 견디는 형태로 나눠서 배포한다(확장 → 배포 → 정리).

timeout 을 늘리면 해결된다는 착각. ImagePullBackOff 는 기다려도 낫지 않는다. 30분 timeout 은 장애를 30분 늦게 알려 줄 뿐이다.

실무에서 진짜 중요한 것

--wait 이 보는 것은 워크로드의 준비 상태지 "서비스가 정상"이 아니다. 파드가 Ready 여도 응답이 500 일 수 있다. 그래서 배포 파이프라인의 마지막에는 항상 바깥에서 때려 보는 스모크 테스트가 있어야 한다. helm 이 초록불을 줬다는 것과 사용자가 쓸 수 있다는 것은 다른 명제다.