Before you start
Linux Pods using cluster DNS; Bash examples. Discover the actual DNS namespace, Service, cluster domain, and any NodeLocal DNSCache. Documentation-reviewed on 2026-09-07; no live diagnostic queries performed.
Commands are examples, not actions run by this page. Replace the sample names and paths. Run related blocks in the same shell. Read the explanations before copying. Logs and configuration can contain private data; keep credentials and unredacted evidence out of public posts.
Validation: documentation-reviewed guidance, not a tested live-cluster repair.
Replace all placeholders. The client and Service can be in different namespaces. These initial cards only read Kubernetes state. Executing a resolver inside a Pod starts a process and makes network requests, so the optional comparison later requires the workload owner's approval.
1. Confirm the intended Service and client
Record the exact name the application requested, the client Pod, namespace, error, and time. A short Service name searches the client's namespace; use the correct Service namespace and configured cluster domain when comparing names. Do not assume every cluster uses cluster.local.
HELP_CLIENT_NS='REPLACE_CLIENT_NAMESPACE'
HELP_CLIENT_POD='REPLACE_CLIENT_POD'
HELP_SERVICE_NS='REPLACE_SERVICE_NAMESPACE'
HELP_SERVICE='REPLACE_SERVICE_NAME'
kubectl config current-context
kubectl -n "$HELP_CLIENT_NS" get pod "$HELP_CLIENT_POD" -o jsonpath='{.spec.dnsPolicy}{"\n"}{.spec.dnsConfig}{"\n"}{.spec.hostNetwork}{"\n"}{.spec.nodeName}{"\n"}'
kubectl -n "$HELP_SERVICE_NS" get service "$HELP_SERVICE" -o yaml
kubectl -n "$HELP_SERVICE_NS" get endpointslice -l "kubernetes.io/service-name=$HELP_SERVICE" -o yamlCheck Service type, selector, ports, addresses, and endpoint readiness. A headless Service has different DNS behavior from an ordinary ClusterIP Service.
2. Inspect the resolver path before altering it
Discover the installed DNS components from the platform inventory. CoreDNS commonly sits behind a Service named kube-dns, but these examples intentionally require the actual names. Some clusters route clients through NodeLocal DNSCache. A missing expected label does not prove DNS is absent.
HELP_DNS_NS='REPLACE_DNS_NAMESPACE'
HELP_DNS_SERVICE='REPLACE_DNS_SERVICE'
HELP_DNS_POD='REPLACE_DNS_POD'
HELP_DNS_CONTAINER='REPLACE_DNS_CONTAINER'
kubectl -n "$HELP_DNS_NS" get service "$HELP_DNS_SERVICE"
kubectl -n "$HELP_DNS_NS" get endpointslice -l "kubernetes.io/service-name=$HELP_DNS_SERVICE" -o wide
kubectl -n "$HELP_DNS_NS" describe pod "$HELP_DNS_POD"
kubectl -n "$HELP_DNS_NS" logs "$HELP_DNS_POD" -c "$HELP_DNS_CONTAINER" --since=10m --tail=100
kubectl -n "$HELP_CLIENT_NS" get networkpolicyLook for availability, recent restart, forwarding, or authorization evidence. Listing NetworkPolicies does not by itself prove which CNI policies allow a packet.
| What you observe | What it suggests | Next step |
|---|---|---|
| One short name fails, but its correctly qualified name resolves. | Namespace or resolver search behavior is a likely cause. | Correct the application endpoint or approved DNS configuration. Preserve the intended Service namespace rather than changing the cluster-wide resolver. |
| The name resolves, but connections fail and ready endpoints are absent. | The incident is likely backend readiness or Service selection, not record lookup. | Investigate selectors, endpoint readiness, target port, application listening behavior, and connectivity. Keep DNS unchanged unless independent evidence implicates it. |
| Many clients receive timeouts or SERVFAIL, with matching DNS Pod errors. | A shared resolver, forwarding path, network restriction, or DNS authorization issue needs investigation. | Escalate the correlated evidence to the DNS/platform owner. Correct only the proven configuration or permission defect; do not grant cluster-admin or replace upstream servers speculatively. |
3. Compare from the affected network context
If approved and the existing client image contains nslookup, compare a fully qualified Service name from that same container. Do not install tools into the production container. If the tool is absent, request an approved diagnostic workflow instead of creating a privileged Pod.
HELP_CLIENT_CONTAINER='REPLACE_CLIENT_CONTAINER'
HELP_CLUSTER_DOMAIN='REPLACE_VERIFIED_CLUSTER_DOMAIN'
HELP_FQDN="${HELP_SERVICE}.${HELP_SERVICE_NS}.svc.${HELP_CLUSTER_DOMAIN}."
kubectl -n "$HELP_CLIENT_NS" exec "$HELP_CLIENT_POD" -c "$HELP_CLIENT_CONTAINER" -- nslookup "$HELP_FQDN"This is an active diagnostic, not an API read: it creates a process and sends DNS traffic. It changes no DNS configuration. Use only with authorization and verified existing tooling.
4. Limit the repair's blast radius
A namespaced endpoint correction has a different impact from editing the shared CoreDNS configuration. For an approved shared change, retain the previous reviewed configuration, validate syntax through the platform workflow, and define a rollback owner. Query logging can expose names and add load; enabling it is a temporary configuration change, not an initial inspection step.
Verify the fix
- Repeat the approved comparison from affected clients and relevant namespaces; record response, time, and resolved address.
- Verify ordinary application connectivity separately from DNS. For headless discovery, check the intended readiness behavior and returned backend set.
- Confirm unrelated internal and external resolution still works. Revert an unsuccessful DNS configuration change through its owner instead of layering speculative fixes.
Record the evidence, approved change, result, and rollback plan so the next administrator can follow your reasoning.
Avoid these shortcuts
- Do not replace cluster DNS with a public resolver; it cannot provide the cluster's private Service records.
- Do not open all egress or disable NetworkPolicies as a generic DNS fix.
- Do not assume a successful laptop lookup validates the Pod's resolver path.
Primary sources and version checks
Check the documentation for your installed release. Provider, runtime, CNI, storage-driver, and distribution details can differ.