Last reviewed: November 10, 2026 (Asia/Shanghai); primary references checked November 9 UTC.
Direct answer
A Kubernetes Service review should trace the rendered Service selector to the intended Pods, resolve each Service port to the application’s actual listener, and inspect every associated EndpointSlice. Then verify a harmless request from the intended client through the Service’s DNS name and port. A valid manifest, a ready Deployment, or one successful response cannot establish that the Service reaches the complete intended backend set.
Pay particular attention when a coding agent renames labels or ports. The Kubernetes Service reference
permits a named targetPort to resolve to different numeric ports on different Pods. The EndpointSlice reference
explains that those different target ports require different slices. Reading only the first slice can therefore hide a broken application version or make a valid port migration look incomplete.
Who this is for
Use this workflow when a coding agent edits a selector-based, non-headless ClusterIP Service, its backing workload labels or named ports, or the Helm values and Kustomize overlays that render them. It is intended for maintainers reviewing ordinary internal application traffic.
Give the agent the expected callers, backend membership, protocol, client-facing port, application listener, and affected environments. Ask for rendered before-and-after manifests and proposed acceptance checks. Execute fixture changes through the team’s approved disposable-cluster workflow. The examples below are review recommendations; no cluster tests or deployments were performed for this article.
Key takeaways
- Match Service selectors against rendered Pod labels, including labels on unrelated workloads.
- Keep the Service’s
port, its portname, and the Pod’s namedtargetPortrelationship explicit. - Read all associated EndpointSlices and retain each slice’s ports with its endpoint identities.
- Check endpoint conditions; presence in a slice does not establish readiness.
- Test DNS, the Service address, and permitted direct backend access separately when diagnosing failures.
- Require membership evidence and controlled failure cases alongside successful requests.
Sources checked
Three primary Kubernetes references were retrieved successfully on November 9, 2026 UTC:
- Service defines selectors, numeric and named target ports, Service types, selectorless and headless behavior, and namespace-qualified discovery.
- EndpointSlices defines association labels, management and ownership, per-slice ports, endpoint conditions, and the need to aggregate all slices while accounting for duplicate endpoints.
- Debug Services separates DNS, Service-IP, selector, port, and direct-Pod checks when diagnosing connectivity.
These maintained references support an evergreen review task. Their displayed modification dates are July 7, 2026; June 22, 2025; and June 9, 2026, respectively. Match the references to the target Kubernetes version and Service implementation. This guide uses established Service and discovery.k8s.io/v1 EndpointSlice fields rather than optional new routing features.
Contract details to verify
Write the client-to-backend contract
Start with a concrete requirement: clients in the test environment call review-api.agent-review on TCP 80; the Service routes to HTTP API Pods carrying both approved labels; worker Pods are excluded. The old API version listens on 8080, while a candidate version will listen on 9090. Both versions declare their listener with the port name http.
| Contract item | Evidence to attach to the patch |
|---|---|
| Candidate | Source revision, rendering command, chart values or overlay, and final manifests |
| Client route | Caller namespace, Service name, protocol, port, and expected application response |
| Membership | Service selector, matching Pod labels, expected Pod UIDs, and excluded workloads |
| Backend port | Named or numeric target, each version’s declared port, and actual application listener |
| Runtime state | Service UID, all associated slices, their ports, endpoint identities, and conditions |
| Acceptance | Healthy baseline, deliberate failure cases, restoration, and bounded observations |
Render every affected environment. A chart value can broaden a selector in one namespace while leaving another unchanged. Also inspect workload-label changes outside the Service file. A Service selector must identify the intended backend role, rather than merely happen to match a healthy Pod today.
For the separate question of whether the selected Pods can accept traffic, use the health-probe review guide . If communication policy also changes, use the NetworkPolicy review guide to check that additional contract.
Resolve selection and ports before testing traffic
This Service expresses the example’s routing requirement:
apiVersion: v1
kind: Service
metadata:
name: review-api
namespace: agent-review
spec:
type: ClusterIP
selector:
app.kubernetes.io/name: review-api
app.kubernetes.io/component: http
ports:
- name: client-http
protocol: TCP
port: 80
targetPort: http
Compare it with these fields inside the existing Deployment’s spec.template. This is a partial excerpt for inspection; it omits the reviewed image and application configuration and cannot be deployed by itself:
metadata:
labels:
app.kubernetes.io/name: review-api
app.kubernetes.io/component: http
spec:
containers:
- name: api
ports:
- name: http
protocol: TCP
containerPort: 8080
Clients use Service port 80. The Service port’s name is client-http; its targetPort: http refers to the Pod port name http. Those two names have different jobs and need not be identical. Confirm that the application actually listens on the declared backend port; an accurate-looking declaration cannot establish that the process opened a socket.
For the candidate listening on 9090, keep the Pod port name http and update its numeric declaration together with the application listener. The Service reference
explicitly supports this mixture of numeric listeners behind one named target. A change to a hard-coded numeric targetPort: 8080 would remove that flexibility and needs a compatible transition plan.
Preserve field types through templating. Use an integer for a numeric target and a valid port name for a named target; do not let a template silently quote a number. The debugging guide specifically calls out numeric-versus-string targets, matching Pod port names, and protocol checks.
List matching Pods in the Service’s namespace and compare the expected set with other workloads. A synthetic worker carrying app.kubernetes.io/name: review-api but component worker is a useful decoy: removing the component condition must be detected even if ordinary requests still succeed.
Inspect every slice with its port mapping intact
After the approved fixture deployment, collect the actual Service and associated EndpointSlices. These commands require kubectl, jq, and access to the explicitly named test context and namespace:
kubectl --context review-cluster --namespace agent-review \
get service review-api -o json |
jq '{uid: .metadata.uid, resourceVersion: .metadata.resourceVersion,
type: .spec.type, clusterIP: .spec.clusterIP,
selector: .spec.selector, ports: .spec.ports,
publishNotReadyAddresses: .spec.publishNotReadyAddresses}'
kubectl --context review-cluster --namespace agent-review \
get pods -l 'app.kubernetes.io/name=review-api' -o json |
jq '[.items[] | {
pod: .metadata.name, uid: .metadata.uid,
labels: .metadata.labels, podIPs: .status.podIPs,
ports: [.spec.containers[] | {container: .name, ports: .ports}],
ready: [.status.conditions[]? | select(.type == "Ready")]
}]'
kubectl --context review-cluster --namespace agent-review \
get endpointslices -l kubernetes.io/service-name=review-api -o json |
jq '[.items[] | {
slice: .metadata.name, resourceVersion: .metadata.resourceVersion,
owners: .metadata.ownerReferences,
manager: .metadata.labels["endpointslice.kubernetes.io/managed-by"],
addressType, ports,
endpoints: [.endpoints[]? | {addresses, targetRef, conditions}]
}]'
Check the Service-name label, managing controller, and owner reference against the Service UID. Investigate unexpected managers or backends instead of assuming that a familiar label proves ordinary controller ownership.
The EndpointSlice reference
states that a slice’s ports apply to every endpoint in that slice. Keep that relationship when preparing evidence. In the mixed-version fixture, associate the old Pods with 8080 and the new Pods with 9090; do not flatten all addresses and assume a single backend port.
Read every associated slice, across the relevant address families. When calculating unique backend counts, account for duplicate endpoints that can appear across slices during updates. Preserve address, protocol, port, and Pod identity so deduplication cannot merge distinct listeners. Separate API reads are not an atomic snapshot: timestamp them and repeat bounded observations after convergence when membership is changing.
Inspect conditions alongside identity. EndpointSlice ready is normally a shortcut for serving and not terminating, but the reference documents that it is always true for Services using publishNotReadyAddresses: true. Resolve that exception before relying on readiness-based eligibility. The test below assumes an ordinary Service without that setting and uses steady, non-terminating Pods.
Exercise the client path and controlled regressions
Use a synthetic HTTP fixture whose harmless /identity response identifies its Pod and version. Establish healthy old and new backends before testing the mixed-port Service. From an approved client Pod, collect DNS and HTTP results separately. For example, if the fixture client named review-client contains nslookup and curl:
kubectl --context review-cluster --namespace agent-review \
exec review-client -- nslookup review-api.agent-review
kubectl --context review-cluster --namespace agent-review \
exec review-client -- curl --fail --silent --show-error \
--connect-timeout 2 --max-time 5 \
http://review-api.agent-review:80/identity
Use the actual client namespace and DNS configuration. The debugging guide recommends a namespace-qualified name when the client and Service are in different namespaces and warns that the cluster DNS suffix can vary.
Require the expected response content as well as HTTP success. Repeat fresh requests within an agreed deadline, but do not require equal distribution or assume a small sample must visit every Pod. Validate complete membership from the slices, and test each expected listener directly where the fixture’s network policy permits it. Direct requests are diagnostic controls; they do not replace the Service-path check.
Run these proposed cases one at a time, retaining a healthy baseline and restoring it between mutations:
| Controlled case | Required review evidence |
|---|---|
Old 8080 and new 9090 Pods both declare http | All expected backend UIDs have the correct slice-port association; the Service answers through TCP 80 |
| A selector typo matches no API Pods | Membership comparison detects the missing set; a DNS result alone cannot pass the test |
| Component selector is removed and the decoy worker matches | Membership comparison rejects the unintended worker, even if an API response still succeeds |
Only the candidate Pod’s named port changes from http | Contract check detects the unresolved target for that version; healthy old responses cannot hide the defect |
| Candidate declares the correct port but its process does not listen there | Backend request fails within the diagnostic deadline; declared configuration alone cannot pass |
| Correct Service name is queried from a different namespace | Namespace-qualified lookup and the subsequent HTTP request are recorded separately |
If DNS succeeds but HTTP fails, compare a request to the captured Service cluster IP on port 80 with permitted direct requests to each captured Pod address and its backend port. The debugging reference uses these layers to narrow the failure. Direct backends working while the Service route fails points the investigation toward Service mapping or its implementation; it does not prove one specific cause. Retain network-policy and client diagnostics before changing the patch.
Keep exposure changes visible
Read the whole rendered Service, including annotations and type. The Service reference
distinguishes ClusterIP, NodePort, LoadBalancer, and ExternalName. A switch to headless discovery, removal of the selector, or a new external exposure changes this article’s assumptions and requires a corresponding review plan.
Also inspect related Ingress or Gateway changes: a ClusterIP Service can sit behind an external entry point. Keep the audience and routing decision explicit rather than inferring privacy from the Service type alone.
Failure modes
Only Deployment labels are reviewed. Compare the Service selector with labels under the rendered Pod template and actual Pod labels. A controller’s own metadata is insufficient membership evidence.
One slice is treated as the whole Service. Read all matching slices and preserve their port mappings. Named target ports can legitimately produce different numeric backend ports.
One successful response approves every backend. Check the complete expected UID set, excluded workers, endpoint conditions, and each listener. An old healthy Pod can conceal a broken candidate.
A DNS answer is treated as application health. Record the lookup and the actual request separately. Neither a Service record nor an endpoint declaration proves that the process is listening.
FAQ
Must the Service port name equal the Pod port name?
No. In the example, client-http names the Service port while targetPort: http selects the Pod port named http. Review the reference made by targetPort.
Can two application versions use different backend ports?
Yes. Kubernetes supports different numeric ports behind the same named target. Declare the name consistently, verify each actual listener, and inspect every resulting slice-port association.
Does every endpoint in a slice receive ordinary Service traffic?
No. Inspect conditions and relevant Service settings. Endpoint presence alone does not establish readiness, and publishNotReadyAddresses changes the meaning of the ready condition.
Reader next step
Choose one agent-written Service patch. Attach the rendered selector, a client-to-listener port table, expected backend UIDs, and all associated EndpointSlices. In the approved disposable environment, verify the mixed-version healthy path, an unintended matching worker, and a broken candidate listener. Approve the routing change only when membership evidence and client-path observations support the same contract.