whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Edits for Custom DNS Documentation (#4207)

Browse Source 
* reorganize custom dns doc

* format fixes
This commit is contained in:
Jessica Yao
2017-06-27 16:26:46 -07:00
committed by Andrew Chen
parent 3e5b11f901
commit a18484cad2
1 changed files with 52 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tasks/administer-cluster/dns-custom-nameservers.md
+52 -55
View File
@@ -2,7 +2,7 @@
assignees: assignees:
- bowei - bowei
- zihongz - zihongz
title: Configuring private DNS zones and upstream nameservers in Kubernetes title: Configure private DNS zones and upstream nameservers in Kubernetes
--- ---
{% capture overview %} {% capture overview %}
@@ -18,29 +18,13 @@ nameservers.
{% capture steps %} {% capture steps %}
## Name resolution in Kubernetes ## Configure stub-domain and upstream DNS servers
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 Cluster administrators can specify custom stub domains and upstream nameservers
by providing a ConfigMap for kube-dns (`kube-system:kube-dns`). by providing a ConfigMap for kube-dns (`kube-system:kube-dns`).
For example, the configuration below inserts a single stub domain and two For example, the following ConfigMap sets up a DNS configuration with a single stub domain and two
upstream nameservers. As specified, DNS requests with the “.acme.local” suffix upstream nameservers.
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 ```yaml
apiVersion: v1 apiVersion: v1
@@ -55,16 +39,11 @@ data:
[“8.8.8.8”, “8.8.4.4”] [“8.8.8.8”, “8.8.4.4”]
``` ```
With the dnsPolicy set to “ClusterFirst”, a DNS query is first sent to As specified, DNS requests with the “.acme.local” suffix
the DNS caching layer in kube-dns. From there, the suffix of the request is are forwarded to a DNS listening at 1.2.3.4. Google Public DNS
examined and then forwarded to the appropriate DNS. In this case, names with serves the upstream queries.
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 The table below describes how queries with certain domain names would map to their destination DNS servers:
those domain names:
| Domain name | Server answering the query | | Domain name | Server answering the query |
| ----------- | -------------------------- | | ----------- | -------------------------- |
@@ -72,49 +51,63 @@ those domain names:
| foo.acme.local| custom DNS (1.2.3.4) | | foo.acme.local| custom DNS (1.2.3.4) |
| widget.com | upstream DNS (one of 8.8.8.8, 8.8.4.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 %} {% endcapture %}
{% capture discussion %} {% 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 *NOTE: "Default" is not the default DNS policy. If `dnsPolicy` is not
using the dnsPolicy flag: “Default” and “ClusterFirst”. If dnsPolicy is not explicitly specified, then “ClusterFirst” is used.*
explicitly specified, then “ClusterFirst” is used:
If dnsPolicy is set to “Default”, then the name resolution configuration is ### "Default" DNS Policy
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 If `dnsPolicy` is set to “Default”, then the name resolution configuration is
kube-dns service. Queries for domains rooted in the configured cluster domain inherited from the node that the pods run on. Custom upstream nameservers and stub domains cannot be used in conjunction with this policy.
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 ### "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 Options for the kube-dns `kube-system:kube-dns` ConfigMap
| Field | Format | Description | | 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. | | `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. | | `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 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 all consul names have the suffix “.consul.local”. To configure Kubernetes, the
cluster administrator simply creates a ConfigMap object as shown below. Note: cluster administrator simply creates a ConfigMap object as shown below.
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 ```yaml
apiVersion: v1 apiVersion: v1
@@ -127,12 +120,16 @@ metadata:
{“consul.local”: [“10.150.0.1”]} {“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 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. 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 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 ```yaml
apiVersion: v1 apiVersion: v1