DNS for Services and Pods

Kubernetes creates DNS records for Services and Pods. You can contactServices with consistent DNS names instead of IP addresses.

Kubernetes publishes information about Pods and Services which is usedto program DNS. kubelet configures Pods' DNS so that running containerscan look up Services by name rather than IP.

Services defined in the cluster are assigned DNS names. By default, aclient Pod's DNS search list includes the Pod's own namespace and thecluster's default domain.

Namespaces of Services

A DNS query may return different results based on the namespace of the Pod makingit. DNS queries that don't specify a namespace are limited to the Pod'snamespace. Access Services in other namespaces by specifying it in the DNS query.

For example, consider a Pod in atest namespace. Adata Service is intheprod namespace.

A query fordata returns no results, because it uses the Pod'stest namespace.

A query fordata.prod returns the intended result, because it specifies thenamespace.

DNS queries may be expanded using the Pod's/etc/resolv.conf. kubeletconfigures this file for each Pod. For example, a query for justdata may beexpanded todata.test.svc.cluster.local. The values of thesearch optionare used to expand queries. To learn more about DNS queries, seetheresolv.conf manual page.

nameserver 10.32.0.10search <namespace>.svc.cluster.local svc.cluster.local cluster.localoptions ndots:5

In summary, a Pod in thetest namespace can successfully resolve eitherdata.prod ordata.prod.svc.cluster.local.

DNS Records

What objects get DNS records?

1. Services
2. Pods

The following sections detail the supported DNS record types and layout that issupported. Any other layout or names or queries that happen to work areconsidered implementation details and are subject to change without warning.For more up-to-date specification, seeKubernetes DNS-Based Service Discovery.

Services

A/AAAA records

"Normal" (not headless) Services are assigned DNS A and/or AAAA records,depending on the IP family or families of the Service, with a name of the formmy-svc.my-namespace.svc.cluster-domain.example. This resolves to the cluster IPof the Service.

Headless Services(without a cluster IP) are also assigned DNS A and/or AAAA records,with a name of the formmy-svc.my-namespace.svc.cluster-domain.example. Unlike normalServices, this resolves to the set of IPs of all of the Pods selected by the Service.Clients are expected to consume the set or else use standard round-robinselection from the set.

SRV records

SRV Records are created for named ports that are part of normal or headlessservices.

• For each named port, the SRV record has the form_port-name._port-protocol.my-svc.my-namespace.svc.cluster-domain.example.
• For a regular Service, this resolves to the port number and the domain name:my-svc.my-namespace.svc.cluster-domain.example.
• For a headless Service, this resolves to multiple answers, one for each Podthat is backing the Service, and contains the port number and the domain name of the Podof the formhostname.my-svc.my-namespace.svc.cluster-domain.example.

Pods

A/AAAA records

Kube-DNS versions, prior to the implementation of theDNS specification,had the following DNS resolution:

<pod-IPv4-address>.<namespace>.pod.<cluster-domain>

For example, if a Pod in thedefault namespace has the IP address 172.17.0.3,and the domain name for your cluster iscluster.local, then the Pod has a DNS name:

172-17-0-3.default.pod.cluster.local

Some cluster DNS mechanisms, likeCoreDNS, also provideA records for:

<pod-ipv4-address>.<service-name>.<my-namespace>.svc.<cluster-domain.example>

For example, if a Pod in thecafe namespace has the IP address 172.17.0.3,is an endpoint of a Service namedbarista, and the domain name for your cluster iscluster.local, then the Pod would have this service-scoped DNSA record.

172-17-0-3.barista.cafe.svc.cluster.local

Pod's hostname and subdomain fields

Currently when a Pod is created, its hostname (as observed from within the Pod)is the Pod'smetadata.name value.

The Pod spec has an optionalhostname field, which can be used to specify adifferent hostname. When specified, it takes precedence over the Pod's name to bethe hostname of the Pod (again, as observed from within the Pod). For example,given a Pod withspec.hostname set to"my-host", the Pod will have itshostname set to"my-host".

The Pod spec also has an optionalsubdomain field which can be used to indicatethat the pod is part of sub-group of the namespace. For example, a Pod withspec.hostnameset to"foo", andspec.subdomain set to"bar", in namespace"my-namespace", willhave its hostname set to"foo" and its fully qualified domain name (FQDN) set to"foo.bar.my-namespace.svc.cluster.local" (once more, as observed from withinthe Pod).

If there exists a headless Service in the same namespace as the Pod, withthe same name as the subdomain, the cluster's DNS Server also returns A and/or AAAArecords for the Pod's fully qualified hostname.

Example:

apiVersion:v1kind:Servicemetadata:name:busybox-subdomainspec:selector:name:busyboxclusterIP:Noneports:-name:foo# name is not required for single-port Servicesport:1234---apiVersion:v1kind:Podmetadata:name:busybox1labels:name:busyboxspec:hostname:busybox-1subdomain:busybox-subdomaincontainers:-image:busybox:1.28command:- sleep-"3600"name:busybox---apiVersion:v1kind:Podmetadata:name:busybox2labels:name:busyboxspec:hostname:busybox-2subdomain:busybox-subdomaincontainers:-image:busybox:1.28command:- sleep-"3600"name:busybox

Given the above Service"busybox-subdomain" and the Pods which setspec.subdomainto"busybox-subdomain", the first Pod will see its own FQDN as"busybox-1.busybox-subdomain.my-namespace.svc.cluster-domain.example". DNS servesA and/or AAAA records at that name, pointing to the Pod's IP. Both Pods "busybox1" and"busybox2" will have their own address records.

AnEndpointSlice can specifythe DNS hostname for any endpoint addresses, along with its IP.

Pod's setHostnameAsFQDN field

When a Pod is configured to have fully qualified domain name (FQDN), itshostname is the short hostname. For example, if you have a Pod with the fullyqualified domain namebusybox-1.busybox-subdomain.my-namespace.svc.cluster-domain.example,then by default thehostname command inside that Pod returnsbusybox-1 and thehostname --fqdn command returns the FQDN.

When you setsetHostnameAsFQDN: true in the Pod spec, the kubelet writes the Pod's FQDNinto the hostname for that Pod's namespace. In this case, bothhostname andhostname --fqdnreturn the Pod's FQDN.

Pod's DNS Policy

DNS policies can be set on a per-Pod basis. Currently Kubernetes supports thefollowing Pod-specific DNS policies. These policies are specified in thednsPolicy field of a Pod Spec.

• "Default": The Pod inherits the name resolution configuration from the nodethat the Pods run on.Seerelated discussionfor more details.

• "ClusterFirst": Any DNS query that does not match the configured clusterdomain suffix, such as "www.kubernetes.io", is forwarded to an upstreamnameserver by the DNS server. Cluster administrators may have extrastub-domain and upstream DNS servers configured.Seerelated discussionfor details on how DNS queries are handled in those cases.

• "ClusterFirstWithHostNet": For Pods running with hostNetwork, you shouldexplicitly set its DNS policy to "ClusterFirstWithHostNet". Otherwise, Podsrunning with hostNetwork and"ClusterFirst" will fallback to the behaviorof the"Default" policy.

  Note:

  This is not supported on Windows. Seebelow for details.

• "None": It allows a Pod to ignore DNS settings from the Kubernetesenvironment. All DNS settings are supposed to be provided using thednsConfig field in the Pod Spec.SeePod's DNS config subsection below.

The example below shows a Pod with its DNS policy set to"ClusterFirstWithHostNet" because it hashostNetwork set totrue.

apiVersion:v1kind:Podmetadata:name:busyboxnamespace:defaultspec:containers:-image:busybox:1.28command:- sleep-"3600"imagePullPolicy:IfNotPresentname:busyboxrestartPolicy:AlwayshostNetwork:truednsPolicy:ClusterFirstWithHostNet

Pod's DNS Config

Pod's DNS Config allows users more control on the DNS settings for a Pod.

ThednsConfig field is optional and it can work with anydnsPolicy settings.However, when a Pod'sdnsPolicy is set to "None", thednsConfig field hasto be specified.

Below are the properties a user can specify in thednsConfig field:

• nameservers: a list of IP addresses that will be used as DNS servers for thePod. There can be at most 3 IP addresses specified. When the Pod'sdnsPolicyis set to "None", the list must contain at least one IP address, otherwisethis property is optional.The servers listed will be combined to the base nameservers generated from thespecified 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 mergedinto the base search domain names generated from the chosen DNS policy.Duplicate domain names are removed.Kubernetes allows up to 32 search domains.
• options: an optional list of objects where each object may have anameproperty (required) and avalue property (optional). The contents in thisproperty 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:

service/networking/custom-dns.yaml

apiVersion:v1kind:Podmetadata:namespace:defaultname:dns-examplespec:containers:-name:testimage:nginxdnsPolicy:"None"dnsConfig:nameservers:-192.0.2.1# this is an examplesearches:- ns1.svc.cluster-domain.example- my.dns.search.suffixoptions:-name:ndotsvalue:"2"-name:edns0

When the Pod above is created, the containertest gets the following contentsin its/etc/resolv.conf file:

nameserver 192.0.2.1search ns1.svc.cluster-domain.example my.dns.search.suffixoptions ndots:2 edns0

For IPv6 setup, search path and name server should be set up like this:

kubectlexec -it dns-example -- cat /etc/resolv.conf

The output is similar to this:

nameserver 2001:db8:30::asearch default.svc.cluster-domain.example svc.cluster-domain.example cluster-domain.exampleoptions ndots:5

DNS search domain list limits

Kubernetes itself does not limit the DNS Config until the length of the searchdomain list exceeds 32 or the total length of all search domains exceeds 2048.This limit applies to the node's resolver configuration file, the Pod's DNSConfig, and the merged DNS Config respectively.

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 withslightly different behaviors, using theResolve-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 fullyqualified has failed.On Windows, you can only have 1 DNS suffix, which is the DNS suffix associated with thatPod'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 spawnedin thedefault namespace, will have the DNS suffixdefault.svc.cluster.local.Inside a Windows Pod, you can resolve bothkubernetes.default.svc.cluster.localandkubernetes, but not the partially qualified names (kubernetes.default orkubernetes.default.svc).

What's next

For guidance on administering DNS configurations, checkConfigure DNS Service.