Skip to content

Commit 1edd6fd

Browse files
tengqmtengqm
committed
Tweak DNS customization page
The `kube-dns` option has been deprecated since 1.18 and no longer supported. The support to `kube-dns` has been removed from kubeadm since 1.21. This PR tweaks the DNS customization page to remove the outdated contents and also reformat the paragraphs where appropriate.
1 parent 6528f71 commit 1edd6fd

File tree

1 file changed

+59
-112
lines changed

1 file changed

+59
-112
lines changed

‎content/en/docs/tasks/administer-cluster/dns-custom-nameservers.md

Lines changed: 59 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@ DNS resolution process in your cluster.
1717
{{< include "task-tutorial-prereqs.md" >}}
1818

1919
Your cluster must be running the CoreDNS add-on.
20-
[Migrating to CoreDNS](/docs/tasks/administer-cluster/coredns/#migrating-to-coredns)
21-
explains how to use `kubeadm` to migrate from `kube-dns`.
2220

2321
{{% version-check %}}
2422

@@ -27,25 +25,27 @@ explains how to use `kubeadm` to migrate from `kube-dns`.
2725
## Introduction
2826

2927
DNS is a built-in Kubernetes service launched automatically
30-
using the _addon manager_
31-
[cluster add-on](http://releases.k8s.io/master/cluster/addons/README.md).
32-
33-
As of Kubernetes v1.12, CoreDNS is the recommended DNS Server, replacing kube-dns. If your cluster
34-
originally used kube-dns, you may still have `kube-dns` deployed rather than CoreDNS.
28+
using the _addon manager_ [cluster add-on](http://releases.k8s.io/master/cluster/addons/README.md).
3529

3630
{{< note >}}
3731
The CoreDNS Service is named `kube-dns` in the `metadata.name` field.
38-
This is so that there is greater interoperability with workloads that relied on the legacy `kube-dns` Service name to resolve addresses internal to the cluster. Using a Service named `kube-dns` abstracts away the implementation detail of which DNS provider is running behind that common name.
32+
The intent is to ensure greater interoperability with workloads that relied on
33+
the legacy `kube-dns` Service name to resolve addresses internal to the cluster.
34+
Using a Service named `kube-dns` abstracts away the implementation detail of
35+
which DNS provider is running behind that common name.
3936
{{< /note >}}
4037

41-
If you are running CoreDNS as a Deployment, it will typically be exposed as a Kubernetes Service with a static IP address.
42-
The kubelet passes DNS resolver information to each container with the `--cluster-dns=<dns-service-ip>` flag.
38+
If you are running CoreDNS as a Deployment, it will typically be exposed as
39+
a Kubernetes Service with a static IP address.
40+
The kubelet passes DNS resolver information to each container with the
41+
`--cluster-dns=<dns-service-ip>` flag.
4342

4443
DNS names also need domains. You configure the local domain in the kubelet
4544
with the flag `--cluster-domain=<default-local-domain>`.
4645

47-
The DNS server supports forward lookups (A and AAAA records), port lookups (SRV records), reverse IP address lookups (PTR records),
48-
and more. For more information, see [DNS for Services and Pods](/docs/concepts/services-networking/dns-pod-service/).
46+
The DNS server supports forward lookups (A and AAAA records), port lookups (SRV records),
47+
reverse IP address lookups (PTR records), and more. For more information, see
48+
[DNS for Services and Pods](/docs/concepts/services-networking/dns-pod-service/).
4949

5050
If a Pod's `dnsPolicy` is set to `default`, it inherits the name resolution
5151
configuration from the node that the Pod runs on. The Pod's DNS resolution
@@ -59,15 +59,16 @@ inheriting DNS. Set it to a valid file path to specify a file other than
5959

6060
## CoreDNS
6161

62-
CoreDNS is a general-purpose authoritative DNS server that can serve as cluster DNS, complying with the [dns specifications](https://github.com/kubernetes/dns/blob/master/docs/specification.md).
62+
CoreDNS is a general-purpose authoritative DNS server that can serve as cluster DNS,
63+
complying with the [DNS specifications](https://github.com/kubernetes/dns/blob/master/docs/specification.md).
6364

6465
### CoreDNS ConfigMap options
6566

66-
CoreDNS is a DNS server that is modular and pluggable, and each plugin adds new functionality to CoreDNS.
67-
This can be configured by maintaining a [Corefile](https://coredns.io/2017/07/23/corefile-explained/), which is the CoreDNS
68-
configuration file. As a cluster administrator, you can modify the
69-
{{< glossary_tooltip text="ConfigMap" term_id="configmap" >}} for the CoreDNS Corefile to change how DNS service discovery
70-
behaves for that cluster.
67+
CoreDNS is a DNS server that is modular and pluggable, with plugins adding new functionalities.
68+
The CoreDNS server can be configured by maintaining a [Corefile](https://coredns.io/2017/07/23/corefile-explained/),
69+
which is the CoreDNS configuration file. As a cluster administrator, you can modify the
70+
{{< glossary_tooltip text="ConfigMap" term_id="configmap" >}} for the CoreDNS Corefile to
71+
change how DNS service discovery behaves for that cluster.
7172

7273
In Kubernetes, CoreDNS is installed with the following default Corefile configuration:
7374

@@ -102,35 +103,57 @@ data:
102103
The Corefile configuration includes the following [plugins](https://coredns.io/plugins/) of CoreDNS:
103104
104105
* [errors](https://coredns.io/plugins/errors/): Errors are logged to stdout.
105-
* [health](https://coredns.io/plugins/health/): Health of CoreDNS is reported to `http://localhost:8080/health`. In this extended syntax `lameduck` will make the process unhealthy then wait for 5 seconds before the process is shut down.
106-
* [ready](https://coredns.io/plugins/ready/): An HTTP endpoint on port 8181 will return 200 OK, when all plugins that are able to signal readiness have done so.
107-
* [kubernetes](https://coredns.io/plugins/kubernetes/): CoreDNS will reply to DNS queries based on IP of the services and pods of Kubernetes. You can find [more details](https://coredns.io/plugins/kubernetes/) about that plugin on the CoreDNS website. `ttl` allows you to set a custom TTL for responses. The default is 5 seconds. The minimum TTL allowed is 0 seconds, and the maximum is capped at 3600 seconds. Setting TTL to 0 will prevent records from being cached.
108-
The `pods insecure` option is provided for backward compatibility with _kube-dns_. You can use the `pods verified` option, which returns an A record only if there exists a pod in same namespace with matching IP. The `pods disabled` option can be used if you don't use pod records.
109-
* [prometheus](https://coredns.io/plugins/metrics/): Metrics of CoreDNS are available at `http://localhost:9153/metrics` in [Prometheus](https://prometheus.io/) format (also known as OpenMetrics).
110-
* [forward](https://coredns.io/plugins/forward/): Any queries that are not within the cluster domain of Kubernetes will be forwarded to predefined resolvers (/etc/resolv.conf).
106+
* [health](https://coredns.io/plugins/health/): Health of CoreDNS is reported to
107+
`http://localhost:8080/health`. In this extended syntax `lameduck` will make theuprocess
108+
unhealthy then wait for 5 seconds before the process is shut down.
109+
* [ready](https://coredns.io/plugins/ready/): An HTTP endpoint on port 8181 will return 200 OK,
110+
when all plugins that are able to signal readiness have done so.
111+
* [kubernetes](https://coredns.io/plugins/kubernetes/): CoreDNS will reply to DNS queries
112+
based on IP of the Services and Pods. You can find [more details](https://coredns.io/plugins/kubernetes/)
113+
about this plugin on the CoreDNS website.
114+
- `ttl` allows you to set a custom TTL for responses. The default is 5 seconds.
115+
The minimum TTL allowed is 0 seconds, and the maximum is capped at 3600 seconds.
116+
Setting TTL to 0 will prevent records from being cached.
117+
- The `pods insecure` option is provided for backward compatibility with `kube-dns`.
118+
- You can use the `pods verified` option, which returns an A record only if there exists a pod
119+
in the same namespace with a matching IP.
120+
- The `pods disabled` option can be used if you don't use pod records.
121+
* [prometheus](https://coredns.io/plugins/metrics/): Metrics of CoreDNS are available at
122+
`http://localhost:9153/metrics` in the [Prometheus](https://prometheus.io/) format
123+
(also known as OpenMetrics).
124+
* [forward](https://coredns.io/plugins/forward/): Any queries that are not within the Kubernetes
125+
cluster domain are forwarded to predefined resolvers (/etc/resolv.conf).
111126
* [cache](https://coredns.io/plugins/cache/): This enables a frontend cache.
112-
* [loop](https://coredns.io/plugins/loop/): Detects simple forwarding loops and halts the CoreDNS process if a loop is found.
113-
* [reload](https://coredns.io/plugins/reload): Allows automatic reload of a changed Corefile. After you edit the ConfigMap configuration, allow two minutes for your changes to take effect.
114-
* [loadbalance](https://coredns.io/plugins/loadbalance): This is a round-robin DNS loadbalancer that randomizes the order of A, AAAA, and MX records in the answer.
127+
* [loop](https://coredns.io/plugins/loop/): Detects simple forwarding loops and
128+
halts the CoreDNS process if a loop is found.
129+
* [reload](https://coredns.io/plugins/reload): Allows automatic reload of a changed Corefile.
130+
After you edit the ConfigMap configuration, allow two minutes for your changes to take effect.
131+
* [loadbalance](https://coredns.io/plugins/loadbalance): This is a round-robin DNS loadbalancer
132+
that randomizes the order of A, AAAA, and MX records in the answer.
115133

116134
You can modify the default CoreDNS behavior by modifying the ConfigMap.
117135

118136
### Configuration of Stub-domain and upstream nameserver using CoreDNS
119137

120-
CoreDNS has the ability to configure stubdomains and upstream nameservers using the [forward plugin](https://coredns.io/plugins/forward/).
138+
CoreDNS has the ability to configure stub-domains and upstream nameservers
139+
using the [forward plugin](https://coredns.io/plugins/forward/).
121140

122141
#### Example
123-
If a cluster operator has a [Consul](https://www.consul.io/) domain server located at 10.150.0.1, and all Consul names have the suffix .consul.local. To configure it in CoreDNS, the cluster administrator creates the following stanza in the CoreDNS ConfigMap.
142+
143+
If a cluster operator has a [Consul](https://www.consul.io/) domain server located at "10.150.0.1",
144+
and all Consul names have the suffix ".consul.local". To configure it in CoreDNS,
145+
the cluster administrator creates the following stanza in the CoreDNS ConfigMap.
124146

125147
```
126148
consul.local:53 {
127-
errors
128-
cache 30
129-
forward . 10.150.0.1
130-
}
149+
errors
150+
cache 30
151+
forward . 10.150.0.1
152+
}
131153
```
132154
133-
To explicitly force all non-cluster DNS lookups to go through a specific nameserver at 172.16.0.1, point the `forward` to the nameserver instead of `/etc/resolv.conf`
155+
To explicitly force all non-cluster DNS lookups to go through a specific nameserver at 172.16.0.1,
156+
point the `forward` to the nameserver instead of `/etc/resolv.conf`
134157
135158
```
136159
forward . 172.16.0.1
@@ -167,88 +190,12 @@ data:
167190
}
168191
```
169192

170-
The `kubeadm` tool supports automatic translation from the kube-dns ConfigMap
171-
to the equivalent CoreDNS ConfigMap.
172-
173193
{{< note >}}
174-
While kube-dns accepts an FQDN for stubdomain and nameserver (eg: ns.foo.com), CoreDNS does not support this feature.
194+
CoreDNS does not support FQDNs for stub-domains and nameservers (eg: "ns.foo.com").
175195
During translation, all FQDN nameservers will be omitted from the CoreDNS config.
176196
{{< /note >}}
177197

178-
## CoreDNS configuration equivalent to kube-dns
179-
180-
CoreDNS supports the features of kube-dns and more.
181-
A ConfigMap created for kube-dns to support `StubDomains`and `upstreamNameservers` translates to the `forward` plugin in CoreDNS.
182-
183-
### Example
184-
185-
This example ConfigMap for kube-dns specifies stubdomains and upstreamnameservers:
186-
187-
```yaml
188-
apiVersion: v1
189-
data:
190-
stubDomains: |
191-
{"abc.com" : ["1.2.3.4"], "my.cluster.local" : ["2.3.4.5"]}
192-
upstreamNameservers: |
193-
["8.8.8.8", "8.8.4.4"]
194-
kind: ConfigMap
195-
```
196-
197-
The equivalent configuration in CoreDNS creates a Corefile:
198-
199-
* For stubDomains:
200-
```yaml
201-
abc.com:53 {
202-
errors
203-
cache 30
204-
forward . 1.2.3.4
205-
}
206-
my.cluster.local:53 {
207-
errors
208-
cache 30
209-
forward . 2.3.4.5
210-
}
211-
```
212-
213-
The complete Corefile with the default plugins:
214-
215-
```
216-
.:53 {
217-
errors
218-
health
219-
kubernetes cluster.local in-addr.arpa ip6.arpa {
220-
pods insecure
221-
fallthrough in-addr.arpa ip6.arpa
222-
}
223-
federation cluster.local {
224-
foo foo.feddomain.com
225-
}
226-
prometheus :9153
227-
forward . 8.8.8.8 8.8.4.4
228-
cache 30
229-
}
230-
abc.com:53 {
231-
errors
232-
cache 30
233-
forward . 1.2.3.4
234-
}
235-
my.cluster.local:53 {
236-
errors
237-
cache 30
238-
forward . 2.3.4.5
239-
}
240-
```
241-
242-
## Migration to CoreDNS
243-
244-
To migrate from kube-dns to CoreDNS, a detailed
245-
[blog article](https://coredns.io/2018/05/21/migration-from-kube-dns-to-coredns/)
246-
is available to help users adapt CoreDNS in place of kube-dns.
247-
248-
You can also migrate using the official CoreDNS
249-
[deploy script](https://github.com/coredns/deployment/blob/master/kubernetes/deploy.sh).
250-
251-
252198
## {{% heading "whatsnext" %}}
253199

254200
- Read [Debugging DNS Resolution](/docs/tasks/administer-cluster/dns-debugging-resolution/)
201+

0 commit comments

Comments
 (0)