From bc23d45c09d7b83cac130fe22a0bd91e72435862 Mon Sep 17 00:00:00 2001 From: Zach Arnold Date: Mon, 17 Sep 2018 10:45:29 -0700 Subject: [PATCH] Revert "Add CoreDNS details to the customize DNS doc (#10228)" This reverts commit e7319eeb8cde914d06cad039867e6213ecef1001. --- .../dns-custom-nameservers.md | 172 ++++-------------- 1 file changed, 33 insertions(+), 139 deletions(-) diff --git a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md index d16ff5f5d2..76447cb678 100644 --- a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -28,19 +28,28 @@ DNS is a built-in Kubernetes service launched automatically using the addon manager [cluster add-on](http://releases.k8s.io/{{< param "githubbranch" >}}/cluster/addons/README.md). -As of Kubernetes v1.12, CoreDNS is the recommended DNS Server, replacing kube-dns. However, kube-dns may still be installed by -default with certain Kubernetes installer tools. Refer to the documentation provided by your installer to know which DNS server is installed by default. +The running DNS Pod holds 3 containers: +- "`kubedns`": watches the Kubernetes master for changes + in Services and Endpoints, and maintains in-memory lookup structures to serve + DNS requests. +- "`dnsmasq`": adds DNS caching to improve performance. +- "`sidecar`": provides a single health check endpoint + to perform healthchecks for `dnsmasq` and `kubedns`. -The CoreDNS Deployment is exposed as a Kubernetes Service with a static IP. -Both the CoreDNS and kube-dns Service are named `kube-dns` in the `metadata.name` field. This is done so that there is greater interoperability with workloads that relied on the legacy `kube-dns` Service name to resolve addresses internal to the cluster. It abstracts away the implementation detail of which DNS provider is running behind that common endpoint. -The kubelet passes DNS to each container with the `--cluster-dns=` flag. +The DNS Pod is exposed as a Kubernetes Service with a static IP. +The kubelet passes DNS to each container with the `--cluster-dns=` +flag. DNS names also need domains. You configure the local domain in the kubelet with the flag `--cluster-domain=`. -The DNS server supports forward lookups (A records), port lookups (SRV records), reverse IP address lookups (PTR records), -and more. For more information see [DNS for Services and Pods] (/docs/concepts/services-networking/dns-pod-service/). +The Kubernetes cluster DNS server is based on the +[SkyDNS](https://github.com/skynetservices/skydns) library. It supports forward +lookups (A records), service lookups (SRV records), and reverse IP address +lookups (PTR records). + +## Inheriting DNS from the node When running a Pod, kubelet prepends the cluster DNS server and searches paths to the node's DNS settings. If the node is able to resolve DNS names @@ -52,130 +61,7 @@ use the kubelet's `--resolv-conf` flag. Set this flag to "" to prevent Pods fro 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] -(https://github.com/kubernetes/dns/blob/master/docs/specification.md). - -### 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](https://coredns.io/2017/07/23/corefile-explained/), which is the CoreDNS -configuration file. A cluster administrator can modify the ConfigMap for the CoreDNS Corefile to change how service discovery works. - -In Kubernetes, CoreDNS is installed with the following default Corefile configuration. - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: coredns - namespace: kube-system -Corefile: | - .:53 { - errors - health - kubernetes cluster.local in-addr.arpa ip6.arpa { - pods insecure - upstream - fallthrough in-addr.arpa ip6.arpa - } - prometheus :9153 - proxy . /etc/resolv.conf - cache 30 - loop - reload - loadbalance - } -``` -The Corefile configuration includes the following [plugins](https://coredns.io/plugins/) of CoreDNS: - -* [errors](https://coredns.io/plugins/errors/): Errors are logged to stdout. -* [health](https://coredns.io/plugins/health/): Health of CoreDNS is reported to http://localhost:8080/health. -* [kubernetes](https://coredns.io/plugins/kubernetes/): CoreDNS will reply to DNS queries based on IP of the services and pods of Kubernetes. You can find more details [here](https://coredns.io/plugins/kubernetes/). - -> The `pods insecure` option is provided for backward compatibility with kube-dns. You can use the `pod 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. - -> `Upstream` is used for resolving services that point to external hosts (External Services). - -* [prometheus](https://coredns.io/plugins/prometheus/): Metrics of CoreDNS are available at http://localhost:9153/metrics in [Prometheus](https://prometheus.io/) format. -* [proxy](https://coredns.io/plugins/proxy/): Any queries that are not within the cluster domain of Kubernetes will be forwarded to predefined resolvers (/etc/resolv.conf). -* [cache](https://coredns.io/plugins/cache/): This enables a frontend cache. -* [loop](https://coredns.io/plugins/loop/): Detects simple forwarding loops and halts the CoreDNS process if a loop is found. -* [reload](https://coredns.io/plugins/reload): Allows automatic reload of a changed Corefile. -* [loadbalance](https://coredns.io/plugins/loadbalance): This is a round-robin DNS loadbalancer by randomizing the order of A, AAAA, and MX records in the answer. - -We can modify the default behavior by modifying this configmap. - -### Configuration of Stub-domain and upstream nameserver using CoreDNS - -CoreDNS has the ability to configure stubdomains and upstream nameservers using the [proxy plugin](https://coredns.io/plugins/proxy/). - -#### Example -If a cluster operator has a [Consul](https://www.consul.io/) 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. - -``` -consul.local:53 { - errors - cache 30 - proxy . 10.150.0.1 - } -``` - -To explicitly force all non-cluster DNS lookups to go through a specific nameserver at 172.16.0.1, point the `proxy` and `upstream` to the nameserver instead of `/etc/resolv.conf` - -``` -proxy . 172.16.0.1 -``` -``` -upstream 172.16.0.1 -``` - -So, the final ConfigMap along with the default `Corefile` configuration will look like: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: coredns - namespace: kube-system -Corefile: | - .:53 { - errors - health - kubernetes cluster.local in-addr.arpa ip6.arpa { - pods insecure - upstream 172.16.0.1 - fallthrough in-addr.arpa ip6.arpa - } - prometheus :9153 - proxy . 172.16.0.1 - cache 30 - loop - reload - loadbalance - } - consul.local:53 { - errors - cache 30 - proxy . 10.150.0.1 - } -``` -In Kubernetes version 1.10 and later, kubeadm supports automatic translation of the CoreDNS ConfigMap from the kube-dns ConfigMap. - -## Kube-dns - -Kube-dns is now available as a optional DNS server since CoreDNS is now the default. -The running DNS Pod holds 3 containers: - -- "`kubedns`": watches the Kubernetes master for changes - in Services and Endpoints, and maintains in-memory lookup structures to serve - DNS requests. -- "`dnsmasq`": adds DNS caching to improve performance. -- "`sidecar`": provides a single health check endpoint - to perform healthchecks for `dnsmasq` and `kubedns`. - -### Configure stub-domain and upstream DNS servers +## Configure stub-domain and upstream DNS servers Cluster administrators can specify custom stub domains and upstream nameservers by providing a ConfigMap for kube-dns (`kube-system:kube-dns`). @@ -216,7 +102,7 @@ details about the configuration option format. {{% capture discussion %}} -#### Effects on Pods +### Effects on Pods Custom upstream nameservers and stub domains do not affect Pods with a `dnsPolicy` set to "`Default`" or "`None`". @@ -250,7 +136,7 @@ DNS queries are routed according to the following flow: ![DNS lookup flow](/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png) -### ConfigMap options +## ConfigMap options Options for the kube-dns `kube-system:kube-dns` ConfigMap: @@ -259,9 +145,9 @@ Options for the kube-dns `kube-system:kube-dns` ConfigMap: | `stubDomains` (optional) | A JSON map using a DNS suffix key such as “acme.local”, and a value consisting of a JSON array of DNS IPs. | The target nameserver can itself be a Kubernetes Service. For instance, you can run your own copy of dnsmasq to export custom DNS names into the ClusterDNS namespace. | | `upstreamNameservers` (optional) | A JSON array of DNS IPs. | If specified, the values replace the nameservers taken by default from the node’s `/etc/resolv.conf`. Limits: a maximum of three upstream nameservers can be specified. | -#### Examples +### Examples -##### Example: Stub domain +#### Example: Stub domain In this example, the user has a Consul DNS service discovery system they want to integrate with kube-dns. The consul domain server is located at 10.150.0.1, and @@ -283,7 +169,7 @@ Note that the cluster administrator does not want to override the node’s upstream nameservers, so they did not specify the optional `upstreamNameservers` field. -##### Example: Upstream nameserver +#### Example: Upstream nameserver In this example the cluster administrator wants to explicitly force all non-cluster DNS lookups to go through their own nameserver at 172.16.0.1. @@ -303,9 +189,17 @@ data: {{% /capture %}} -## CoreDNS configuration equivalent to kube-dns +## Configuring CoreDNS {#config-coredns} -CoreDNS supports all the functionalities and more that is provided by kube-dns. +You can configure [CoreDNS](https://coredns.io/) as a service discovery. + +CoreDNS is available as an option in Kubernetes starting with version 1.9. +It is currently a [GA feature](https://github.com/kubernetes/community/blob/master/keps/sig-network/0010-20180314-coredns-GA-proposal.md) and is on course to be [the default](https://github.com/kubernetes/community/blob/master/keps/sig-network/0012-20180518-coredns-default-proposal.md), replacing kube-dns. + + +## CoreDNS ConfigMap options + +CoreDNS chains plugins and can be configured by maintaining a Corefile with the ConfigMap. CoreDNS supports all the functionalities and more that is provided by kube-dns. A ConfigMap created for kube-dns to support `StubDomains`and `upstreamNameservers` translates to the `proxy` plugin in CoreDNS. Similarly, the `Federation` plugin translates to the `federation` plugin in CoreDNS. @@ -382,8 +276,8 @@ In Kubernetes version 1.10 and later, kubeadm supports automatic translation of ## Migration to CoreDNS +A number of tools support the installation of CoreDNS instead of kube-dns. To migrate from kube-dns to CoreDNS, [a detailed blog](https://coredns.io/2018/05/21/migration-from-kube-dns-to-coredns/) is available to help users adapt CoreDNS in place of kube-dns. -A cluster administrator can also migrate using [the deploy script](https://github.com/coredns/deployment/blob/master/kubernetes/deploy.sh), which will also help you translate the kube-dns configmap to the equivalent CoreDNS one. ## What's next - [Debugging DNS Resolution](/docs/tasks/administer-cluster/dns-debugging-resolution/).