Kubernetes service endpoint troubleshooting cheat sheet
Trace a Service through selectors, pod readiness, EndpointSlices and service ports.
Kubernetes with EndpointSlice support and kubectl read access to the target namespace.
Updated · Kubernetes · 6 min read
| Command | What it does |
|---|---|
kubectl config current-context | Confirm the cluster context |
kubectl get service web -n production -o wide | Inspect Service addresses and ports |
kubectl describe service web -n production | Inspect Service selector and endpoint summary |
kubectl get pods -n production -l app=web -o wide --show-labels | Inspect selected pods and readiness |
kubectl get endpointslice -n production -l kubernetes.io/service-name=web -o yaml | Inspect EndpointSlice addresses and conditions |
Walkthrough
Replace production, web, app=web and the pod name. Confirm the context and use an authorized account; these commands inspect resources without changing them.
Step 1: Confirm the cluster context
kubectl config current-context
Compare the selected context with the approved cluster inventory. Context names can be arbitrary local labels, so verify the endpoint through your organization’s inventory before interpreting production results.
Step 2: Inspect Service addresses and ports
kubectl get service web -n production -o wide
Record the ClusterIP, service ports and selector for the affected Service. A ClusterIP being assigned does not prove that any backend is ready or that the application is listening on its target port.
Step 3: Inspect Service selector and endpoint summary
kubectl describe service web -n production
Compare the selector, port and targetPort with the deployed application. A named target port must match the pod’s declared container port name; the summary is a starting point, not a substitute for inspecting EndpointSlices.
Step 4: Inspect selected pods and readiness
kubectl get pods -n production -l app=web -o wide --show-labels
Use the selector actually shown by the Service rather than assuming app=web. Check labels, readiness and node placement; a Running pod can still be unready or expose the wrong application port.
Step 5: Inspect EndpointSlice addresses and conditions
kubectl get endpointslice -n production -l kubernetes.io/service-name=web -o yaml
Compare endpoint addresses, ports and readiness conditions with the intended pods. A missing or unready endpoint narrows the investigation to selection or readiness; avoid sharing full resource output if it contains internal addresses.
WORKED INCIDENT
Practical case: A Service has no ready backends
Fictional teaching scenario; observations are examples, not captured production output.
Situation
Clients receive errors from a ClusterIP even though the web pods are running.
Investigation sequence
1. Confirm the cluster context
kubectl config current-contextVerify the cluster context and production namespace before inspecting resources.
2. Inspect Service selector and endpoint summary
kubectl describe service web -n productionRead the Service selector and target port from the actual Service definition.
3. Inspect selected pods and readiness
kubectl get pods -n production -l app=web -o wide --show-labelsCompare selected pod labels and readiness against the selector.
4. Inspect EndpointSlice addresses and conditions
kubectl get endpointslice -n production -l kubernetes.io/service-name=web -o yamlInspect EndpointSlices for ready addresses corresponding to those pods.
Example findings
Illustrative findings: the Service selects app=web, but the deployed pods have app=frontend and the EndpointSlice has no ready backends.
Interpret the findings
A selector mismatch explains the empty backend list in this example. An empty list can also reflect pod readiness or other Service configuration, so inspect those separately.
Verify the outcome
After the workload owner corrects the selector or pod labels through the approved deployment, confirm ready EndpointSlices and test the Service from an authorized client.
Escalation handoff
Send the namespace, Service selector, pod labels, endpoint conditions and timestamps to the application platform owner.