Kubernetes ProgressDeadlineExceeded 해결: rollout timeout·readiness·새 Pod 점검

AI로 직접 제작한 개념 일러스트입니다. 기존 서비스 가용성과 새 버전 배포 진행을 나누어 점검합니다.

Kubernetes 배포에서 “ProgressDeadlineExceeded”가 표시되거나 kubectl rollout status가 시간 초과로 끝나나요? 먼저 Deployment가 새 버전으로 진행하지 못한 것인지, 명령줄의 대기 제한만 끝난 것인지 구분해야 합니다. 새 Pod의 이벤트·준비 상태·실제 가용 복제본을 읽으면 이미지 문제, 스케줄링, readiness, 자원 제한을 분리할 수 있습니다. 제한 시간을 무작정 늘리기 전에 멈춘 단계를 확인하세요.

1. 명령의 --timeout과 Deployment 진행 제한은 다릅니다

kubectl rollout status 안내의 --timeout은 상태 확인 명령이 얼마나 기다릴지를 정합니다. Deployment의 spec.progressDeadlineSeconds는 컨트롤러가 진행 지연을 상태로 보고하는 기준입니다. CLI의 대기가 끝났다고 Deployment에 반드시 ProgressDeadlineExceeded가 기록돼 있는 것은 아닙니다. 두 값을 같은 제한으로 설명하면 원인 판단을 놓치기 쉽습니다.

Kubernetes Deployment 공식 문서는 진행 실패가 감지되면 Progressing=False, reason=ProgressDeadlineExceeded를 보고한다고 설명합니다. Kubernetes Deployment 컨트롤러가 이 이유만으로 자동 롤백하는 것은 아닙니다. CI/CD나 별도 오케스트레이터가 추가 대응을 수행하는지는 해당 시스템의 정책으로 확인합니다.

2. 실패 상태를 증상별로 나누는 표

확인한 상태	다음 조사 대상	피해야 할 결론
CLI 대기 시간 초과만 있음	현재 Deployment 조건·최신 revision	배포가 자동 취소·롤백됐다고 판단
새 Pod가 Pending	스케줄러 이벤트·자원·quota·스토리지	시간만 늘리면 해결된다고 판단
ImagePullBackOff	태그·레지스트리 인증·접근 경로	readiness만 수정
Pod 실행 중이나 Ready 아님	readiness 경로·포트·의존 서비스	Running을 서비스 준비 완료로 판단
컨테이너 재시작 반복	종료 코드·이전 로그·프로브·메모리	Deployment 시간만 확대
옛 복제본은 정상, 새 복제본만 실패	새 ReplicaSet 설정과 가용성	기존 트래픽도 모두 끊겼다고 단정

Available=True와 Progressing=False가 함께 나타나는 상황도 있습니다. 이전 복제본이 최소 가용성을 유지하는 동안 새 버전 전개가 멈췄을 수 있기 때문입니다. 업데이트된 수와 가용한 수, 이전 ReplicaSet의 수를 함께 봅니다. 배포 진행 실패와 사용자 요청 전체 실패는 별도로 확인해야 합니다.

3. context·Deployment·새 ReplicaSet을 차례로 조회하기

다음은 demo 네임스페이스의 web Deployment를 조회하는 가상 예시입니다. 실제 context·네임스페이스·이름·권한에 맞게 바꿉니다. 수정 명령은 포함하지 않았습니다. 상태가 변하는 중일 수 있으므로 명령 실행 시각과 revision도 함께 기록하면 서로 다른 시점의 출력을 잘못 비교하는 일을 줄일 수 있습니다.

kubectl config current-context
kubectl -n demo get deployment web -o wide
kubectl -n demo describe deployment web
kubectl -n demo get rs -l app=web
kubectl -n demo get pods -l app=web -o wide

app=web은 예시 레이블이므로 Deployment의 실제 selector와 맞는지 먼저 확인하세요. describe에서 ReplicaFailure·Progressing·Available 조건과 이벤트를 보고, 새 ReplicaSet이 생성됐는지·원하는 복제본 수로 늘었는지·새 Pod가 준비됐는지 순서대로 읽습니다. 여러 rollout이 겹쳤다면 어느 revision의 결과인지 확인해야 합니다.

kubectl -n demo rollout history deployment/web
kubectl -n demo rollout status deployment/web --timeout=60s
kubectl -n demo get deployment web -o yaml

60s는 설명용 CLI 대기값이며 운영에 권장하는 진행 제한이 아닙니다. 이 명령의 시간 초과와 Deployment 조건을 별도로 대조합니다. 출력된 YAML에 민감한 환경 설정이 있을 수 있으므로 운영 구성 전체를 공개 게시판에 그대로 공유하지 않습니다.

4. readiness 실패와 재시작 원인을 구분하기

readiness·liveness·startup probe 안내는 readiness가 트래픽을 받을 준비 상태에 영향을 주고, liveness와 startup은 다른 목적을 가진다고 설명합니다. 새 Pod가 Running이어도 readiness가 실패하면 새 버전이 가용 복제본으로 준비되지 않을 수 있습니다. 프로브 경로·포트·응답과 애플리케이션 초기화 시간을 확인하고, 의존 서비스 연결 실패도 분리해서 봅니다.

kubectl -n demo describe pod NEW_POD_NAME
kubectl -n demo logs NEW_POD_NAME -c APP_CONTAINER --tail=100
kubectl -n demo logs NEW_POD_NAME -c APP_CONTAINER --previous --tail=100

이름과 컨테이너를 실제 값으로 바꿉니다. --previous는 이전 컨테이너 인스턴스가 있을 때만 유효한 로그를 제공할 수 있습니다. readiness 실패만으로 컨테이너가 재시작된다고 설명하지 마세요. 스케줄링 단계의 실패는 Pod Pending 진단 글로, 준비된 Pod와 Service 연결의 문제는 Kubernetes Service 연결 진단 글로 이어서 구분할 수 있습니다.

5. 원인 수정·롤백 판단·완료 확인 체크리스트

• 새 Pod의 첫 실패 이벤트와 로그를 보존하고 이전 정상 버전과 달라진 설정을 찾는다.
• 이미지·권한·프로브·자원 중 확인된 원인만 수정한다.
• 롤백은 DB 스키마·설정·저장 데이터의 역호환성과 현재 정상 트래픽을 확인한 뒤 판단한다.
• 정상 초기화가 오래 걸리는 근거가 있을 때만 프로브·진행 제한·CI 대기를 각각 조정한다.
• 원하는 revision의 새 복제본 준비와 실제 서비스 응답·오류율을 다시 확인한다.

가상 예로 새 이미지가 잘못된 readiness 경로 /ready-new를 사용하지만 앱은 /ready만 제공한다면, 진행 제한을 늘리는 것보다 경로 불일치를 고치는 것이 원인 대응입니다. 반대로 실제 초기화가 오래 걸리는 정상 작업이라면 시작·준비 조건과 배포 정책을 함께 검토합니다. 이 사례는 설명용이며 실제 클러스터 장애나 성공 결과를 주장하지 않습니다.

6. 자주 묻는 질문

ProgressDeadlineExceeded면 자동으로 이전 버전으로 돌아가나요?
Deployment 컨트롤러는 상태를 보고합니다. 자동 롤백 여부는 CI/CD 등 상위 운영 시스템의 정책을 별도로 확인해야 합니다.

Pod가 Running이면 rollout 성공인가요?
준비 상태와 업데이트된 가용 복제본, 원하는 revision까지 확인해야 합니다. 실제 요청 정상 여부도 별도 점검합니다.

--timeout을 늘리면 오류가 해결되나요?
명령이 더 기다릴 뿐 원인이 제거되는 것은 아닙니다. Deployment 조건·이벤트·프로브·로그로 멈춘 단계를 먼저 확인하세요.

공식 자료 확인 기준: 2026-10-06. 예시와 계산은 설명용이며 실제 실행 결과·요금 견적이 아닙니다.

공식 출처와 함께 확인하기

• Kubernetes Deployment 공식 문서
• kubectl rollout status 안내
• readiness·liveness·startup probe 안내