Skip to content

Commit 2ed2862

Browse files
v-shilsv-shils
authored
Merge pull request #229441 from schaffererin/core-dns-aks
Core DNS AKS - Freshness pass and GitIssues
2 parents 5ac9669 + 37d947d commit 2ed2862

File tree

1 file changed

+154
-125
lines changed

1 file changed

+154
-125
lines changed

‎articles/aks/coredns-custom.md

Lines changed: 154 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -4,167 +4,185 @@ description: Learn how to customize CoreDNS to add subdomains or extend custom D
44
ms.subservice: aks-networking
55
author: asudbring
66
ms.topic: how-to
7-
ms.date: 03/15/2019
7+
ms.date: 03/03/2023
88
ms.author: allensu
99

1010
#Customer intent: As a cluster operator or developer, I want to learn how to customize the CoreDNS configuration to add sub domains or extend to custom DNS endpoints within my network
1111
---
1212

1313
# Customize CoreDNS with Azure Kubernetes Service
1414

15-
Azure Kubernetes Service (AKS) uses the [CoreDNS][coredns] project for cluster DNS management and resolution with all *1.12.x* and higher clusters. Previously, the kube-dns project was used. This kube-dns project is now deprecated. For more information about CoreDNS customization and Kubernetes, see the [official upstream documentation][corednsk8s].
15+
Azure Kubernetes Service (AKS) uses the [CoreDNS][coredns] project for cluster DNS management and resolution with all *1.12.x* and higher clusters. For more information about CoreDNS customization and Kubernetes, see the [official upstream documentation][corednsk8s].
1616

17-
As AKS is a managed service, you cannot modify the main configuration for CoreDNS (a *CoreFile*). Instead, you use a Kubernetes *ConfigMap* to override the default settings. To see the default AKS CoreDNS ConfigMaps, use the `kubectl get configmaps --namespace=kube-system coredns -o yaml` command.
17+
AKS is a managed service, so you can't modify the main configuration for CoreDNS (a *CoreFile*). Instead, you use a Kubernetes *ConfigMap* to override the default settings. To see the default AKS CoreDNS ConfigMaps, use the `kubectl get configmaps --namespace=kube-system coredns -o yaml` command.
1818

19-
This article shows you how to use ConfigMaps for basic customization options of CoreDNS in AKS. This approach differs from configuring CoreDNS in other contexts such as using the CoreFile. Verify the version of CoreDNS you are running as the configuration values may change between versions.
19+
This article shows you how to use ConfigMaps for basic CoreDNS customization options of in AKS. This approach differs from configuring CoreDNS in other contexts, such as CoreFile.
2020

2121
> [!NOTE]
22-
> `kube-dns` offered different [customization options][kubednsblog] via a Kubernetes config map. CoreDNS is **not** backwards compatible with kube-dns. Any customizations you previously used must be updated for use with CoreDNS.
22+
> Previously, kube-dns was used for cluster DNS management and resolution, but it's now deprecated. `kube-dns` offered different [customization options][kubednsblog] via a Kubernetes config map. CoreDNS is **not** backwards compatible with kube-dns. Any customizations you previously used must be updated for CoreDNS.
2323
2424
## Before you begin
2525

26-
This article assumes that you have an existing AKS cluster. If you need an AKS cluster, see the AKS quickstart [using the Azure CLI][aks-quickstart-cli], [using Azure PowerShell][aks-quickstart-powershell], or [using the Azure portal][aks-quickstart-portal].
26+
* This article assumes that you have an existing AKS cluster. If you need an AKS cluster, you can create one using [Azure CLI][aks-quickstart-cli], [Azure PowerShell][aks-quickstart-powershell], or the [Azure portal][aks-quickstart-portal].
27+
* Verify the version of CoreDNS you're running. The configuration values may change between versions.
28+
* When you create configurations like the examples below, your names in the *data* section must end in *.server* or *.override*. This naming convention is defined in the default AKS CoreDNS ConfigMap, which you can view using the `kubectl get configmaps --namespace=kube-system coredns -o yaml` command.
2729

28-
When creating a configuration like the examples below, your names in the *data* section must end in either *.server* or *.override*. This naming convention is defined in the default AKS CoreDNS Configmap which you can view using the `kubectl get configmaps --namespace=kube-system coredns -o yaml` command.
29-
30-
## What is supported/unsupported
30+
## Plugin support
3131

3232
All built-in CoreDNS plugins are supported. No add-on/third party plugins are supported.
3333

3434
## Rewrite DNS
3535

36-
One scenario you have is to perform on-the-fly DNS name rewrites. In the following example, replace `<domain to be written>` with your own fully qualified domain name. Create a file named `corednsms.yaml` and paste the following example configuration:
36+
You can customize CoreDNS with AKS to perform on-the-fly DNS name rewrites.
3737

38-
```yaml
39-
apiVersion: v1
40-
kind: ConfigMap
41-
metadata:
42-
name: coredns-custom
43-
namespace: kube-system
44-
data:
45-
test.server: | # you may select any name here, but it must end with the .server file extension
46-
<domain to be rewritten>.com:53 {
47-
log
48-
errors
49-
rewrite stop {
50-
name regex (.*)\.<domain to be rewritten>.com {1}.default.svc.cluster.local
51-
answer name (.*)\.default\.svc\.cluster\.local {1}.<domain to be rewritten>.com
52-
}
53-
forward . /etc/resolv.conf # you can redirect this to a specific DNS server such as 10.0.0.10, but that server must be able to resolve the rewritten domain name
54-
}
55-
```
38+
1. Create a file named `corednsms.yaml` and paste the following example configuration. Make sure to replace `<domain to be rewritten>` with your own fully qualified domain name.
5639

57-
> [!IMPORTANT]
58-
> If you redirect to a DNS server, such as the CoreDNS service IP, that DNS server must be able to resolve the rewritten domain name.
40+
```yaml
41+
apiVersion: v1
42+
kind: ConfigMap
43+
metadata:
44+
name: coredns-custom
45+
namespace: kube-system
46+
data:
47+
test.override: |
48+
<domain to be rewritten>.com:53 {
49+
log
50+
errors
51+
rewrite stop {
52+
name regex (.*)\.<domain to be rewritten>.com {1}.default.svc.cluster.local
53+
answer name (.*)\.default\.svc\.cluster\.local {1}.<domain to be rewritten>.com
54+
}
55+
forward . /etc/resolv.conf # you can redirect this to a specific DNS server such as 10.0.0.10, but that server must be able to resolve the rewritten domain name
56+
}
57+
```
5958
60-
Create the ConfigMap using the [kubectl apply configmap][kubectl-apply] command and specify the name of your YAML manifest:
59+
> [!IMPORTANT]
60+
> If you redirect to a DNS server, such as the CoreDNS service IP, that DNS server must be able to resolve the rewritten domain name.
6161
62-
```console
63-
kubectl apply -f corednsms.yaml
64-
```
62+
2. Create the ConfigMap using the [`kubectl apply configmap`][kubectl-apply] command and specify the name of your YAML manifest.
6563

66-
To verify the customizations have been applied, use the [kubectl get configmaps][kubectl-get] and specify your *coredns-custom* ConfigMap:
64+
```console
65+
kubectl apply -f corednsms.yaml
66+
```
6767

68-
```
69-
kubectl get configmaps --namespace=kube-system coredns-custom -o yaml
70-
```
68+
3. Verify the customizations have been applied using the [`kubectl get configmaps`][kubectl-get] and specify your *coredns-custom* ConfigMap.
7169

72-
Now force CoreDNS to reload the ConfigMap. The [kubectl delete pod][kubectl delete] command isn't destructive and doesn't cause down time. The `kube-dns` pods are deleted, and the Kubernetes Scheduler then recreates them. These new pods contain the change in TTL value.
70+
```console
71+
kubectl get configmaps --namespace=kube-system coredns-custom -o yaml
72+
```
7373

74-
```console
75-
kubectl delete pod --namespace kube-system -l k8s-app=kube-dns
76-
```
74+
4. Force CoreDNS to reload the ConfigMap using the [`kubectl delete pod`][kubectl delete] command and the `kube-dns` label. This command deletes the `kube-dns` pods, and then the Kubernetes Scheduler recreates them. The new pods contain the change in TTL value.
7775

78-
> [!Note]
79-
> The command above is correct. While we're changing `coredns`, the deployment is under the **kube-dns** label.
76+
```console
77+
kubectl delete pod --namespace kube-system -l k8s-app=kube-dns
78+
```
8079

8180
## Custom forward server
8281

83-
If you need to specify a forward server for your network traffic, you can create a ConfigMap to customize DNS. In the following example, update the `forward` name and address with the values for your own environment. Create a file named `corednsms.yaml` and paste the following example configuration:
82+
If you need to specify a forward server for your network traffic, you can create a ConfigMap to customize DNS.
8483

85-
```yaml
86-
apiVersion: v1
87-
kind: ConfigMap
88-
metadata:
89-
name: coredns-custom
90-
namespace: kube-system
91-
data:
92-
test.server: | # you may select any name here, but it must end with the .server file extension
93-
<domain to be rewritten>.com:53 {
94-
forward foo.com 1.1.1.1
95-
}
96-
```
84+
1. Create a file named `corednsms.yaml` and paste the following example configuration. Make sure to replace the `forward` name and the address with the values for your own environment.
9785

98-
As in the previous examples, create the ConfigMap using the [kubectl apply configmap][kubectl-apply] command and specify the name of your YAML manifest. Then, force CoreDNS to reload the ConfigMap using the [kubectl delete pod][kubectl delete] for the Kubernetes Scheduler to recreate them:
86+
```yaml
87+
apiVersion: v1
88+
kind: ConfigMap
89+
metadata:
90+
name: coredns-custom
91+
namespace: kube-system
92+
data:
93+
test.server: | # you may select any name here, but it must end with the .server file extension
94+
<domain to be rewritten>.com:53 {
95+
forward foo.com 1.1.1.1
96+
}
97+
```
9998

100-
```console
101-
kubectl apply -f corednsms.yaml
102-
kubectl delete pod --namespace kube-system --selector k8s-app=kube-dns
103-
```
99+
2. Create the ConfigMap using the [`kubectl apply configmap`][kubectl-apply] command and specify the name of your YAML manifest.
100+
101+
```console
102+
kubectl apply -f corednsms.yaml
103+
```
104+
105+
3. Force CoreDNS to reload the ConfigMap using the [`kubectl delete pod`][kubectl delete] so the Kubernetes Scheduler can recreate them.
106+
107+
```console
108+
kubectl delete pod --namespace kube-system -l k8s-app=kube-dns
109+
```
104110

105111
## Use custom domains
106112

107113
You may want to configure custom domains that can only be resolved internally. For example, you may want to resolve the custom domain *puglife.local*, which isn't a valid top-level domain. Without a custom domain ConfigMap, the AKS cluster can't resolve the address.
108114

109-
In the following example, update the custom domain and IP address to direct traffic to with the values for your own environment. Create a file named `corednsms.yaml` and paste the following example configuration:
115+
1. Create a new file named `corednsms.yaml` and paste the following example configuration. Make sure to update the custom domain and IP address with the values for your own environment.
110116

111-
```yaml
112-
apiVersion: v1
113-
kind: ConfigMap
114-
metadata:
115-
name: coredns-custom
116-
namespace: kube-system
117-
data:
118-
puglife.server: | # you may select any name here, but it must end with the .server file extension
119-
puglife.local:53 {
120-
errors
121-
cache 30
122-
forward . 192.11.0.1 # this is my test/dev DNS server
123-
}
124-
```
117+
```yaml
118+
apiVersion: v1
119+
kind: ConfigMap
120+
metadata:
121+
name: coredns-custom
122+
namespace: kube-system
123+
data:
124+
puglife.server: | # you may select any name here, but it must end with the .server file extension
125+
puglife.local:53 {
126+
errors
127+
cache 30
128+
forward . 192.11.0.1 # this is my test/dev DNS server
129+
}
130+
```
125131

126-
As in the previous examples, create the ConfigMap using the [kubectl apply configmap][kubectl-apply] command and specify the name of your YAML manifest. Then, force CoreDNS to reload the ConfigMap using the [kubectl delete pod][kubectl delete] for the Kubernetes Scheduler to recreate them:
132+
2. Create the ConfigMap using the [`kubectl apply configmap`][kubectl-apply] command and specify the name of your YAML manifest.
127133

128-
```console
129-
kubectl apply -f corednsms.yaml
130-
kubectl delete pod --namespace kube-system --selector k8s-app=kube-dns
131-
```
134+
```console
135+
kubectl apply -f corednsms.yaml
136+
```
137+
138+
3. Force CoreDNS to reload the ConfigMap using the [`kubectl delete pod`][kubectl delete] so the Kubernetes Scheduler can recreate them.
139+
140+
```console
141+
kubectl delete pod --namespace kube-system -l k8s-app=kube-dns
142+
```
132143

133144
## Stub domains
134145

135-
CoreDNS can also be used to configure stub domains. In the following example, update the custom domains and IP addresses with the values for your own environment. Create a file named `corednsms.yaml` and paste the following example configuration:
146+
CoreDNS can also be used to configure stub domains.
136147

137-
```yaml
138-
apiVersion: v1
139-
kind: ConfigMap
140-
metadata:
141-
name: coredns-custom
142-
namespace: kube-system
143-
data:
144-
test.server: | # you may select any name here, but it must end with the .server file extension
145-
abc.com:53 {
146-
errors
147-
cache 30
148-
forward . 1.2.3.4
149-
}
150-
my.cluster.local:53 {
151-
errors
152-
cache 30
153-
forward . 2.3.4.5
154-
}
148+
1. Create a file named `corednsms.yaml` and paste the following example configuration. Make sure to update the custom domains and IP addresses with the values for your own environment.
155149

156-
```
150+
```yaml
151+
apiVersion: v1
152+
kind: ConfigMap
153+
metadata:
154+
name: coredns-custom
155+
namespace: kube-system
156+
data:
157+
test.server: | # you may select any name here, but it must end with the .server file extension
158+
abc.com:53 {
159+
errors
160+
cache 30
161+
forward . 1.2.3.4
162+
}
163+
my.cluster.local:53 {
164+
errors
165+
cache 30
166+
forward . 2.3.4.5
167+
}
157168
158-
As in the previous examples, create the ConfigMap using the [kubectl apply configmap][kubectl-apply] command and specify the name of your YAML manifest. Then, force CoreDNS to reload the ConfigMap using the [kubectl delete pod][kubectl delete] for the Kubernetes Scheduler to recreate them:
169+
```
159170

160-
```console
161-
kubectl apply -f corednsms.yaml
162-
kubectl delete pod --namespace kube-system --selector k8s-app=kube-dns
163-
```
171+
2. Create the ConfigMap using the [`kubectl apply configmap`][kubectl-apply] command and specify the name of your YAML manifest.
172+
173+
```console
174+
kubectl apply -f corednsms.yaml
175+
```
176+
177+
3. Force CoreDNS to reload the ConfigMap using the [`kubectl delete pod`][kubectl delete] so the Kubernetes Scheduler can recreate them.
178+
179+
```console
180+
kubectl delete pod --namespace kube-system -l k8s-app=kube-dns
181+
```
164182

165183
## Hosts plugin
166184

167-
As all built-in plugins are supported this means that the CoreDNS [Hosts][coredns hosts] plugin is available to customize as well:
185+
All built-in plugins are supported, so the [CoreDNS hosts][coredns hosts] plugin is available to customize as well.
168186

169187
```yaml
170188
apiVersion: v1
@@ -184,26 +202,38 @@ data:
184202

185203
## Troubleshooting
186204

187-
For general CoreDNS troubleshooting steps, such as checking the endpoints or resolution, see [Debugging DNS Resolution][coredns-troubleshooting].
205+
For general CoreDNS troubleshooting steps, such as checking the endpoints or resolution, see [Debugging DNS resolution][coredns-troubleshooting].
188206

189-
To enable DNS query logging, apply the following configuration in your coredns-custom ConfigMap:
207+
### Enable DNS query logging
190208

191-
```yaml
192-
apiVersion: v1
193-
kind: ConfigMap
194-
metadata:
195-
name: coredns-custom
196-
namespace: kube-system
197-
data:
198-
log.override: | # you may select any name here, but it must end with the .override file extension
199-
log
200-
```
209+
1. Add the following configuration to your coredns-custom ConfigMap:
201210

202-
After you apply the configuration changes, use the `kubectl logs` command to view the CoreDNS debug logging. For example:
211+
```yaml
212+
apiVersion: v1
213+
kind: ConfigMap
214+
metadata:
215+
name: coredns-custom
216+
namespace: kube-system
217+
data:
218+
log.override: | # you may select any name here, but it must end with the .override file extension
219+
log
220+
```
203221

204-
```console
205-
kubectl logs --namespace kube-system --selector k8s-app=kube-dns
206-
```
222+
2. Apply the configuration changes and force CoreDNS to reload the ConfigMap using the following commands:
223+
224+
```console
225+
# Apply configuration changes
226+
kubectl apply -f corednsms.yaml
227+
228+
# Force CoreDNS to reload the ConfigMap
229+
kubectl delete pod --namespace kube-system -l k8s-app=kube-dns
230+
```
231+
232+
3. View the CoreDNS debug logging using the `kubectl logs` command.
233+
234+
```console
235+
kubectl logs --namespace kube-system -l k8s-app=kube-dns
236+
```
207237

208238
## Next steps
209239

@@ -215,7 +245,6 @@ To learn more about core network concepts, see [Network concepts for application
215245
[kubednsblog]: https://www.danielstechblog.io/using-custom-dns-server-for-domain-specific-name-resolution-with-azure-kubernetes-service/
216246
[coredns]: https://coredns.io/
217247
[corednsk8s]: https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#coredns
218-
[dnscache]: https://coredns.io/plugins/cache/
219248
[kubectl-apply]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#apply
220249
[kubectl-get]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get
221250
[kubectl delete]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#delete

0 commit comments

Comments
 (0)