From 5ffcf129aea8b618a1f1e0c2d91f2b7d6f0b64da Mon Sep 17 00:00:00 2001 From: "Lubomir I. Ivanov (VMware)" Date: Thu, 31 May 2018 19:11:16 +0300 Subject: [PATCH 1/4] dns-custom-namerserver: break down the page into mutliple sections This page is currently about kube-dns and is a bit outdated. Introduce the heading `# Customizing kube-dns`. Introduce a separate section about CoreDNS. --- .../dns-custom-nameservers.md | 98 ++++++++++++++++++- 1 file changed, 94 insertions(+), 4 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 12bc59108853d..3b4eedabcdbf4 100644 --- a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -6,8 +6,10 @@ title: Customizing DNS Service content_template: templates/task --- +# Customizing kube-dns + {{% capture overview %}} -This page provides hints on configuring DNS Pod and guidance on customizing the +This section provides hints on configuring DNS Pod and guidance on customizing the DNS resolution process. {{% /capture %}} @@ -184,9 +186,97 @@ data: ["172.16.0.1"] ``` -## What's next -- [Debugging DNS Resolution](/docs/tasks/administer-cluster/dns-debugging-resolution/). - {{% /capture %}} +# Customizing CoreDNS + +This section provides with details on [CoreDNS](https://coredns.io/) as a service discovery. +## Introduction + +CoreDNS is available as an option in Kubernetes starting from v1.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. + + +## ConfigMap options + +CoreDNS chains plugins and can be configured by maintaining a Corefile via 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 `upstreamnameserver` translates to the `proxy` plugin in CoreDNS. +Similarly, the `Federation` plugin translates to the `federation` plugin in CoreDNS. + +### Example +Below is an example ConfigMap of kube-dns with federations, stubdomains and upstreamnameservers configured. + +```yaml +apiVersion: v1 +data: + federations: | + {"foo" : "foo.feddomain.com"} + stubDomains: | + {"abc.com" : ["1.2.3.4"], "my.cluster.local" : ["2.3.4.5"]} + upstreamNameservers: | + ["8.8.8.8", "8.8.4.4"] +kind: ConfigMap +``` + +The equivalent configuration in CoreDNS translates to the following Corefile: +* For federations: +```yaml +federation cluster.local { + foo foo.feddomain.com + } +``` + +* For StubDomains: +```yaml +abc.com:53 { + errors + cache 30 + proxy . 1.2.3.4 + } + my.cluster.local:53 { + errors + cache 30 + proxy . 2.3.4.5 + } +``` + +The complete Corefile along with the default plugins: + +```yaml +.:53 { + errors + health + kubernetes cluster.local in-addr.arpa ip6.arpa { + upstream 8.8.8.8 8.8.4.4 + pods insecure + fallthrough in-addr.arpa ip6.arpa + } + federation cluster.local { + foo foo.feddomain.com + } + prometheus :9153 + proxy . 8.8.8.8 8.8.4.4 + cache 30 + } + abc.com:53 { + errors + cache 30 + proxy . 1.2.3.4 + } + my.cluster.local:53 { + errors + cache 30 + proxy . 2.3.4.5 + } +``` + +Currently from Kubernetes 1.10, automatic translation of the CoreDNS configmap from kube-dns ConfigMap is supported via `kubeadm`. + +## Migration to CoreDNS + +Currently, a number of tools supports the installation of CoreDNS instead of kube-dns. +If a user wants 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 in adapting CoreDNS in place of kube-dns. + +## What's next +- [Debugging DNS Resolution](/docs/tasks/administer-cluster/dns-debugging-resolution/). From 82b3c75246199b1f67854d395c7454e0c322fef2 Mon Sep 17 00:00:00 2001 From: Jennifer Rondeau Date: Fri, 8 Jun 2018 10:48:39 -0400 Subject: [PATCH 2/4] Copyedits, fix headings for customizing DNS Hey Lubomir, I coypedited pretty heavily because this workflow is so much easier for docs and because I'm trying to help improve everything touching kubeadm as much as possible. But there's one outstanding issue wrt headings and intro content: you can't add a heading 1 to a topic to do what you wanted to do. The page title in the front matter is rendered as a heading 1 and everything else has to start at heading 2. (We still need to doc this better in the docs contributing content, I know.) Instead, I think we need to rewrite the top-of-page intro content to explain better the relationship between kube-dns and CoreDNS. I'm happy to write something, but I thought I'd push this commit first so you can see what I'm doing. Hope it's all clear -- ping here or on Slack with any questions ~ Jennifer --- .../dns-custom-nameservers.md | 114 +++++++++--------- 1 file changed, 56 insertions(+), 58 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 3b4eedabcdbf4..c9f37f71daea4 100644 --- a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -6,10 +6,8 @@ title: Customizing DNS Service content_template: templates/task --- -# Customizing kube-dns - {{% capture overview %}} -This section provides hints on configuring DNS Pod and guidance on customizing the +This page explains how to configure your DNS Pod and customize the DNS resolution process. {{% /capture %}} @@ -23,42 +21,42 @@ DNS resolution process. ## Introduction -Starting from Kubernetes v1.3, DNS is a built-in service launched automatically +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). -The running Kubernetes DNS pod holds 3 containers: +The running DNS Pod holds 3 containers: -- "`kubedns`": The `kubedns` process watches the Kubernetes master for changes +- "`kubedns`": watches the Kubernetes master for changes in Services and Endpoints, and maintains in-memory lookup structures to serve DNS requests. -- "`dnsmasq`": The `dnsmasq` container adds DNS caching to improve performance. -- "`sidecar`": The `sidecar` container provides a single health check endpoint - while performing dual healthchecks (for `dnsmasq` and `kubedns`). +- "`dnsmasq`": adds DNS caching to improve performance. +- "`sidecar`": provides a single health check endpoint + to perform healthchecks for `dnsmasq` and `kubedns`. -The DNS pod is exposed as a Kubernetes Service with a static IP. Once assigned -the kubelet passes DNS configured using the `--cluster-dns=` -flag to each container. +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. The local domain is configurable in the kubelet -using the flag `--cluster-domain=`. +DNS names also need domains. You configure the local domain in the kubelet +with the flag `--cluster-domain=`. -The Kubernetes cluster DNS server is based off the +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 (A records), service lookups (SRV records), and reverse IP address lookups (PTR records). ## Inheriting DNS from the node -When running a pod, kubelet will prepend the cluster DNS server and search -paths to the node's own DNS settings. If the node is able to resolve DNS names -specific to the larger environment, pods should be able to, also. -See [Known issues](#known-issues) below for a caveat. +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 +specific to the larger environment, Pods should also be able to resolve. +But see [Known issues](#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. Setting it to "" means that pods will -not inherit DNS. Setting it to a valid file path means that kubelet will use -this file instead of `/etc/resolv.conf` for DNS inheritance. +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. ## Configure stub-domain and upstream DNS servers @@ -66,7 +64,7 @@ Cluster administrators can specify custom stub domains and upstream nameservers by providing a ConfigMap for kube-dns (`kube-system:kube-dns`). For example, the following ConfigMap sets up a DNS configuration with a single stub domain and two -upstream nameservers. +upstream nameservers: ```yaml apiVersion: v1 @@ -81,11 +79,11 @@ data: ["8.8.8.8", "8.8.4.4"] ``` -As specified, DNS requests with the “.acme.local” suffix +DNS requests with the “.acme.local” suffix are forwarded to a DNS listening at 1.2.3.4. Google Public DNS serves the upstream queries. -The table below describes how queries with certain domain names would map to +The table below describes how queries with certain domain names map to their destination DNS servers: | Domain name | Server answering the query | @@ -101,9 +99,9 @@ details about the configuration option format. {{% capture discussion %}} -### Impacts on Pods +### Effects on Pods -Custom upstream nameservers and stub domains won't impact Pods that have their +Custom upstream nameservers and stub domains do not affect Pods with a `dnsPolicy` set to "`Default`" or "`None`". If a Pod's `dnsPolicy` is set to "`ClusterFirst`", its name resolution is @@ -115,23 +113,23 @@ cluster domain suffix, such as "www.kubernetes.io", is forwarded to the upstream nameserver inherited from the node. **With custom configurations**: If stub domains and upstream DNS servers are -configured (as in the [previous example](#configuring-stub-domain-and-upstream-dns-servers)), -DNS queries will be routed according to the following flow: +configured, +DNS queries are routed according to the following flow: 1. The query is first sent to the DNS caching layer in kube-dns. 1. From the caching layer, the suffix of the request is examined and then forwarded to the appropriate DNS, based on the following cases: - * *Names with the cluster suffix* (e.g.".cluster.local"): + * *Names with the cluster suffix*, for example ".cluster.local": The request is sent to kube-dns. - * *Names with the stub domain suffix* (e.g. ".acme.local"): - The request is sent to the configured custom DNS resolver (e.g. listening at 1.2.3.4). + * *Names with the stub domain suffix*, for example ".acme.local": + The request is sent to the configured custom DNS resolver, listening for example at 1.2.3.4. - * *Names without a matching suffix* (e.g."widget.com"): - The request is forwarded to the upstream DNS - (e.g. Google public DNS servers at 8.8.8.8 and 8.8.4.4). + * *Names without a matching suffix*, for example "widget.com": + The request is forwarded to the upstream DNS, + for example Google public DNS servers at 8.8.8.8 and 8.8.4.4. ![DNS lookup flow](/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png) @@ -141,17 +139,17 @@ Options for the kube-dns `kube-system:kube-dns` ConfigMap: | Field | Format | Description | | ----- | ------ | ----------- | -| `stubDomains` (optional) | A JSON map using a DNS suffix key (e.g. “acme.local”) and a value consisting of a JSON array of DNS IPs. | The target nameserver may 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. | Note: If specified, then the values specified replace the nameservers taken by default from the node’s `/etc/resolv.conf`. Limits: a maximum of three upstream nameservers can be specified. | +| `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 #### Example: Stub domain -In this example, the user has a Consul DNS service discovery system that they wish to +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 -all consul names have the suffix “.consul.local”. To configure Kubernetes, the -cluster administrator simply creates a ConfigMap object as shown below. +all consul names have the suffix `.consul.local`. To configure Kubernetes, the +cluster administrator creates the following ConfigMap: ```yaml apiVersion: v1 @@ -164,7 +162,7 @@ data: {"consul.local": ["10.150.0.1"]} ``` -Note that the cluster administrator did not wish to override the node’s +Note that the cluster administrator does not want to override the node’s upstream nameservers, so they did not specify the optional `upstreamNameservers` field. @@ -172,8 +170,8 @@ upstream nameservers, so they did not specify the optional 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. -Again, this is easy to accomplish; they just need to create a ConfigMap with the -`upstreamNameservers` field specifying the desired nameserver. +In this case, they create a ConfigMap with the +`upstreamNameservers` field specifying the desired nameserver: ```yaml apiVersion: v1 @@ -188,24 +186,23 @@ data: {{% /capture %}} -# Customizing CoreDNS - -This section provides with details on [CoreDNS](https://coredns.io/) as a service discovery. +## Configuring CoreDNS -## Introduction +You can configure [CoreDNS](https://coredns.io/) as a service discovery. -CoreDNS is available as an option in Kubernetes starting from v1.9. +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. -## ConfigMap options +## CoreDNS ConfigMap options -CoreDNS chains plugins and can be configured by maintaining a Corefile via the ConfigMap. CoreDNS supports all the functionalities and more that is provided by kube-dns. +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 `upstreamnameserver` translates to the `proxy` plugin in CoreDNS. Similarly, the `Federation` plugin translates to the `federation` plugin in CoreDNS. ### Example -Below is an example ConfigMap of kube-dns with federations, stubdomains and upstreamnameservers configured. + +This example ConfigMap for kube0dns specifies federations, stubdomains and upstreamnameservers: ```yaml apiVersion: v1 @@ -219,7 +216,8 @@ data: kind: ConfigMap ``` -The equivalent configuration in CoreDNS translates to the following Corefile: +The equivalent configuration in CoreDNS creates a Corefile: + * For federations: ```yaml federation cluster.local { @@ -227,7 +225,7 @@ federation cluster.local { } ``` -* For StubDomains: +* For stubDomains: ```yaml abc.com:53 { errors @@ -241,7 +239,7 @@ abc.com:53 { } ``` -The complete Corefile along with the default plugins: +The complete Corefile with the default plugins: ```yaml .:53 { @@ -271,12 +269,12 @@ The complete Corefile along with the default plugins: } ``` -Currently from Kubernetes 1.10, automatic translation of the CoreDNS configmap from kube-dns ConfigMap is supported via `kubeadm`. +In Kubernetes version 1.10 and later, kubeadm supports automatic translation of the CoreDNS ConfigMap from the kube-dns ConfigMap. ## Migration to CoreDNS -Currently, a number of tools supports the installation of CoreDNS instead of kube-dns. -If a user wants 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 in adapting CoreDNS in place of kube-dns. +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. ## What's next - [Debugging DNS Resolution](/docs/tasks/administer-cluster/dns-debugging-resolution/). From 17c62892119f122b4d90a71598692f9acb63dab5 Mon Sep 17 00:00:00 2001 From: Jennifer Rondeau Date: Tue, 12 Jun 2018 07:45:22 -0400 Subject: [PATCH 3/4] Interim fix for talking about CoreDNS --- .../administer-cluster/dns-custom-nameservers.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 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 c9f37f71daea4..1fbc83ab50ebd 100644 --- a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -8,13 +8,16 @@ content_template: templates/task {{% capture overview %}} This page explains how to configure your DNS Pod and customize the -DNS resolution process. +DNS resolution process. In Kubernetes version 1.11 and later, CoreDNS is installed +by default. See [Configuring CoreDNS](#config-coredns) and +[Using CoreDNS for Service Discovery](/docs/tasks/administer-cluster/coredns/). {{% /capture %}} {{% capture prerequisites %}} * {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} -* Kubernetes version 1.6 and above. -* The cluster must be configured to use the `kube-dns` addon. +* Kubernetes version 1.6 or later. To work with CoreDNS, version 1.9 or later. +* The cluster must be configured to use the `kube-dns` add-on. Note that the add-on name +is the same whether you run kube-dns or CoreDNS. {{% /capture %}} {{% capture steps %}} @@ -186,7 +189,7 @@ data: {{% /capture %}} -## Configuring CoreDNS +## Configuring CoreDNS {config-coredns} You can configure [CoreDNS](https://coredns.io/) as a service discovery. From 39c799f232f6950138f7afb8c4b45b0a083c7064 Mon Sep 17 00:00:00 2001 From: Jennifer Rondeau Date: Tue, 12 Jun 2018 09:07:24 -0400 Subject: [PATCH 4/4] Fix CoreDNS details --- .../tasks/administer-cluster/dns-custom-nameservers.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 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 1fbc83ab50ebd..695ceab5e9c7c 100644 --- a/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -8,16 +8,16 @@ content_template: templates/task {{% capture overview %}} This page explains how to configure your DNS Pod and customize the -DNS resolution process. In Kubernetes version 1.11 and later, CoreDNS is installed -by default. See [Configuring CoreDNS](#config-coredns) and -[Using CoreDNS for Service Discovery](/docs/tasks/administer-cluster/coredns/). +DNS resolution process. In Kubernetes version 1.11 and later, CoreDNS is at GA +and is installed by default with kubeadm. See [Configuring CoreDNS](#config-coredns) +and [Using CoreDNS for Service Discovery](/docs/tasks/administer-cluster/coredns/). {{% /capture %}} {{% capture prerequisites %}} * {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} * Kubernetes version 1.6 or later. To work with CoreDNS, version 1.9 or later. -* The cluster must be configured to use the `kube-dns` add-on. Note that the add-on name -is the same whether you run kube-dns or CoreDNS. +* The appropriate add-on: kube-dns or CoreDNS. To install with kubeadm, +see [the kubeadm reference documentation](/docs/reference/setup-tools/kubeadm/kubeadm-alpha/#cmd-phase-addon). {{% /capture %}} {{% capture steps %}}