Introduction

In Kubernetes, you normally resolve a Service by DNS rather than by chasing Pod IP addresses. The cluster DNS server creates records for Services automatically, so applications can call a stable hostname even when the backing Pods are recreated.

The Basic Service Hostname

For a Service named api in the namespace default, a Pod in the same namespace can usually reach it with:

api

A Pod in a different namespace should use at least:

api.default

The fully qualified in-cluster DNS name is typically:

api.default.svc.cluster.local

The cluster.local suffix is the common default, but clusters can use a different cluster domain. The important structure is:

• service name
• namespace
• 'svc'
• cluster domain

Example Service and Lookup

Here is a minimal Service:

1apiVersion: v1
2kind: Service
3metadata:
4  name: api
5  namespace: demo
6spec:
7  selector:
8    app: api
9  ports:
10    - name: http
11      port: 80
12      targetPort: 8080

From a Pod in the same namespace, you can test DNS resolution:

kubectl exec -n demo deploy/client -- getent hosts api
kubectl exec -n demo deploy/client -- nslookup api

From another namespace:

kubectl exec -n tools deploy/client -- nslookup api.demo
kubectl exec -n tools deploy/client -- curl http://api.demo

If cluster search paths are configured in the usual way, the short name works only inside the same namespace. Outside that namespace, include the namespace explicitly.

What the DNS Record Resolves To

For a normal Service, the DNS name resolves to the Service cluster IP. Traffic then gets load-balanced to healthy backend Pods.

For a headless Service, the DNS behavior is different. Instead of one cluster IP, DNS returns the IP addresses of the backing Pods directly. That is useful for systems that need peer discovery, such as stateful databases.

1apiVersion: v1
2kind: Service
3metadata:
4  name: db
5  namespace: demo
6spec:
7  clusterIP: None
8  selector:
9    app: db
10  ports:
11    - name: tcp
12      port: 5432

Clients can still resolve db.demo.svc.cluster.local, but they will receive Pod endpoints instead of one virtual IP.

Why Service DNS Is Better Than Pod IPs

Pods are disposable. A restart, reschedule, or rollout can change the Pod IP. Service DNS gives your code a stable name and lets Kubernetes manage the moving parts.

This is why application configuration should usually point to a Service name:

env:
  - name: API_BASE_URL
    value: http://api.demo.svc.cluster.local

That configuration survives replica replacements, rolling updates, and node changes without hard-coded IP maintenance.

Debugging Resolution Failures

If a Service hostname does not resolve, check these points in order:

1. Confirm the Service exists in the namespace you expect.
2. Confirm the client Pod is using cluster DNS.
3. Confirm the Service has endpoints.
4. Confirm you are using the right hostname form for the caller's namespace.

Useful commands:

1kubectl get svc -A
2kubectl get endpoints -n demo api
3kubectl exec -n demo deploy/client -- cat /etc/resolv.conf
4kubectl exec -n demo deploy/client -- nslookup api.demo.svc.cluster.local

If the Service exists but has no endpoints, DNS may still resolve while traffic fails. In that case the problem is selector matching or Pod readiness, not the hostname format.

Short Names, Namespace Names, and FQDNs

Use the shortest form that is unambiguous for the caller:

• same namespace: api
• different namespace: api.demo
• explicit full form: api.demo.svc.cluster.local

The fully qualified form is useful in debugging, cross-namespace configuration, and documentation because it removes ambiguity. In application code, many teams prefer service.namespace for readability.

Common Pitfalls

The most common mistake is trying to resolve only the service name from a different namespace. api works from demo, but not necessarily from tools. Use api.demo or the full name there.

Another issue is blaming DNS when the Service has no endpoints. Name resolution can succeed while every connection still fails because no healthy Pods back the Service.

Teams also hard-code Pod IPs during debugging and then accidentally ship that configuration. Use Service names instead unless you explicitly need Pod-level addressing.

Summary

• Kubernetes creates DNS names for Services automatically.
• In the same namespace, the short service name is often enough.
• Across namespaces, use service.namespace or the full in-cluster DNS name.
• Normal Services resolve to a cluster IP, while headless Services resolve to backend Pod IPs.
• If resolution or connectivity fails, check namespace, DNS config, and Service endpoints.