Customize CoreDNS for Azure Kubernetes Service (AKS)

Azure Kubernetes Service (AKS) uses CoreDNS for cluster DNS management and resolution with all 1.12.x and higher clusters. 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 --output yaml command.

This article shows you how to use ConfigMaps for basic CoreDNS customization options in Azure Kubernetes Service (AKS).

Note

Previously, AKS used kube-dns for cluster DNS management and resolution, but it's now deprecated. kube-dns offered different customization options via a Kubernetes config map. CoreDNS is not backwards compatible with kube-dns. You must update any previous customizations to work with CoreDNS.

Prerequisites

This article assumes that you have an existing AKS cluster. If you need an AKS cluster, you can create one using Azure CLI, Azure PowerShell, or the Azure portal.
Verify the version of CoreDNS you're running. The configuration values might change between versions.

Plugin support

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

Important

When you create configurations like the ones in this article, the names you specify 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 --output yaml command.

Configure DNS name rewrites

Create a file named corednsms.yaml and paste in the following example configuration. Make sure to replace <___domain to be rewritten> with your own fully qualified ___domain name (FQDN).

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  test.server: |
    <___domain to be rewritten>.com:53 {
    log
    errors
    rewrite stop {
      name regex (.*)\.<___domain to be rewritten>\.com {1}.default.svc.cluster.local
      answer name (.*)\.default\.svc\.cluster\.local {1}.<___domain to be rewritten>.com
    }
    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
    }

Important

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.

Create the ConfigMap using the kubectl apply configmap command and specify the name of your YAML manifest.
```
kubectl apply -f corednsms.yaml
```
Verify the customizations were applied using the kubectl get configmaps command.
```
kubectl get configmaps --namespace=kube-system coredns-custom -o yaml
```
Perform a rolling restart to reload the ConfigMap and enable the Kubernetes Scheduler to restart CoreDNS without downtime using the kubectl rollout restart command.
```
kubectl --namespace kube-system rollout restart deployment coredns
```

Specify a forward server for your network traffic

Create a file named corednsms.yaml and paste in the following example configuration. Make sure to replace the forward name and <___domain to be rewritten> with your own values.

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  test.server: | # You can select any name here, but it must end with the .server file extension
    <___domain to be rewritten>.com:53 {
        forward foo.com 1.1.1.1
    }

Create the ConfigMap using the kubectl apply configmap command.
```
kubectl apply -f corednsms.yaml
```
Perform a rolling restart to reload the ConfigMap and enable the Kubernetes Scheduler to restart CoreDNS without downtime using the kubectl rollout restart command.
```
kubectl --namespace kube-system rollout restart deployment coredns
```

Use custom domains

You might want to configure custom domains that can only be resolved internally. For example, you might 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.

Create a new file named corednsms.yaml and paste in the following example configuration. Make sure to update the custom ___domain and IP address with your own values.

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  puglife.server: | # You can select any name here, but it must end with the .server file extension
    puglife.local:53 {
        errors
        cache 30
        forward . 192.11.0.1  # This is my test/dev DNS server
    }

Create the ConfigMap using the kubectl apply configmap command.
```
kubectl apply -f corednsms.yaml
```
Perform a rolling restart to reload the ConfigMap and enable the Kubernetes Scheduler to restart CoreDNS without downtime using the kubectl rollout restart command.
```
kubectl --namespace kube-system rollout restart deployment coredns 
```

Configure stub domains

Create a file named corednsms.yaml and paste the following example configuration. Make sure to update the custom domains and IP addresses with your own values.

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  test.server: | # You can select any name here, but it must end with the .server file extension
    abc.com:53 {
     errors
     cache 30
     forward . 1.2.3.4
    }
    my.cluster.local:53 {
        errors
        cache 30
        forward . 2.3.4.5
    }

Create the ConfigMap using the kubectl apply configmap command and specify.
```
kubectl apply -f corednsms.yaml
```
Perform a rolling restart to reload the ConfigMap and enable the Kubernetes Scheduler to restart CoreDNS without downtime using the kubectl rollout restart command.
```
kubectl --namespace kube-system rollout restart deployment coredns
```

Add custom host-to-IP mappings

Create a file named corednsms.yaml and paste the following example configuration. Make sure to update the IP addresses and hostnames with your own values.

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom # This is the name of the ConfigMap you can overwrite with your changes
  namespace: kube-system
data:
    test.override: | # You can select any name here, but it must end with the .override file extension
          hosts { 
              10.0.0.1 example1.org
              10.0.0.2 example2.org
              10.0.0.3 example3.org
              fallthrough
          }

Create the ConfigMap using the kubectl apply configmap command.
```
kubectl apply -f corednsms.yaml
```
Perform a rolling restart to reload the ConfigMap and enable the Kubernetes Scheduler to restart CoreDNS without downtime using the kubectl rollout restart command.
```
kubectl --namespace kube-system rollout restart deployment coredns
```

Next steps

To troubleshoot CoreDNS issues, see Troubleshoot issues with CoreDNS on Azure Kubernetes Service (AKS).
To learn about CoreDNS autoscaling behavior, see Autoscaling CoreDNS in Azure Kubernetes Service (AKS).

Feedback

Was this page helpful?

Last updated on 2025-10-22