Skip to content

Commit

Permalink
dns-custom-namerserver: break down the page into mutliple sections (#…
Browse files Browse the repository at this point in the history 
…8900)

* 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.

* 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

* Interim fix for talking about CoreDNS

* Fix CoreDNS details
  • Loading branch information
@neolit123
neolit123 authored and Misty Stanley-Jones committed Jun 20, 2018
1 parent 4770301 commit 06c00e7
Showing 1 changed file with 139 additions and 48 deletions.
187 changes: 139 additions & 48 deletions content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,64 +7,67 @@ content_template: templates/task
---

{{% capture overview %}}
This page provides hints on configuring DNS Pod and guidance on customizing the
DNS resolution process.
This page explains how to configure your DNS Pod and customize the
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 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 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 %}}

## 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=<dns-service-ip>`
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=<dns-service-ip>`
flag.

DNS names also need domains. The local domain is configurable in the kubelet
using the flag `--cluster-domain=<default-local-domain>`.
DNS names also need domains. You configure the local domain in the kubelet
with the flag `--cluster-domain=<default-local-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

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
Expand All @@ -79,11 +82,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 |
Expand All @@ -99,9 +102,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
Expand All @@ -113,23 +116,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)

Expand All @@ -139,17 +142,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
Expand All @@ -162,16 +165,16 @@ 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.

#### 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.
In this case, they create a ConfigMap with the
`upstreamNameservers` field specifying the desired nameserver:

```yaml
apiVersion: v1
Expand All @@ -184,9 +187,97 @@ data:
["172.16.0.1"]
```

## What's next
- [Debugging DNS Resolution](/docs/tasks/administer-cluster/dns-debugging-resolution/).

{{% /capture %}}

## Configuring CoreDNS {config-coredns}

You can configure [CoreDNS](https://coredns.io/) as a service discovery.

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.


## CoreDNS ConfigMap options

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

This example ConfigMap for kube0dns specifies federations, stubdomains and upstreamnameservers:

```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 creates a 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 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
}
```

In Kubernetes version 1.10 and later, kubeadm supports automatic translation of the CoreDNS ConfigMap from the kube-dns ConfigMap.

## Migration to CoreDNS

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/).

0 comments on commit 06c00e7

Please sign in to comment.