From a18484cad26456fda4d4a4c5ec507f5810bf9a3e Mon Sep 17 00:00:00 2001 From: Jessica Yao Date: Tue, 27 Jun 2017 16:26:46 -0700 Subject: [PATCH] Edits for Custom DNS Documentation (#4207) * reorganize custom dns doc * format fixes --- .../dns-custom-nameservers.md | 107 +++++++++--------- 1 file changed, 52 insertions(+), 55 deletions(-) diff --git a/docs/tasks/administer-cluster/dns-custom-nameservers.md b/docs/tasks/administer-cluster/dns-custom-nameservers.md index e6d925f556..fc708429a6 100644 --- a/docs/tasks/administer-cluster/dns-custom-nameservers.md +++ b/docs/tasks/administer-cluster/dns-custom-nameservers.md @@ -2,7 +2,7 @@ assignees: - bowei - zihongz -title: Configuring private DNS zones and upstream nameservers in Kubernetes +title: Configure private DNS zones and upstream nameservers in Kubernetes --- {% capture overview %} @@ -18,29 +18,13 @@ nameservers. {% capture steps %} -## Name resolution in Kubernetes - -The diagram below shows the flow of DNS queries specified in the configuration -above. With the dnsPolicy set to “ClusterFirst” a DNS query is first sent to -the DNS caching layer in kube-dns. From there, the suffix of the request is -examined and then forwarded to the appropriate DNS. In this case, names with -the cluster suffix (e.g. “.cluster.local”) are sent to kube-dns. Names with -the stub domain suffix (e.g. “.acme.local”) are sent to the configured -custom resolver. Finally, requests that do not match any of those suffixes are -forwarded to the upstream DNS. - -![DNS lookup flow](/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png) - -## Configuring 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`). -For example, the configuration below inserts a single stub domain and two -upstream nameservers. As specified, DNS requests with the “.acme.local” suffix -are forwarded to a DNS listening at 1.2.3.4. Additionally, Google Public DNS -serves the upstream queries. See the [ConfigMap options](#configmap-options) for -details about the configuration option format. +For example, the following ConfigMap sets up a DNS configuration with a single stub domain and two +upstream nameservers. ```yaml apiVersion: v1 @@ -55,16 +39,11 @@ data: [“8.8.8.8”, “8.8.4.4”] ``` -With the dnsPolicy set to “ClusterFirst”, a DNS query is first sent to -the DNS caching layer in kube-dns. From there, the suffix of the request is -examined and then forwarded to the appropriate DNS. In this case, names with -the cluster suffix (e.g. “.cluster.local”) are sent to kube-dns. Names with the -stub domain suffix (e.g. “.acme.local”) are sent to the configured custom -resolver. Finally, requests that do not match any of those suffixes are -forwarded to the upstream DNS. +As specified, 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. -Below is a table of example domain names and the destination of the queries for -those domain names: +The table below describes how queries with certain domain names would map to their destination DNS servers: | Domain name | Server answering the query | | ----------- | -------------------------- | @@ -72,49 +51,63 @@ those domain names: | foo.acme.local| custom DNS (1.2.3.4) | | widget.com | upstream DNS (one of 8.8.8.8, 8.8.4.4) | +See [ConfigMap options](#configmap-options) for +details about the configuration option format. + {% endcapture %} {% capture discussion %} -## Understanding custom DNS upstream servers and stub domains +## Understanding name resolution in Kubernetes -### Pod DNS policies +DNS policies can be set on a per-pod basis. Currently Kubernetes supports two pod-specific DNS policies: “Default” and “ClusterFirst”. These policies are specified with the `dnsPolicy` flag. -Kubernetes currently supports two DNS policies specified on a per-pod basis -using the dnsPolicy flag: “Default” and “ClusterFirst”. If dnsPolicy is not -explicitly specified, then “ClusterFirst” is used: +*NOTE: "Default" is not the default DNS policy. If `dnsPolicy` is not +explicitly specified, then “ClusterFirst” is used.* -If dnsPolicy is set to “Default”, then the name resolution configuration is -inherited from the node the pods run on. Note: custom upstream nameservers and -stub domains cannot be used in conjunction with dnsPolicy: “Default”. +### "Default" DNS Policy -If dnsPolicy is set to “ClusterFirst”, then DNS queries are sent to the -kube-dns service. Queries for domains rooted in the configured cluster domain -suffix (any address ending in “.cluster.local” in the example above) are -answered by the kube-dns service. All other queries, such as -www.kubernetes.io, are forwarded to the upstream nameserver inherited from -the node. +If `dnsPolicy` is set to “Default”, then the name resolution configuration is +inherited from the node that the pods run on. Custom upstream nameservers and stub domains cannot be used in conjunction with this policy. -### ConfigMap options +### "ClusterFirst" DNS Policy + +If the `dnsPolicy` is set to "ClusterFirst", name resolution is handled differently, *depending on whether stub-domain and upstream DNS servers are configured*. + +**Without custom configurations**: Any 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. + +**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: + +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"): 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 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). + +![DNS lookup flow](/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png) + +## ConfigMap options 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 (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. | -### Additional examples +## Additional examples -#### Example: Stub domain +### Example: Stub domain -In this example, the user has Consul DNS service discovery system they wish to +In this example, the user has a Consul DNS service discovery system that they wish 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. Note: -in this example, the cluster administrator did not wish to override the node’s -upstream nameservers, so they didn’t need to specify the optional -upstreamNameservers field. +cluster administrator simply creates a ConfigMap object as shown below. ```yaml apiVersion: v1 @@ -127,12 +120,16 @@ metadata: {“consul.local”: [“10.150.0.1”]} ``` -#### Example: Upstream nameserver +Note that the cluster administrator did not wish to override the node’s +upstream nameservers, so they did not specify the optional +`upstreamNameservers` field. + +### 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. Again, this is easy to accomplish; they just need to create a ConfigMap with the -upstreamNameservers field specifying the desired nameserver. +`upstreamNameservers` field specifying the desired nameserver. ```yaml apiVersion: v1