Add documentation for DNS stub domains (#4063)

* Add documentation for DNS stub domains

* add additional prereq

* fix image path

* review feedback

* minor grammar and style nits

_data/tasks.yml

@@ -136,6 +136,7 @@ toc:
   - docs/tasks/administer-cluster/highly-available-master.md
   - docs/tasks/administer-cluster/configure-multiple-schedulers.md
   - docs/tasks/administer-cluster/ip-masq-agent.md
+  - docs/tasks/administer-cluster/dns-custom-nameservers.md
   - title: Change Cluster Size
     path: https://github.com/kubernetes/kubernetes/wiki/User-FAQ#how-do-i-change-the-size-of-my-cluster/
 

docs/tasks/administer-cluster/dns-custom-nameservers.md

@@ -0,0 +1,151 @@
+---
+assignees:
+- bowei
+- zihongz
+title: Configuring private DNS zones and upstream nameservers in Kubernetes
+---
+
+{% capture overview %}
+This page shows how to add custom private DNS zones (stub domains) and upstream
+nameservers.
+{% endcapture %}
+
+{% capture prerequisites %}
+* {% include task-tutorial-prereqs.md %}
+* Kubernetes version 1.6 and above.
+* The cluster must be configured to use the `kube-dns` addon.
+{% endcapture %}
+
+{% 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
+
+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.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: kube-dns
+  namespace: kube-system
+data:
+  stubDomains: |
+    {“acme.local”: [“1.2.3.4”]}
+  upstreamNameservers: |
+    [“8.8.8.8”, “8.8.4.4”]
+```
+
+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.
+
+Below is a table of example domain names and the destination of the queries for
+those domain names:
+
+| Domain name | Server answering the query |
+| ----------- | -------------------------- |
+| kubernetes.default.svc.cluster.local| kube-dns |
+| foo.acme.local| custom DNS (1.2.3.4) |
+| widget.com    | upstream DNS (one of 8.8.8.8, 8.8.4.4) |
+
+{% endcapture %}
+
+{% capture discussion %}
+
+## Understanding custom DNS upstream servers and stub domains
+
+### Pod DNS policies
+
+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:
+
+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”.
+
+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.
+
+### 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. |
+
+### Additional examples
+
+#### Example: Stub domain
+
+In this example, the user has Consul DNS service discovery system 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.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: kube-dns
+    namespace: kube-system
+    data:
+      stubDomains: |
+          {“consul.local”: [“10.150.0.1”]}
+```
+
+#### 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.
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: kube-dns
+    namespace: kube-system
+    data:
+      upstreamNameservers: |
+          [“172.16.0.1”]
+```
+
+{% endcapture %}
+
+{% include templates/task.md %}