You are viewing documentation for Kubernetes version: v1.24
Kubernetes v1.24 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
DNS for Services and Pods
Kubernetes creates DNS records for Services and Pods. You can contact Services with consistent DNS names instead of IP addresses.
Kubernetes DNS schedules a DNS Pod and Service on the cluster, and configures the kubelets to tell individual containers to use the DNS Service's IP to resolve DNS names.
Every Service defined in the cluster (including the DNS server itself) is assigned a DNS name. By default, a client Pod's DNS search list includes the Pod's own namespace and the cluster's default domain.
Namespaces of Services
A DNS query may return different results based on the namespace of the Pod making it. DNS queries that don't specify a namespace are limited to the Pod's namespace. Access Services in other namespaces by specifying it in the DNS query.
For example, consider a Pod in a
test namespace. A
data Service is in
A query for
data returns no results, because it uses the Pod's
A query for
data.prod returns the intended result, because it specifies the
DNS queries may be expanded using the Pod's
sets this file for each Pod. For example, a query for just
data may be
data.test.svc.cluster.local. The values of the
are used to expand queries. To learn more about DNS queries, see
resolv.conf manual page.
nameserver 10.32.0.10 search <namespace>.svc.cluster.local svc.cluster.local cluster.local options ndots:5
In summary, a Pod in the test namespace can successfully resolve either
What objects get DNS records?
The following sections detail the supported DNS record types and layout that is supported. Any other layout or names or queries that happen to work are considered implementation details and are subject to change without warning. For more up-to-date specification, see Kubernetes DNS-Based Service Discovery.
"Normal" (not headless) Services are assigned a DNS A or AAAA record,
depending on the IP family of the Service, for a name of the form
my-svc.my-namespace.svc.cluster-domain.example. This resolves to the cluster IP
of the Service.
"Headless" (without a cluster IP) Services are also assigned a DNS A or AAAA record,
depending on the IP family of the Service, for a name of the form
my-svc.my-namespace.svc.cluster-domain.example. Unlike normal
Services, this resolves to the set of IPs of the Pods selected by the Service.
Clients are expected to consume the set or else use standard round-robin
selection from the set.
SRV Records are created for named ports that are part of normal or Headless
For each named port, the SRV record would have the form
For a regular Service, this resolves to the port number and the domain name:
For a headless Service, this resolves to multiple answers, one for each Pod
that is backing the Service, and contains the port number and the domain name of the Pod
of the form
In general a Pod has the following DNS resolution:
For example, if a Pod in the
default namespace has the IP address 172.17.0.3,
and the domain name for your cluster is
cluster.local, then the Pod has a DNS name:
Any Pods exposed by a Service have the following DNS resolution available:
Pod's hostname and subdomain fields
Currently when a Pod is created, its hostname is the Pod's
The Pod spec has an optional
hostname field, which can be used to specify the
Pod's hostname. When specified, it takes precedence over the Pod's name to be
the hostname of the Pod. For example, given a Pod with
hostname set to
my-host", the Pod will have its hostname set to "
The Pod spec also has an optional
subdomain field which can be used to specify
its subdomain. For example, a Pod with
hostname set to "
set to "
bar", in namespace "
my-namespace", will have the fully qualified
domain name (FQDN) "
apiVersion: v1 kind: Service metadata: name: default-subdomain spec: selector: name: busybox clusterIP: None ports: - name: foo # Actually, no port is needed. port: 1234 targetPort: 1234 --- apiVersion: v1 kind: Pod metadata: name: busybox1 labels: name: busybox spec: hostname: busybox-1 subdomain: default-subdomain containers: - image: busybox:1.28 command: - sleep - "3600" name: busybox --- apiVersion: v1 kind: Pod metadata: name: busybox2 labels: name: busybox spec: hostname: busybox-2 subdomain: default-subdomain containers: - image: busybox:1.28 command: - sleep - "3600" name: busybox
If there exists a headless Service in the same namespace as the Pod and with
the same name as the subdomain, the cluster's DNS Server also returns an A or AAAA
record for the Pod's fully qualified hostname.
For example, given a Pod with the hostname set to "
busybox-1" and the subdomain set to
default-subdomain", and a headless Service named "
the same namespace, the Pod will see its own FQDN as
busybox-1.default-subdomain.my-namespace.svc.cluster-domain.example". DNS serves an
A or AAAA record at that name, pointing to the Pod's IP. Both Pods "
busybox2" can have their distinct A or AAAA records.
The Endpoints object can specify the
hostname for any endpoint addresses,
along with its IP.
hostnameis required for the Pod's A or AAAA record to be created. A Pod with no
subdomainwill only create the A or AAAA record for the headless Service (
default-subdomain.my-namespace.svc.cluster-domain.example), pointing to the Pod's IP address. Also, Pod needs to become ready in order to have a record unless
publishNotReadyAddresses=Trueis set on the Service.
Pod's setHostnameAsFQDN field
Kubernetes v1.22 [stable]
When a Pod is configured to have fully qualified domain name (FQDN), its hostname is the short hostname. For example, if you have a Pod with the fully qualified domain name
busybox-1.default-subdomain.my-namespace.svc.cluster-domain.example, then by default the
hostname command inside that Pod returns
busybox-1 and the
hostname --fqdn command returns the FQDN.
When you set
setHostnameAsFQDN: true in the Pod spec, the kubelet writes the Pod's FQDN into the hostname for that Pod's namespace. In this case, both
hostname --fqdn return the Pod's FQDN.
In Linux, the hostname field of the kernel (the
nodename field of
struct utsname) is limited to 64 characters.
If a Pod enables this feature and its FQDN is longer than 64 character, it will fail to start. The Pod will remain in
Pending status (
ContainerCreating as seen by
kubectl) generating error events, such as Failed to construct FQDN from Pod hostname and cluster domain, FQDN
long-FQDN is too long (64 characters is the max, 70 characters requested). One way of improving user experience for this scenario is to create an admission webhook controller to control FQDN size when users create top level objects, for example, Deployment.
Pod's DNS Policy
DNS policies can be set on a per-Pod basis. Currently Kubernetes supports the
following Pod-specific DNS policies. These policies are specified in the
dnsPolicy field of a Pod Spec.
Default": The Pod inherits the name resolution configuration from the node that the Pods run on. See related discussion for more details.
ClusterFirst": Any DNS query that does not match the configured cluster domain suffix, such as "
www.kubernetes.io", is forwarded to the upstream nameserver inherited from the node. Cluster administrators may have extra stub-domain and upstream DNS servers configured. See related discussion for details on how DNS queries are handled in those cases.
ClusterFirstWithHostNet": For Pods running with hostNetwork, you should explicitly set its DNS policy "
- Note: This is not supported on Windows. See below for details
None": It allows a Pod to ignore DNS settings from the Kubernetes environment. All DNS settings are supposed to be provided using the
dnsConfigfield in the Pod Spec. See Pod's DNS config subsection below.
dnsPolicyis not explicitly specified, then "ClusterFirst" is used.
The example below shows a Pod with its DNS policy set to
ClusterFirstWithHostNet" because it has
hostNetwork set to
apiVersion: v1 kind: Pod metadata: name: busybox namespace: default spec: containers: - image: busybox:1.28 command: - sleep - "3600" imagePullPolicy: IfNotPresent name: busybox restartPolicy: Always hostNetwork: true dnsPolicy: ClusterFirstWithHostNet
Pod's DNS Config
Kubernetes v1.14 [stable]
Pod's DNS Config allows users more control on the DNS settings for a Pod.
dnsConfig field is optional and it can work with any
However, when a Pod's
dnsPolicy is set to "
dnsConfig field has
to be specified.
Below are the properties a user can specify in the
nameservers: a list of IP addresses that will be used as DNS servers for the Pod. There can be at most 3 IP addresses specified. When the Pod's
dnsPolicyis set to "
None", the list must contain at least one IP address, otherwise this property is optional. The servers listed will be combined to the base nameservers generated from the specified DNS policy with duplicate addresses removed.
searches: a list of DNS search domains for hostname lookup in the Pod. This property is optional. When specified, the provided list will be merged into the base search domain names generated from the chosen DNS policy. Duplicate domain names are removed. Kubernetes allows for at most 6 search domains.
options: an optional list of objects where each object may have a
nameproperty (required) and a
valueproperty (optional). The contents in this property will be merged to the options generated from the specified DNS policy. Duplicate entries are removed.
The following is an example Pod with custom DNS settings:
apiVersion: v1 kind: Pod metadata: namespace: default name: dns-example spec: containers: - name: test image: nginx dnsPolicy: "None" dnsConfig: nameservers: - 18.104.22.168 searches: - ns1.svc.cluster-domain.example - my.dns.search.suffix options: - name: ndots value: "2" - name: edns0
When the Pod above is created, the container
test gets the following contents
nameserver 22.214.171.124 search ns1.svc.cluster-domain.example my.dns.search.suffix options ndots:2 edns0
For IPv6 setup, search path and name server should be set up like this:
kubectl exec -it dns-example -- cat /etc/resolv.conf
The output is similar to this:
nameserver fd00:79:30::a search default.svc.cluster-domain.example svc.cluster-domain.example cluster-domain.example options ndots:5
Expanded DNS Configuration
Kubernetes 1.22 [alpha]
By default, for Pod's DNS Config, Kubernetes allows at most 6 search domains and a list of search domains of up to 256 characters.
If the feature gate
ExpandedDNSConfig is enabled for the kube-apiserver and
the kubelet, it is allowed for Kubernetes to have at most 32 search domains and
a list of search domains of up to 2048 characters.
DNS resolution on Windows nodes
- ClusterFirstWithHostNet is not supported for Pods that run on Windows nodes.
Windows treats all names with a
.as a FQDN and skips FQDN resolution.
- On Windows, there are multiple DNS resolvers that can be used. As these come with
slightly different behaviors, using the
Resolve-DNSNamepowershell cmdlet for name query resolutions is recommended.
- On Linux, you have a DNS suffix list, which is used after resolution of a name as fully
qualified has failed.
On Windows, you can only have 1 DNS suffix, which is the DNS suffix associated with that
Pod's namespace (example:
mydns.svc.cluster.local). Windows can resolve FQDNs, Services, or network name which can be resolved with this single suffix. For example, a Pod spawned in the
defaultnamespace, will have the DNS suffix
default.svc.cluster.local. Inside a Windows Pod, you can resolve both
kubernetes, but not the partially qualified names (
For guidance on administering DNS configurations, check Configure DNS Service