diff --git a/_data/tasks.yml b/_data/tasks.yml index e3e4c8dd95..8beb20b7e6 100644 --- a/_data/tasks.yml +++ b/_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/ diff --git a/docs/tasks/administer-cluster/dns-custom-nameservers.md b/docs/tasks/administer-cluster/dns-custom-nameservers.md new file mode 100644 index 0000000000..dbdf56fb99 --- /dev/null +++ b/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 %} diff --git a/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png b/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png new file mode 100644 index 0000000000..b048875f53 Binary files /dev/null and b/docs/tasks/administer-cluster/dns-custom-nameservers/dns.png differ