Endpoints none diagnostic runbook

If the Service exists but Endpoints / EndpointSlice is empty (Endpoints none, endpoints: []), traffic never reaches Pods. You usually see timeouts, connection refused, or an unhealthy load balancer.

30-second checklist

1. kubectl get svc,endpoints,endpointslice -n <ns> — confirm empty backends
2. Service selector must exactly match Pod labels
3. At least one Ready Pod (READY 0/1 pods are excluded)
4. Check exceptions: publishNotReadyAddresses, headless, ExternalName
5. Consider NetworkPolicy and kube-proxy / Cilium dataplane

Inspect objects

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>

Empty Endpoints means the dataplane has nothing to program.

Match selector to labels

kubectl get svc <svc> -n <ns> -o jsonpath='{.spec.selector}{"\n"}'
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
kubectl get pods -n <ns> --show-labels

Common mistakes: mixing app vs app.kubernetes.io/name, Helm selector immutability drift, wrong namespace.

Not Ready ⇒ not in Endpoints

kubectl get pods -n <ns> -o wide
kubectl get pod <pod> -n <ns> -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'

targetPort and protocol

Compare Service targetPort (name or number) with container ports. IP present but no ports usually means a name mismatch.

NetworkPolicy and dataplane

• Policies blocking client→Pod or probe paths
• CNI identity lag after label changes
• Debug with netshoot against ClusterIP and Pod IP

Decision table

Prevent recurrence

• Generate Service selector and Pod labels from one Helm values source
• Fail CI when Endpoints stay empty after rollout
• Point readinessProbe at the real traffic port
• Standardize on app.kubernetes.io/* labels

Endpoints none is not a “broken Service object” — it means the selector / Ready / port contract broke. Start with “does this selector return Pods?”