study.

잘못된 이미지 배포를 조사하고 복구하기 · Kubernetes

존재하지 않는 태그로 실패를 만든 뒤 근거를 확인하고 이전 템플릿으로 돌아갑니다.

← Kubernetes

진도·퀴즈와 함께 학습하기

먼저, 개념을 잡아볼게요.

롤아웃과 가용성

Deployment는 새 템플릿으로 Pod를 교체합니다. 롤링 업데이트 중 일부 기존 Pod가 남을 수 있어 새 Pod 실패가 곧 모든 서비스 중단이라는 뜻은 아닙니다.

이벤트로 원인 좁히기

이미지 태그 오류는 이미지 pull 단계에서 드러납니다. Pending처럼 보이는 상태만 읽지 말고 describe와 Events로 상세 원인을 확인합니다.

롤백의 범위

rollout undo는 이전 Pod 템플릿으로 되돌립니다. 외부 데이터베이스 변경이나 독립된 ConfigMap까지 되돌리는 전체 시스템 복구가 아닙니다.

왜 필요한가요?

잘못된 이미지 태그는 새 Pod를 만들지만 이미지를 가져오지 못하게 할 수 있습니다. 기존 버전이 남아 응답하더라도 새 배포가 성공한 것은 아닙니다.

차례대로 이해하기

실패한 revision 식별

Deployment의 현재 템플릿, 새 ReplicaSet, 새 Pod 이벤트를 연결해 봅니다. rollout status의 타임아웃은 기다리던 조건을 시간 안에 만족하지 못했다는 뜻이며 원인 자체는 이벤트에서 찾아야 합니다.

복구 후 결과 비교

undo 뒤에도 rollout 완료와 실제 이미지·Ready 수를 확인합니다. 명령의 성공 메시지만 읽지 말고 이전에 실패했던 조건이 해소됐는지를 같은 방법으로 다시 검사하세요.

직접 실행하며 익혀보세요.

kubectl과 개인 실습용 Kubernetes 클러스터, POSIX 셸이 필요합니다. 매 실습에서 context를 확인하고 전용 namespace를 사용하세요. 실습별 정리는 해당 namespace의 모든 리소스를 삭제합니다.

정상 Deployment에 의도적으로 존재하지 않는 이미지 태그를 지정하세요. rollout 대기 실패는 예상한 결과이며 이벤트를 읽은 뒤 undo합니다.

kubectl config current-context
kubectl create namespace study-k8s-recovery --dry-run=client -o yaml | kubectl apply -f -
kubectl create deployment web --image=nginx:stable-alpine -n study-k8s-recovery --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout status deployment/web -n study-k8s-recovery --timeout=120s
kubectl set image deployment/web nginx=nginx:study-missing-tag-20261117 -n study-k8s-recovery
kubectl rollout status deployment/web -n study-k8s-recovery --timeout=30s || true
kubectl get pods -n study-k8s-recovery
kubectl get events -n study-k8s-recovery --sort-by=.metadata.creationTimestamp
kubectl rollout undo deployment/web -n study-k8s-recovery
kubectl rollout status deployment/web -n study-k8s-recovery --timeout=120s
kubectl get deployment web -n study-k8s-recovery -o jsonpath='{.spec.template.spec.containers[0].image}'

이렇게 확인하세요

Events에 이미지 조회 실패가 나타나고 롤백 뒤 Ready가 회복돼야 합니다. 네트워크 차단이나 레지스트리 제한도 pull 오류를 만들 수 있으므로 메시지로 구분하세요. 복구 후 이미지는 nginx:stable-alpine입니다.

실습 리소스 정리

결과 확인을 마친 뒤 실행하세요. 이 실습에서 만든 리소스와 보존할 데이터가 없는지 확인합니다.

kubectl delete namespace study-k8s-recovery

응용해보기

이전 revision으로 되돌렸지만 앱 설정은 여전히 새 값입니다. 왜 그럴 수 있을까요?

생각해본 뒤 풀이 보기

롤백은 Pod 템플릿을 복구하며 같은 이름으로 참조한 ConfigMap의 내용을 과거로 돌리지는 않습니다. 이미지와 설정을 어떤 버전 단위로 묶어 관리할지 별도 배포 전략이 필요합니다.

잠깐, 이해했는지 확인해볼까요?

rollout undo가 직접 되돌리는 주된 대상은?

  1. 모든 외부 데이터
  2. 이전 Pod 템플릿
  3. 클러스터의 모든 Secret
  4. 노드 운영체제
생각해본 뒤 풀이 보기

이전 Pod 템플릿

Deployment 롤백은 이전 Pod 템플릿을 복원합니다. 애플리케이션 외부 상태까지 함께 복구하지 않습니다.

공식 문서 · 잘못된 이미지 배포를 조사하고 복구하기