service-debug

Service Connectivity Diagnosis

When a Service is unreachable, returns connection refused, or has no backends, follow this flow to identify the root cause.

Scope: This skill is for diagnosis only. Once you identify the root cause, report it to the user and stop. Do NOT attempt to modify the Service, Endpoints, or pod specs — that should be left to the user.

Diagnostic Flow

1. Check the Service

kubectl get svc <service> -n <ns> -o wide

Confirm the Service exists and note:

• TYPE — ClusterIP, NodePort, LoadBalancer, or ExternalName
• CLUSTER-IP — should not be None unless it is a headless service
• PORT(S) — the port(s) the Service exposes
• SELECTOR — the label selector used to find backend pods

2. Check Endpoints

kubectl get endpoints <service> -n <ns>

• If ENDPOINTS column shows <none> or is empty, no pods match the Service's selector — go to step 3.
• If endpoints exist, note the IPs and ports — go to step 4.

For more detail (including notReadyAddresses):

kubectl describe endpoints <service> -n <ns>

3. Investigate selector and pods

The Service's selector must match labels on running, ready pods.

Get the Service selector:

kubectl get svc <service> -n <ns> -o jsonpath='{.spec.selector}'

List pods that match the selector:

kubectl get pods -n <ns> -l <key>=<value> -o wide

(Replace <key>=<value> with each selector pair from the previous command.)

If no pods match:

• The selector may be wrong (typo, outdated label)
• The pods may be in a different namespace
• The pods may not exist yet

If pods exist but none are Ready:

• Pods may be starting, crashing, or failing readiness probes
• Use pod-crash-debug or check readiness probes

4. Check port configuration

Verify that the Service port, targetPort, and the container's actual listening port all align.

kubectl get svc <service> -n <ns> -o jsonpath='{range .spec.ports[*]}port={.port} targetPort={.targetPort} protocol={.protocol}{"\n"}{end}'