POD RESTART LOOP
SAFE OPERATING BOUNDARY
적용 전 기록한 정상 revision과 백업 manifest를 기준으로 되돌립니다. Deployment rollback은 컨테이너 이미지·Pod template만 되돌릴 뿐 외부 DB migration과 영구 볼륨 데이터는 복구하지 않으므로, 데이터 호환성을 확인하고 승인된 revision 또는 GitOps 변경으로 복원한 뒤 rollout·Ready·오류율을 재검증합니다.
BEFORE YOU START
CHECK THE BRANCH
exitCode, reason, finishedAt과 --previous 로그를 같은 재시작 회차로 묶어 봅니다. 설정 누락·마이그레이션 실패·의존 서비스 오류라면 probe 지연부터 늘려 원인을 숨기지 않습니다.
컨테이너 limit 초과와 노드 전체 MemoryPressure를 구분합니다. limit만 즉시 높이기 전에 실제 working set, 누수 여부, request와 노드 allocatable을 함께 확인합니다.
startup probe가 없거나 검사 경로·포트·timeout이 실제 애플리케이션 기동 특성과 맞지 않을 수 있습니다. readiness 실패는 트래픽 제외, liveness·startup 실패는 재시작으로 이어진다는 차이를 반영합니다.
개별 Pod 수정보다 Deployment·StatefulSet의 최근 revision과 ConfigMap·Secret 참조 변경을 먼저 확인합니다. 생성된 Pod를 직접 편집하면 다음 재생성 때 사라집니다.
FOLLOW THE FLOW
NAMESPACE와 POD를 실제 값으로 바꾸고 재시작 횟수, 현재·직전 종료 상태, 최근 이벤트를 한 번에 확인합니다.
kubectl get pod -n <NAMESPACE> <POD> -o widekubectl get pod -n <NAMESPACE> <POD> -o jsonpath='{range .status.containerStatuses[*]}{.name}{" current="}{.state}{" last="}{.lastState}{" restarts="}{.restartCount}{"\n"}{end}'kubectl events -n <NAMESPACE> --for pod/<POD> --types=Warning,NormalWaiting.reason, terminated.reason·exitCode와 이벤트 시각이 같은 원인을 가리키는지 봅니다. OOMKilled, probe 실패, 애플리케이션 종료를 먼저 분류합니다.
이미지 가져오기 오류라면 ImagePullBackOff 가이드로, Pending이면 스케줄링·PVC·Node 가이드로 이동합니다.
재시작 뒤 현재 로그만 보면 최초 오류가 사라질 수 있으므로 --previous 결과를 반드시 함께 봅니다. 민감정보가 포함될 수 있어 공유 전 마스킹합니다.
kubectl get pod -n <NAMESPACE> <POD> -o jsonpath='{.spec.containers[*].name}{"\n"}'kubectl logs -n <NAMESPACE> <POD> -c <CONTAINER> --tail=200 --timestampskubectl logs -n <NAMESPACE> <POD> -c <CONTAINER> --previous --tail=200 --timestamps현재 로그는 새 실행 회차, --previous는 직전 종료 회차입니다. 직전 로그 마지막 오류가 종료 reason·exitCode와 일치하는지 확인합니다.
애플리케이션 자체 종료면 설정과 의존성을, OOMKilled면 리소스를, probe 실패면 검사 정의를 각각 확인합니다.
Pod 원본 리소스 요청·제한과 가능한 경우 Metrics API 사용량을 비교하고 노드 압박도 함께 확인합니다.
kubectl get pod -n <NAMESPACE> <POD> -o jsonpath='{range .spec.containers[*]}{.name}{" requests="}{.resources.requests}{" limits="}{.resources.limits}{"\n"}{end}{range .status.containerStatuses[*]}{.name}{" reason="}{.lastState.terminated.reason}{" exit="}{.lastState.terminated.exitCode}{"\n"}{end}'kubectl top pod -n <NAMESPACE> <POD> --containerskubectl describe node <NODE>limit 근처에서 OOMKilled면 누수·정상 최대 사용량과 limit을 재산정합니다. Node MemoryPressure가 True면 개별 Pod 외에 노드 수용량 문제도 해결해야 합니다.
기존 관측 구간이 부족하면 limit을 추측으로 변경하지 말고 지표와 힙·프로세스 진단을 먼저 확보합니다.
실패 Pod가 아니라 이를 관리하는 Deployment·StatefulSet의 probe, 포트, 리소스와 최근 rollout 이력을 확인합니다.
kubectl get pod -n <NAMESPACE> <POD> -o jsonpath='{range .metadata.ownerReferences[*]}{.kind}{"/"}{.name}{"\n"}{end}'kubectl get deployment -n <NAMESPACE> <DEPLOYMENT> -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{" image="}{.image}{" command="}{.command}{" args="}{.args}{" resources="}{.resources}{" startupProbe="}{.startupProbe}{" livenessProbe="}{.livenessProbe}{" readinessProbe="}{.readinessProbe}{"\n"}{end}'kubectl rollout history deployment/<DEPLOYMENT> -n <NAMESPACE>startupProbe 부재, 잘못된 path·port, 너무 짧은 timeout·failureThreshold, 변경된 command·args·resource limit을 이전 정상 revision과 비교합니다.
수정안은 소스 관리 manifest에서 만들고 diff, 백업, 승인, 검증, 되돌리기 순서를 정합니다.
이 단계부터 클러스터 상태가 바뀝니다. 정상 revision과 현재 manifest를 보관하고, 애플리케이션 원인에 맞는 한 가지 수정만 검토된 파일로 적용합니다.
install -d -m 0700 "<APPROVED_BACKUP_PATH>"
umask 077
kubectl get deployment -n <NAMESPACE> <DEPLOYMENT> -o yaml > "<APPROVED_BACKUP_PATH>/deployment.before.yaml"
chmod 0600 "<APPROVED_BACKUP_PATH>/deployment.before.yaml"
stat -Lc '%a %U:%G %n' "<APPROVED_BACKUP_PATH>/deployment.before.yaml"kubectl diff --server-side -f <REVIEWED_MANIFEST.yaml>kubectl apply --server-side -f <REVIEWED_MANIFEST.yaml>kubectl rollout status deployment/<DEPLOYMENT> -n <NAMESPACE> --timeout=5m
kubectl get pods -n <NAMESPACE> -l <LABEL_SELECTOR> -o wide새 Pod가 Ready이고 restartCount가 더 늘지 않으며 서비스 지표가 정상이어야 합니다. rollout timeout은 성공이 아니므로 이벤트와 새 Pod 로그를 다시 확인합니다.
실패하면 kubectl rollout undo를 즉시 실행하기보다 보존한 revision·manifest와 데이터 마이그레이션 호환성을 확인한 뒤 승인된 revision으로 되돌리고, 재발 방지를 위해 메모리·재시작·probe 실패 알림과 부하 기반 값을 운영 기준에 반영합니다.
PRIMARY REFERENCES
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.