Endpoints none 진단 런북

Service는 살아 있는데 Endpoints/EndpointSlice가 비어 있으면(Endpoints none, endpoints: []) 트래픽이 Pod로 전달되지 않습니다. 증상은 타임아웃·connection refused·로드밸런서 unhealthy로 나타납니다.

30초 체크리스트

1. kubectl get svc,endpoints,endpointslice -n <ns> — Service 대비 Endpoints 비었는지
2. Service selector와 Pod labels가 완전히 일치하는지
3. Ready Pod가 있는지 (kubectl get pods READY 0/1이면 Endpoints에 안 실음)
4. publishNotReadyAddresses / headless / ExternalName 예외인지
5. NetworkPolicy·kube-proxy·Cilium/kube-proxy-free 환경 여부

Events·오브젝트 확인

kubectl get svc <svc> -n <ns> -o yaml
kubectl get endpoints <svc> -n <ns> -o yaml
kubectl get endpointslice -n <ns> -l kubernetes.io/service-name=<svc> -o yaml
kubectl describe svc <svc> -n <ns>

Endpoints가 비어 있으면 kube-proxy/ dataplane이 백엔드를 프로그램할 대상이 없습니다.

selector ↔ label 대조

# Service selector
kubectl get svc <svc> -n <ns> -o jsonpath='{.spec.selector}{"\n"}'

# 그 selector로 Pod가 실제로 잡히는지
SEL=$(kubectl get svc <svc> -n <ns> -o jsonpath='{range $k,$v := .spec.selector}{$k}={$v},{end}' | sed 's/,$//')
kubectl get pods -n <ns> -l "$SEL" -o wide

# Pod 라벨 덤프
kubectl get pods -n <ns> --show-labels

흔한 실수:

• app: api vs app.kubernetes.io/name: api 혼용
• Helm 차트에서 selector를 immutable하게 바꾼 뒤 업그레이드 실패/불일치
• 잘못된 네임스페이스의

Ready가 아니면 Endpoints에 안 붙음

kubectl get pods -n <ns> -o wide
kubectl describe pod <pod> -n <ns> | sed -n '/Conditions:/,/Containers:/p'
kubectl get pod <pod> -n <ns> -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'

# 디버그 중에만 — NotReady도 노출 (주의)
spec:
  publishNotReadyAddresses: true

targetPort·프로토콜

kubectl get svc <svc> -n <ns> -o jsonpath='{range .spec.ports[*]}{.name}{"\t"}{.port}{"→"}{.targetPort}{"\t"}{.protocol}{"\n"}{end}'
kubectl get pod <pod> -n <ns> -o jsonpath='{range .spec.containers[*].ports[*]}{.containerPort}{"\t"}{.protocol}{"\n"}{end}'

Endpoints에 IP는 있는데 포트가 비면 targetPort 이름이 컨테이너 포트 name과 안 맞는 경우입니다.

NetworkPolicy·dataplane

• Ingress/Egress policy가 kube-apiserver→Pod 또는 클라이언트→Pod를 막는지
• Cilium/Calico identity 기반 정책에서 label 변경 후 미반영
• kubectl run netshot --rm -it --image=nicolaka/netshoot -- /bin/bash로 Service ClusterIP·Pod IP 직접 curl

빠른 판정표

재발 방지

• Service selector와 Deployment template labels를 한 소스(Helm values)에서 생성
• CI에서 kubectl get endpoints가 비면 배포 실패 처리
• readinessProbe를 실제 트래픽 포트에 맞추기
• 라벨 스키마를 app.kubernetes.io/*로 통일

Endpoints none은 “Service 고장”이 아니라 셀렉터·Ready·포트 계약이 깨졌다는 신호입니다. selector로 Pod가 잡히는지부터 확인하면 대부분 갈래가 정해집니다.