1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
# kubernetes
*kubernetes* enables reading zone data from a kubernetes cluster.
It implements the [spec](https://github.com/kubernetes/dns/blob/master/docs/specification.md)
defined for kubernetes DNS-Based service discovery:
Service `A` records are constructed as "myservice.mynamespace.svc.coredns.local" where:
* "myservice" is the name of the k8s service
* "mynamespace" is the k8s namespace for the service, and
* "svc" indicates this is a service
* "coredns.local" is the zone
Pod `A` records are constructed as "1-2-3-4.mynamespace.pod.coredns.local" where:
* "1-2-3-4" is derived from the ip address of the pod (1.2.3.4 in this example)
* "mynamespace" is the k8s namespace for the service, and
* "pod" indicates this is a pod
* "coredns.local" is the zone
Endpoint `A` records are constructed as "epname.myservice.mynamespace.svc.coredns.local" where:
* "epname" is the hostname (or name constructed from IP) of the endpoint
* "myservice" is the name of the k8s service that the endpoint serves
* "mynamespace" is the k8s namespace for the service, and
* "svc" indicates this is a service
* "coredns.local" is the zone
Also supported are PTR and SRV records for services/endpoints.
## Syntax
This is an example kubernetes configuration block, with all options described:
```
# kubernetes <zone> [<zone>] ...
#
# Use kubernetes middleware for domain "coredns.local"
# Reverse domain zones can be defined here (e.g. 0.0.10.in-addr.arpa),
# or instead with the "cidrs" option.
#
kubernetes coredns.local {
# resyncperiod <period>
#
# Kubernetes data API resync period. Default is 5m
# Example values: 60s, 5m, 1h
#
resyncperiod 5m
# endpoint <url>
#
# Use url for a remote k8s API endpoint. If omitted, it will connect to
# k8s in-cluster using the cluster service account.
#
endpoint https://k8s-endpoint:8080
# tls <cert-filename> <key-filename> <cacert-filename>
#
# The tls cert, key and the CA cert filenanames for remote k8s connection.
# This option is ignored if connecting in-cluster (i.e. endpoint is not
# specified).
#
tls cert key cacert
# namespaces <namespace> [<namespace>] ...
#
# Only expose the k8s namespaces listed. If this option is omitted
# all namespaces are exposed
#
namespaces demo
# lables <expression> [,<expression>] ...
#
# Only expose the records for kubernetes objects
# that match this label selector. The label
# selector syntax is described in the kubernetes
# API documentation: http://kubernetes.io/docs/user-guide/labels/
# Example selector below only exposes objects tagged as
# "application=nginx" in the staging or qa environments.
#
labels environment in (staging, qa),application=nginx
# pods <disabled|insecure|verified>
#
# Set the mode of responding to pod A record requests.
# e.g 1-2-3-4.ns.pod.zone. This option is provided to allow use of
# SSL certs when connecting directly to pods.
# Valid values: disabled, verified, insecure
# disabled: Do not process pod requests, always returning NXDOMAIN
# insecure: Always return an A record with IP from request (without
# checking k8s). This option is is vulnerable to abuse if
# used maliciously in conjuction with wildcard SSL certs.
# verified: Return an A record if there exists a pod in same
# namespace with matching IP. This option requires
# substantially more memory than in insecure mode, since it
# will maintain a watch on all pods.
# Default value is "disabled".
#
pods disabled
# cidrs <cidr> [<cidr>] ...
#
# Expose cidr ranges to reverse lookups. Include any number of space
# delimited cidrs, and or multiple cidrs options on separate lines.
# kubernetes middleware will respond to PTR requests for ip addresses
# that fall within these ranges.
#
cidrs 10.0.0.0/24 10.0.10.0/25
# upstream <address> [<address>] ...
#
# Defines upstream resolvers used for resolving services that point to
# external hosts (External Services). <address> can be an ip, an ip:port, or
# a path to a file structured like resolv.conf.
upstream 12.34.56.78:53
# federation <federation-name> <federation-domain>
#
# Defines federation membership. One line for each federation membership.
# Each line consists of the name of the federation, and the domain.
federation myfed foo.example.com
# autopath [NDOTS [RESPONSE [RESOLV-CONF]]
#
# Enables server side search path lookups for pods. When enabled, coredns
# will identify search path queries from pods and perform the remaining
# lookups in the path on the pod's behalf. The search path used mimics the
# resolv.conf search path deployed to pods. E.g.
#
# search ns1.svc.cluster.local svc.cluster.local cluster.local foo.com
#
# If no domains in the path produce an answer, a lookup on the bare question
# will be attempted.
#
# A successful response will contain a question section with the original
# question, and an answer section containing the record for the question that
# actually had an answer. This means that the question and answer will not
# match. For example:
#
# # host -v -t a google.com
# Trying "google.com.default.svc.cluster.local"
# ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 50957
# ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0
#
# ;; QUESTION SECTION:
# ;google.com.default.svc.cluster.local. IN A
#
# ;; ANSWER SECTION:
# google.com. 175 IN A 216.58.194.206
#
#
# NDOTS (default: 0) This provides an adjustable threshold to
# prevent server side lookups from triggering. If the number of dots before
# the first search domain is less than this number, then the search path will
# not executed on the server side.
#
# RESPONSE (default: SERVFAIL) RESPONSE can be either NXDOMAIN, SERVFAIL or
# NOERROR. This option causes coredns to return the given response instead of
# NXDOMAIN when the all searches in the path produce no results. Setting this
# to SERVFAIL or NOERROR should prevent the client from fruitlessly continuing
# the client side searches in the path after the server already checked them.
#
# RESOLV-CONF (default: /etc/resolv.conf) If specified, coredns uses this
# file to get the host's search domains. CoreDNS performs a lookup on these
# domains if the in-cluster search domains in the path fail to produce an
# answer. If not specified, the values will be read from the local resolv.conf
# file (i.e the resolv.conf file in the pod containing coredns).
#
# Enabling autopath causes coredns to use more memory since it needs to
# maintain a watch on all pods. If autopath and "pods verified" mode are
# both enabled, they will share the same watch. I.e. enabling both options
# should have an equivalent memory impact of just one.
autopath 0 SERVFAIL /etc/resolv.conf
# fallthrough
#
# If a query for a record in the cluster zone results in NXDOMAIN,
# normally that is what the response will be. However, if you specify
# this option, the query will instead be passed on down the middleware
# chain, which can include another middleware to handle the query.
fallthrough
}
```
## Wildcards
Some query labels accept a wildcard value to match any value.
If a label is a valid wildcard (\*, or the word "any"), then that label will match
all values. The labels that accept wildcards are:
* _service_ in an `A` record request: _service_.namespace.svc.zone.
* e.g. `*.ns.svc.myzone.local`
* _namespace_ in an `A` record request: service._namespace_.svc.zone.
* e.g. `nginx.*.svc.myzone.local`
* _port and/or protocol_ in an `SRV` request: __port_.__protocol_.service.namespace.svc.zone.
* e.g. `_http.*.service.ns.svc.`
* multiple wild cards are allowed in a single query.
* e.g. `A` Request `*.*.svc.zone.` or `SRV` request `*.*.*.*.svc.zone.`
## Deployment in Kubernetes
See the [deployment](https://github.com/coredns/deployment) repository for details on how
to deploy CoreDNS in Kubernetes.
|
