Kubernetes deployment failure triage

Kubernetes Deployment가 올라오지 않을 때는 kubectl apply 또는 Deployment 객체만 보지 말고, 먼저 대상 namespace의 실제 Pod 상태와 event를 확인해야 한다. 대부분의 원인은 image pull, scheduling, probe/readiness, crash loop, 잘못된 selector 또는 rollout 정체처럼 Pod 레벨 신호에 나타난다.

Summary#

Kubernetes Deployment가 올라오지 않을 때는 kubectl apply 또는 Deployment 객체만 보지 말고, 먼저 대상 namespace의 실제 Pod 상태와 event를 확인해야 한다. 대부분의 원인은 image pull, scheduling, probe/readiness, crash loop, 잘못된 selector 또는 rollout 정체처럼 Pod 레벨 신호에 나타난다.

Problem#

Deployment 명령은 성공했거나 Deployment 객체만 보면 원인이 불명확하지만, 실제 워크로드가 Ready 상태가 되지 않는다.

Triage Procedure#

namespace를 명시해 Pod 목록을 확인한다. - kubectl get pods -n <namespace> - 필요하면 kubectl get deploy -n <namespace>와 함께 desired/current/ready 수를 비교한다.
Pod 상태 전이를 관찰한다. - kubectl get pods -n <namespace> -w - Pending, ImagePullBackOff, ErrImagePull, CrashLoopBackOff, RunContainerError, ContainerCreating, Running but 0/1 Ready 같은 상태를 먼저 분류한다.
문제 Pod를 describe 해서 events를 읽는다. - kubectl describe pod <pod-name> -n <namespace> - scheduling 실패, image pull 실패, volume mount 실패, probe 실패, OOMKilled, restart count, container reason/message를 확인한다.
Deployment describe로 rollout 조건을 확인한다. - kubectl describe deployment <deployment-name> -n <namespace> - replica 수, selector, rollout condition, unavailable/available 상태, ReplicaSet 연결을 확인한다.
CrashLoop 또는 probe 문제면 logs와 probe 설정을 분리해 본다. - kubectl logs <pod-name> -n <namespace> - 이전 컨테이너 로그가 필요하면 kubectl logs <pod-name> -n <namespace> --previous - readiness 실패는 트래픽 제외 신호이고, liveness 실패는 재시작 신호이므로 같은 “health check 실패”로 뭉뚱그리지 않는다.
수정 전 원인을 한 가지로 좁힌다. - 이미지 태그/registry 인증 문제인지 - node resource 부족 또는 taint/toleration/nodeSelector 문제인지 - config/secret/volume mount 문제인지 - app crash 또는 잘못된 command/args 문제인지 - readiness/liveness/startup probe 문제인지 - Deployment selector/label 불일치 또는 rollout 전략 문제인지 확인한 뒤 manifest를 수정한다.

Failure Modes#

Deployment 객체만 보고 Pod-level event를 읽지 않으면 image pull, scheduling, mount, probe 실패를 놓친다.
namespace를 생략하면 다른 namespace를 보고 “리소스가 없다”는 잘못된 결론을 낼 수 있다.
restart count 자체를 원인으로 오해하고 describe pod의 reason/message/events 또는 logs --previous를 확인하지 않으면 진단이 늦어진다.
readiness 실패와 liveness 실패를 혼동하면 트래픽 제외 문제와 재시작 루프 문제를 잘못 처리할 수 있다.
무작정 manifest를 바꾸면 원인 신호가 사라져 재현과 검증이 어려워진다.

Kubernetes Probe Failure Modes: startupProbe, readiness/liveness semantics, slow-boot shielding, and sidecar/termination edge cases — probe 실패와 rollout 정체를 해석할 때 연결된다.
Compose vs Kubernetes production boundary — Kubernetes를 선택하는 운영 경계와 배포/스케줄링 요구를 이해하는 배경 지식으로 연결된다.

Sources#

Kubernetes documentation: kubectl describe and resource inspection concepts
Kubernetes documentation: Pods, Deployments, Events, Probes, and debugging workloads
Stack Overflow: kubernetes-deployment-failure-how-to-inspect
Stack Overflow: kubernetes-deployment-failing-due-to-image-pull-failure

Maintenance Note#

이전 Sources에는 FastAPI/JWT, React state update, PostgreSQL query optimization, Docker Compose image refresh 등 Kubernetes deployment failure triage와 직접 관련 없는 링크가 섞여 있었다. 본문 절차는 유지하되 출처 목록은 Kubernetes workload debugging과 직접 관련된 항목으로 축소한다.

Sagwan Revalidation 2026-07-08T07:25:53Z#

verdict: ok
note: Pod/events 중심 triage와 명령들이 현재 Kubernetes practice와 부합합니다.

Sagwan Revalidation 2026-07-10T07:14:20Z#

verdict: ok
note: Pod/events 중심의 배포 실패 진단 절차는 현재도 표준 practice와 부합함

Sagwan Revalidation 2026-07-12T01:07:10Z#

verdict: ok
note: Pod 상태·event 중심 triage 절차는 현재 Kubernetes practice와도 부합함

Sagwan Revalidation 2026-07-13T20:37:33Z#

verdict: ok
note: Kubernetes 배포 장애 기본 triage 절차로 여전히 유효하다.

Sagwan Revalidation 2026-07-15T20:08:16Z#

verdict: ok
note: Pod/events 중심 triage와 명령들이 현재 Kubernetes practice와 부합함

Sagwan Revalidation 2026-07-17T20:45:47Z#

verdict: ok
note: Pod/events 중심 triage 절차와 명령이 현재 practice와도 부합함

Sagwan Revalidation 2026-07-19T21:42:10Z#

verdict: ok
note: 현재 Kubernetes 배포 실패 진단 절차로 여전히 정확하고 재사용 가능함

Sagwan Revalidation 2026-07-21T23:22:42Z#

verdict: ok
note: Pod 상태·event 중심 triage와 명령/개념이 현재 practice와 부합함

Sagwan Revalidation 2026-07-24T01:09:24Z#

verdict: ok
note: Pod/events 중심 triage와 logs/describe 절차는 현재도 표준적이다.

Sagwan Revalidation 2026-07-26T03:36:27Z#

verdict: ok
note: Pod/event 중심 triage와 명령들이 현재 Kubernetes practice와 여전히 부합함

Sagwan Revalidation 2026-07-28T10:42:52Z#

verdict: ok
note: Pod/events 중심 triage 절차는 현재 Kubernetes practice와도 부합함

Sagwan Revalidation 2026-07-30T15:35:01Z#

verdict: ok
note: 표준 kubectl 기반 배포 장애 triage 절차로 현재도 유효하다.

Sagwan Revalidation 2026-08-02T01:17:58Z#

verdict: ok
note: Pod 상태·events·describe·logs 중심의 배포 실패 triage는 현재도 표준적이다.

Sagwan Revalidation 2026-08-06T02:02:29Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-08T11:21:35Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-10T23:40:50Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-13T11:24:21Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-16T00:06:13Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-18T12:14:54Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-21T00:48:47Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-23T13:26:35Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-26T01:44:33Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-28T13:53:14Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-08-31T02:03:48Z#

verdict: ok
note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-09-02T16:49:29Z#

verdict: ok
note: Pod/events 중심의 Deployment 장애 triage 절차는 현재도 유효함

Sagwan Revalidation 2026-09-08T19:56:15Z#

verdict: ok
note: [chatgpt HTTP 404] {

Sagwan Revalidation 2026-09-11T09:51:23Z#

verdict: ok
note: kubectl 명령어·Pod 상태명(ImagePullBackOff 등)·triage 절차 모두 현행 Kubernetes(1.32)에서 그대로 유효하다.

Sagwan Revalidation 2026-09-14T05:18:35Z#

verdict: ok
note: kubectl 명령, Pod 상태명, readiness/liveness 구분 모두 현행 Kubernetes 관행과 일치하며 변경 불필요.