Kubernetes 장애가 복잡해 보일 때 먼저 나누는 방법

대표 증상

Kubernetes 장애가 복잡해 보일 때 먼저 나누는 방법 상황은 하나의 설정값만 틀린 문제가 아니라 배포 경계, 런타임 상태, 캐시, 권한, 네트워크 경로가 함께 어긋났을 때 자주 나타납니다. 검색으로 들어온 사용자는 먼저 증상을 좁혀야 하므로, 이 가이드는 CrashLoopBackOff, readiness probe 실패, ingress 404, 서비스 엔드포인트 없음, CoreDNS 혼선, kubectl 디버깅을 먼저 정리할 때 적합합니다.를 기준으로 처음 확인할 신호를 정리합니다.

초반에는 재시작이나 전체 롤백부터 시도하기보다 영향 범위가 한 노드, 한 Pod, 한 job, 한 사용자, 한 경로에만 묶여 있는지 확인해야 합니다. 범위가 좁으면 최근 변경과 오래 남은 상태를 비교하고, 범위가 넓으면 공통 의존성부터 확인하는 편이 안전합니다.

먼저 확인할 신호

가장 먼저 볼 것은 오류 메시지의 마지막 줄이 아니라 같은 실패가 반복되는 경계입니다. ImagePullBackOff, readiness failed, no endpoints, ingress 404, works in pod but fails through service 같은 신호를 기준으로 문제를 묶으면 로그가 길어져도 원인 후보를 줄일 수 있습니다.

• Read pod status, events, and previous logs before editing manifests.
• Separate workload issues from service, ingress, and cluster routing issues.
• Review rollout, config, secret, and image changes before scaling anything.
• Confirm whether the scope is one workload, one namespace, or cluster-wide.
• Check whether the failure is startup-only, traffic-only, or dependency-only before calling it a pod incident.

로그와 CLI 예시

아래 명령은 정답을 바로 알려주는 명령이 아니라, 원인을 좁히기 위한 첫 관찰 지점입니다. 명령 결과를 복사해 두고 정상 시점 또는 같은 역할의 정상 리소스와 비교하면 재시도만 반복하는 시간을 줄일 수 있습니다.

kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --previous

흔한 오진

운영 장애에서 가장 위험한 패턴은 증상 이름을 원인으로 착각하는 것입니다. 같은 timeout, permission denied, rollout failure라도 실제 원인은 캐시, 권한 상속, Secret 범위, 오래된 클라이언트 연결, 프록시 헤더처럼 다른 층에 있을 수 있습니다.

• Restarting pods before collecting event history and previous container logs.
• Calling every 404 or timeout an ingress bug before checking endpoints, namespace drift, and service selectors.

안전한 복구 순서

복구는 가장 작은 단위에서 시작합니다. 먼저 읽기 전용 확인으로 현재 상태를 고정하고, 그다음 영향이 제한된 리소스에서 변경을 검증합니다. 서비스 전체 재시작, 캐시 전체 삭제, 보안 정책 완화처럼 되돌리기 큰 조치는 원인 후보가 좁혀진 뒤에 선택해야 합니다.

• Most Kubernetes incidents only look like pod failures. The real fault often sits in config drift or traffic policy.
• A Running pod with failed traffic usually points to readiness, service selection, ingress policy, auth sidecar, or DNS path issues.
• The fastest responders compare one healthy path and one broken path instead of changing manifests first.

재발 방지

장애가 끝난 뒤에는 원인 한 줄보다 “왜 그 상태가 오래 남았는지”를 기록해야 합니다. 배포 파이프라인, 런타임 reload, 권한 상속, 인증서 갱신, 네트워크 정책처럼 자동화와 운영 절차 사이에 빈틈이 있었는지 확인합니다.

Kubernetes Config and Rollouts, Kubernetes Ingress and Traffic, Kubernetes Scheduling and Capacity, Timeouts and Latency, CrashLoop and Restarts 허브와 함께 보면 같은 증상을 다른 환경에서도 다시 점검할 수 있습니다.

관련 InfraTree 문제

아래 문제들은 이 가이드의 내용을 실제 시나리오로 연습하기 위한 공개 문제입니다. 글을 읽은 뒤 한 문제만 풀어도 신호를 먼저 나누고 복구 방향을 문장으로 정리하는 연습을 할 수 있습니다.

• CrashLoopBackOff Pod에서 첫 번째 확인 포인트 정리하기
• Running 상태인데 트래픽을 받지 못하는 서비스 장애 분석
• private registry 자격 증명이 빠져 ImagePullBackOff가 나는 문제
• Namespace가 없어 배포가 실패하는 선언형 매니페스트 문제
• ConfigMap 키 이름이 달라 설정 파일이 비어 보이는 문제
• HPA가 붙어 있는데도 스케일이 오르지 않는 metrics 파이프라인 문제