Customizing DNS Service

This page explains how to configure your DNS Pod(s) and customize the DNS resolution process in your cluster.

Before you begin

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you do not already have a cluster, you can create one by using minikube or you can use one of these Kubernetes playgrounds:

Your cluster must be running the CoreDNS add-on. Migrating to CoreDNS explains how to use kubeadm to migrate from kube-dns.

Your Kubernetes server must be at or later than version v1.12. To check the version, enter kubectl version.

Introduction

DNS is a built-in Kubernetes service launched automatically using the addon manager cluster add-on.

As of Kubernetes v1.12, CoreDNS is the recommended DNS Server, replacing kube-dns. If your cluster originally used kube-dns, you may still have kube-dns deployed rather than CoreDNS.

Note: Both the CoreDNS and kube-dns Service are named kube-dns in the metadata.name field.
This is so that there is greater interoperability with workloads that relied on the legacy kube-dns Service name to resolve addresses internal to the cluster. Using a Service named kube-dns abstracts away the implementation detail of which DNS provider is running behind that common name.

If you are running CoreDNS as a Deployment, it will typically be exposed as a Kubernetes Service with a static IP address. The kubelet passes DNS resolver information to each container with the --cluster-dns=<dns-service-ip> flag.

DNS names also need domains. You configure the local domain in the kubelet with the flag --cluster-domain=<default-local-domain>.

The DNS server supports forward lookups (A and AAAA records), port lookups (SRV records), reverse IP address lookups (PTR records), and more. For more information, see DNS for Services and Pods.

If a Pod’s dnsPolicy is set to default, it inherits the name resolution configuration from the node that the Pod runs on. The Pod’s DNS resolution should behave the same as the node. But see Known issues.

If you don’t want this, or if you want a different DNS config for pods, you can use the kubelet’s --resolv-conf flag. Set this flag to “” to prevent Pods from inheriting DNS. Set it to a valid file path to specify a file other than /etc/resolv.conf for DNS inheritance.

CoreDNS

CoreDNS is a general-purpose authoritative DNS server that can serve as cluster DNS, complying with the dns specifications.

CoreDNS ConfigMap options

CoreDNS is a DNS server that is modular and pluggable, and each plugin adds new functionality to CoreDNS. This can be configured by maintaining a Corefile, which is the CoreDNS configuration file. As a cluster administrator, you can modify the ConfigMap for the CoreDNS Corefile to change how DNS service discovery behaves for that cluster.

In Kubernetes, CoreDNS is installed with the following default Corefile configuration:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: coredns
  5.   namespace: kube-system
  6. data:
  7.   Corefile: |
  8.     .:53 {
  9.         errors
  10.         health {
  11.             lameduck 5s
  12.         }
  13.         ready
  14.         kubernetes cluster.local in-addr.arpa ip6.arpa {
  15.             pods insecure
  16.             fallthrough in-addr.arpa ip6.arpa
  17.             ttl 30
  18.         }
  19.         prometheus :9153
  20.         forward . /etc/resolv.conf
  21.         cache 30
  22.         loop
  23.         reload
  24.         loadbalance
  25.     }

The Corefile configuration includes the following plugins of CoreDNS:

  • errors: Errors are logged to stdout.
  • health: Health of CoreDNS is reported to http://localhost:8080/health. In this extended syntax lameduck will make the process unhealthy then wait for 5 seconds before the process is shut down.
  • ready: An HTTP endpoint on port 8181 will return 200 OK, when all plugins that are able to signal readiness have done so.
  • kubernetes: CoreDNS will reply to DNS queries based on IP of the services and pods of Kubernetes. You can find more details about that plugin on the CoreDNS website. ttl allows you to set a custom TTL for responses. The default is 5 seconds. The minimum TTL allowed is 0 seconds, and the maximum is capped at 3600 seconds. Setting TTL to 0 will prevent records from being cached.
    The pods insecure option is provided for backward compatibility with kube-dns. You can use the pods verified option, which returns an A record only if there exists a pod in same namespace with matching IP. The pods disabled option can be used if you don’t use pod records.
  • prometheus: Metrics of CoreDNS are available at http://localhost:9153/metrics in Prometheus format (also known as OpenMetrics).
  • forward: Any queries that are not within the cluster domain of Kubernetes will be forwarded to predefined resolvers (/etc/resolv.conf).
  • cache: This enables a frontend cache.
  • loop: Detects simple forwarding loops and halts the CoreDNS process if a loop is found.
  • reload: Allows automatic reload of a changed Corefile. After you edit the ConfigMap configuration, allow two minutes for your changes to take effect.
  • loadbalance: This is a round-robin DNS loadbalancer that randomizes the order of A, AAAA, and MX records in the answer.

You can modify the default CoreDNS behavior by modifying the ConfigMap.

Configuration of Stub-domain and upstream nameserver using CoreDNS

CoreDNS has the ability to configure stubdomains and upstream nameservers using the forward plugin.

Example

If a cluster operator has a Consul domain server located at 10.150.0.1, and all Consul names have the suffix .consul.local. To configure it in CoreDNS, the cluster administrator creates the following stanza in the CoreDNS ConfigMap.

  1. consul.local:53 {
  2.         errors
  3.         cache 30
  4.         forward . 10.150.0.1
  5.     }

To explicitly force all non-cluster DNS lookups to go through a specific nameserver at 172.16.0.1, point the forward to the nameserver instead of /etc/resolv.conf

  1. forward .  172.16.0.1

The final ConfigMap along with the default Corefile configuration looks like:

  1. apiVersion: v1
  2. kind: ConfigMap
  3. metadata:
  4.   name: coredns
  5.   namespace: kube-system
  6. data:
  7.   Corefile: |
  8.     .:53 {
  9.         errors
  10.         health
  11.         kubernetes cluster.local in-addr.arpa ip6.arpa {
  12.            pods insecure
  13.            fallthrough in-addr.arpa ip6.arpa
  14.         }
  15.         prometheus :9153
  16.         forward . 172.16.0.1
  17.         cache 30
  18.         loop
  19.         reload
  20.         loadbalance
  21.     }
  22.     consul.local:53 {
  23.         errors
  24.         cache 30
  25.         forward . 10.150.0.1
  26.     }

The kubeadm tool supports automatic translation from the kube-dns ConfigMap to the equivalent CoreDNS ConfigMap.

Note: While kube-dns accepts an FQDN for stubdomain and nameserver (eg: ns.foo.com), CoreDNS does not support this feature. During translation, all FQDN nameservers will be omitted from the CoreDNS config.

CoreDNS configuration equivalent to kube-dns

CoreDNS supports the features of kube-dns and more. A ConfigMap created for kube-dns to support StubDomainsand upstreamNameservers translates to the forward plugin in CoreDNS. Similarly, the Federations plugin in kube-dns translates to the federation plugin in CoreDNS.

Example

This example ConfigMap for kube-dns specifies federations, stubdomains and upstreamnameservers:

  1. apiVersion: v1
  2. data:
  3.   federations: |
  4.     {"foo" : "foo.feddomain.com"}
  5.   stubDomains: |
  6.     {"abc.com" : ["1.2.3.4"], "my.cluster.local" : ["2.3.4.5"]}
  7.   upstreamNameservers: |
  8.     ["8.8.8.8", "8.8.4.4"]
  9. kind: ConfigMap

The equivalent configuration in CoreDNS creates a Corefile:

  • For federations:
  1. federation cluster.local {
  2.     foo foo.feddomain.com
  3. }
  • For stubDomains:
  1. abc.com:53 {
  2.     errors
  3.     cache 30
  4.     forward . 1.2.3.4
  5. }
  6. my.cluster.local:53 {
  7.     errors
  8.     cache 30
  9.     forward . 2.3.4.5
  10. }

The complete Corefile with the default plugins:

  1. .:53 {
  2.     errors
  3.     health
  4.     kubernetes cluster.local in-addr.arpa ip6.arpa {
  5.         pods insecure
  6.         fallthrough in-addr.arpa ip6.arpa
  7.     }
  8.     federation cluster.local {
  9.         foo foo.feddomain.com
  10.     }
  11.     prometheus :9153
  12.     forward . 8.8.8.8 8.8.4.4
  13.     cache 30
  14. }
  15. abc.com:53 {
  16.     errors
  17.     cache 30
  18.     forward . 1.2.3.4
  19. }
  20. my.cluster.local:53 {
  21.     errors
  22.     cache 30
  23.     forward . 2.3.4.5
  24. }

Migration to CoreDNS

To migrate from kube-dns to CoreDNS, a detailed blog article is available to help users adapt CoreDNS in place of kube-dns.

You can also migrate using the offical CoreDNS deploy script.

What’s next