Mar 24, 2026

마지막 업데이트 Mar 30, 2026

Kubernetes service has no endpoints 트러블슈팅 가이드

Service 에 endpoints 가 없다는 것은 service 객체는 존재하지만, Kubernetes 가 트래픽을 보낼 healthy backing pod 를 찾지 못했다는 뜻입니다. 대개는 “Service 가 고장났다” 보다 selector, label, readiness, port, namespace scope 가 생각한 대로 맞지 않는 경우입니다.

짧게 말하면 핵심은 이것입니다. selector match 와 pod readiness 를 같이 봐야 합니다. Service 는 selector 와 맞고, ready 상태인 pod 로만 트래픽을 보냅니다.

selector 와 readiness 를 같이 본다

많은 경우 Service 와 pod 를 따로 보지만, 진짜 질문은 Kubernetes 가 이 둘을 실제로 연결할 수 있는가입니다.

즉 아래가 모두 맞아야 합니다.

Service selector
pod label
namespace scope
readiness 상태
targetPort 또는 named-port 매핑

하나라도 틀리면 Service 는 존재해도 usable endpoint 가 0개일 수 있습니다.

”no endpoints” 는 실전에서 보통 무엇을 뜻하나

보통 이런 이유가 많습니다.

selector 가 실제 pod label 과 안 맞는다
pod 는 있지만 unready 상태다
Service 가 잘못된 port 를 본다
namespace 를 잘못 보고 있다
workload 가 아직 healthy 하지 않은데 endpoint 가 생기길 기대한다

좋은 점은, 이 문제는 보통 vague 한 네트워크 미스터리가 아니라 꽤 구체적인 매핑 문제라는 것입니다.

흔한 원인

1. Service selector 와 pod label 이 맞지 않는다

가장 흔한 원인입니다.

아주 작은 mismatch 도 충분합니다.

app
component
version label
환경별 label

이 중 하나만 틀려도 Service 는 endpoint 를 못 채웁니다.

2. matching pod 가 ready 가 아니다

pod 는 있고 selector 도 맞지만 readiness 에 실패할 수 있습니다.

그 경우 Kubernetes 는 안전하게 트래픽을 받을 수 있을 때까지 endpoint 에 넣지 않습니다.

3. port mapping 이 잘못되었다

Service 가 아래를 가리킬 수 있습니다.

잘못된 targetPort
pod 가 노출하지 않는 named port
기대와 다르게 해석되는 port name

container port 나 manifest 변경 뒤 자주 보이는 패턴입니다.

4. namespace 또는 scope 가 잘못 가정되었다

label 은 맞는데, Service 와 pod 가 실제로 같은 namespace 문맥에 있지 않을 수 있습니다.

수동 디버깅 중에 놓치기 쉬운 부분입니다.

5. readiness 와 traffic 기대치가 다르다

pod 가 존재하는 순간 바로 endpoint 가 생겨야 한다고 생각하지만, 실제로는 readiness 가 통과돼야만 들어갑니다.

이건 Service bug 가 아니라 endpoint population 의 정상 동작입니다.

실전 점검 순서

1. Service selector 와 namespace 를 확인한다

내가 기억하는 설정이 아니라, 실제 object definition 부터 봐야 합니다.

2. backing pod 의 label 을 비교한다

생각하는 deployment template 이 아니라 현재 살아 있는 pod label 을 봐야 합니다.

이 단계에서 stale rollout 이나 manual mismatch 가 빨리 드러납니다.

3. matching pod 가 ready 인지 확인한다

label 이 맞는데 pod 가 ready 가 아니라면, Service 는 endpoint 를 비워 두는 것이 정상입니다.

4. `targetPort` 와 named-port 매핑을 점검한다

port mismatch 는 Service 가 겉보기엔 정상인데도 연결이 안 되는 전형적인 원인입니다.

5. labels 와 readiness 가 맞으면 endpoint 가 채워지는지 확인한다

이 마지막 단계가 mapping 문제였는지, readiness 문제였는지, 그 밖의 문제였는지 구분해 줍니다.

빠른 명령

kubectl get svc <service> -n <ns> -o yaml
kubectl get endpoints <service> -n <ns>
kubectl get pods -n <ns> --show-labels

deployment 를 바꾸기 전에 service selector, 실제 endpoints, pod label 을 먼저 비교해 보세요.

selector mismatch, unready pod, named port 또는 targetPort 불일치를 먼저 찾는 데 좋습니다.

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

selector 가 틀렸다면

label 또는 selector 를 맞춰서 Service 와 pod 가 같은 workload 를 가리키게 해야 합니다.

pod 가 ready 가 아니라면

Service 를 손보기보다 readiness 쪽 문제를 먼저 봐야 합니다.

port 가 틀렸다면

Service port 와 실제 container port 또는 named port 를 맞춰야 합니다.

namespace 가 잘못되었다면

올바른 scope 에서 workload 를 다시 봐야 합니다.

기대가 잘못되었다면

Kubernetes 는 pod 가 ready 하다고 판단할 때만 endpoint 를 채운다는 점을 기억해야 합니다.

장애 중에 던져볼 질문

이 질문이 꽤 유용합니다.

지금 이 Service 뒤에 있어야 하는 정확한 pod 는 무엇이고, Kubernetes 가 그 pod 를 endpoint 로 추가하지 못하게 막는 구체적인 조건은 무엇인가?

이 질문이 real blocker 를 빨리 드러냅니다.

FAQ

Q. Service 가 있는데 endpoint 가 0개일 수 있나

그렇습니다. ready pod 가 없거나 selector 가 맞지 않으면 가능합니다.

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

Service selector 와 실제 pod label, readiness 를 같이 비교하는 것입니다.

Q. label 만 맞으면 끝인가

그렇지 않습니다. pod 가 unready 이거나 port mapping 이 틀릴 수도 있습니다.

Q. 이건 항상 네트워크 문제인가

아닙니다. 보통은 workload mapping 이나 readiness 문제부터 보는 편이 맞습니다.

먼저 읽어볼 가이드

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