Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Kubernetes readiness probe failed: 먼저 볼 것들

readiness probe 가 계속 실패하면 pod 는 살아 있어도 Kubernetes 는 그 pod 로 트래픽을 보내지 않습니다. 이때 문제는 “pod 가 죽었다” 보다는 probe 가 실제 startup timing, endpoint behavior, dependency 기대와 맞지 않는 경우가 많습니다.

짧게 말하면 핵심은 이것입니다. probe 동작과 실제 앱 동작을 비교해야 합니다. readiness probe 는 프로세스가 떠 있는지만이 아니라, 앱이 안전하게 트래픽을 받을 수 있는 시점을 반영해야 합니다.

probe 동작과 실제 앱 동작을 같이 본다

path, timeout, expected response 가 실제와 맞지 않으면 프로세스는 살아 있어도 pod 는 계속 unready 상태로 남습니다.

즉 아래를 같이 봐야 합니다.

readiness probe 가 실제로 무엇을 호출하는가
앱이 실제로 무엇을 노출하는가
startup 이 실제로 얼마나 걸리는가
readiness 가 외부 dependency 를 너무 일찍 보지 않는가

이 구분이 pod phase 만 보는 것보다 훨씬 유용합니다.

readiness failure 는 보통 무엇을 뜻하나

실전에선 보통 이런 경우가 많습니다.

잘못된 path 또는 port 를 probe 한다
startup 이 probe 가 허용하는 시간보다 길다
readiness check 가 너무 많은 걸 본다
threshold 가 너무 공격적이다
앱은 살아 있지만 아직 traffic-safe 하지 않다

핵심은 “잘못된 probe” 와 “실제 dependency 문제를 드러내는 올바른 probe” 를 구분하는 것입니다.

흔한 원인

1. probe path 또는 port 가 틀리다

앱이 아래 상태일 수 있습니다.

다른 port 에 listen 한다
다른 endpoint 를 노출한다
probe 가 기대하는 status code 와 다른 값을 준다

container 또는 framework 변경 뒤 자주 보입니다.

2. startup 이 probe 가 허용하는 시간보다 오래 걸린다

앱 초기화가 느리면 readiness 는 timing 문제로 실패할 수 있습니다.

3. probe 가 외부 시스템을 너무 일찍 본다

readiness 가 DB, queue, upstream service 를 지나치게 강하게 확인하면, 일시적인 외부 문제만으로도 pod 가 계속 unready 상태가 될 수 있습니다.

4. timeout 과 threshold 가 비현실적이다

짧은 timeout, 짧은 interval, 빡빡한 threshold 는 정상 pod 도 unready 로 만들 수 있습니다.

5. 앱 동작은 바뀌었는데 probe 는 그대로다

서비스는 진화했는데 readiness 계약은 예전 가정에 묶여 있는 경우입니다.

이런 drift 가 readiness incident 를 특히 헷갈리게 만듭니다.

실전 점검 순서

1. readiness probe 가 실제로 무엇을 호출하는지 확인한다

정확한 path, port, method, timing 부터 봐야 합니다.

2. pod 안에서 path 와 port 를 직접 테스트한다

컨테이너 내부 문맥에서 endpoint 가 실제로 probe 가 기대하는 방식으로 동작하는지 알 수 있습니다.

3. startup time 과 probe timing 을 비교한다

앱에 더 많은 warm-up 시간이 필요하다면, probe 모양은 맞아도 timing 이 틀린 것입니다.

4. 필요 이상인 dependency check 를 readiness 에서 줄일 수 있는지 본다

readiness 는 traffic routing 을 보호해야 하지만, 정말 필요하지 않다면 일시적인 upstream 흔들림에 pod 전체를 hostage 로 만들 필요는 없습니다.

5. probe 가 real behavior 와 맞을 때 pod 가 ready 가 되는지 확인한다

이 마지막 단계가 probe 설계 문제였는지, startup timing 문제였는지, 더 깊은 runtime 문제였는지 구분해 줍니다.

빠른 명령

kubectl describe pod <pod> -n <ns>
kubectl logs <pod> -n <ns>
kubectl exec -it <pod> -n <ns> -- sh

probe 가 무엇을 호출하는지, 앱 로그는 뭐라고 하는지, pod 안에서 endpoint 가 실제로 응답하는지를 같이 볼 수 있는 기본 조합입니다.

잘못된 path/port, 느린 startup timing, 외부 시스템에 너무 일찍 의존하는 readiness check 를 먼저 보세요.

mismatch 를 찾은 뒤 무엇을 바꾸면 좋나

path 또는 port 가 틀렸다면

앱이 실제로 노출하는 endpoint 와 probe 를 맞춰야 합니다.

startup 이 너무 느리다면

Kubernetes 가 현실적인 warm-up 을 기다리도록 probe timing 을 조정해야 합니다.

readiness 가 너무 많은 걸 본다면

필요 이상인 dependency coupling 을 줄여 임시 upstream 문제 때문에 불필요하게 트래픽이 막히지 않게 해야 합니다.

threshold 가 너무 엄격하다면

실제 운영 조건에 맞게 interval 과 failure threshold 를 다시 잡아야 합니다.

앱 동작이 drift 했다면

서비스가 traffic-safe 해지는 실제 조건에 맞게 readiness 계약을 업데이트해야 합니다.

장애 중에 던져볼 질문

이 질문이 꽤 유용합니다.

이 pod 가 트래픽을 받아도 안전하다고 판단해야 할 정확한 조건은 무엇이고, 현재 readiness probe 는 그 조건을 정확히 테스트하고 있는가?

이 질문이 probe 설계 문제를 빨리 드러냅니다.

FAQ

Q. readiness 와 liveness 는 같은가

아닙니다. readiness 는 트래픽 수용 여부, liveness 는 restart 필요 여부에 더 가깝습니다.

Q. 가장 빠른 첫 단계는 무엇인가

probe 가 쓰는 정확한 path, port, timing 을 확인하는 것입니다.

Q. pod 가 살아 있으면 ready 여야 하지 않나

그렇지 않습니다. alive 는 프로세스가 존재한다는 뜻이고, ready 는 트래픽을 받아도 안전하다는 뜻입니다.

Q. readiness 가 모든 외부 dependency 를 다 봐야 하나

보통은 아닙니다. 그 dependency 없이는 정말 안전하게 응답할 수 없는 경우에만 강하게 묶는 편이 맞습니다.

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.