# How to Customize CoreDNS for Kubernetes Clusters

DigitalOcean Kubernetes (DOKS) is a Kubernetes service with a fully managed control plane, high availability, and autoscaling. DOKS integrates with standard Kubernetes toolchains and DigitalOcean’s load balancers, volumes, CPU and GPU Droplets, API, and CLI.

**Warning**: Besides the methods in this guide, do not modify any managed components pre-installed in your DigitalOcean Kubernetes cluster, such as workloads, policies, Cilium, and CoreDNS. Modifying these services can cause your cluster’s operations to temporarily or permanently fail, and we may revert these changes at any time to maintain the functionality of your cluster.

DOKS uses [CoreDNS](https://coredns.io/) for cluster DNS management. To serve DNS requests for pods, every DOKS clusters has two CoreDNS replicas by default. To see the default configuration of the CoreDNS deployment, you can use the following command:

```shell
kubectl describe deployment coredns -n=kube-system
```

You can view the CoreDNS settings used by DOKS in the [CoreDNS’s configuration file](https://coredns.io/2017/07/23/corefile-explained/) using the following command:

```shell
kubectl get configmap -n kube-system coredns -o yaml
```

The output looks similar to the following:

```yaml
apiVersion: v1
data:
  Corefile: |
    .:53 {
        errors
        health
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
          pods insecure
          fallthrough in-addr.arpa ip6.arpa
        }
        prometheus :9153
        forward . /etc/resolv.conf
        cache 30
        loop
        reload
        loadbalance
        import custom/*.override
    }
    import custom/*.server
kind: ConfigMap
[...]
```

The default CoreDNS configuration is in the `Corefile` key of the ConfigMap and includes plugins such as [`errors`](https://coredns.io/plugins/errors), [`health`](https://coredns.io/plugins/health), [`ready`](https://coredns.io/plugins/ready), [`reload`](https://coredns.io/plugins/reload), and [`loadbalance`](https://coredns.io/plugins/loadbalance).

The [`import`](https://coredns.io/plugins/import/) plugin lets you include customizations, such as specifying a forwarding server for your network traffic, enabling logging for debugging DNS queries, or configuring your environment’s custom domains, stub domains, or upstream name servers.

The DigitalOcean Kubernetes backend overwrites any changes you make to the default CoreDNS ConfigMap. Instead of modifying the CoreDNS ConfigMap, we recommend using a Kubernetes ConfigMap to customize the CoreDNS settings of a cluster:

1. Create a custom ConfigMap that has keys named with `.override` and `.server` extensions and save it as `coredns-custom.yaml`.

   - `.override` lets you append to the default [Server Block](https://coredns.io/manual/configuration/#server-blocks) of CoreDNS. This does not let you override options that have already been specified.
   - `.server` lets you specify additional server blocks for CoreDNS.

   You can specify a name of your choice for the `.server` or `.override` extensions.

   For example, the following custom ConfigMap:

   - Adds the [`log`](https://coredns.io/plugins/log) plugin. Specifying `log` in the `.override` option to start logging at the system level. Using the plugin in the `.server` option starts logging for a specific domain.
   - Overrides the [`forward`](https://coredns.io/plugins/forward) plugin to forward requests to the specified name server. You can redirect requests to a specific DNS server that can resolve the rewritten domain name.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  log.override: |
    log
  custom.server: |
    example.io:8053 {
      forward . 8.8.8.8
    }
```

2. Apply the custom configuration to the `kube-system` namespace:

```shell
kubectl apply -f coredns-custom.yaml
```

3. Check the logs to make sure that the customization have been applied:

```shell
kubectl logs -n kube-system -l k8s-app=kube-dns
```

For the ConfigMap shown previously, the output looks similar to the following after the changes reconcile:

```
[INFO] Reloading
[INFO] plugin/reload: Running configuration MD5 = 2abff3bcc90cc5e9925581a55c02a47c
[INFO] Reloading complete
[INFO] 127.0.0.1:56186 - 38484 "HINFO IN 300556296135298597.3851195213192789444. udp 56 false 512" NXDOMAIN qr,rd,ra,ad 131 0.003940763s
[INFO] 10.244.1.134:40618 - 34833 "A IN mirror.vacares.com.svc.cluster.local. udp 54 false
[INFO] 10.244.1.134:52328 - 3722 "AAAA IN mirror.atlanticmetro.net.cluster.local. udp 56 false 512" NXDOMAIN qr,aa,rd 149 0.000093086s
[INFO] 10.244.1.134:40521 - 28128 "A IN example.io. udp 51 false 4096" NOERROR qr,rd,ra 115 0.000944973s
```

Because the example ConfigMap uses the `log` plugin, the log output here shows DNS queries, including a query to `example.io` that occurred on the cluster’s pod.

If you experience CoreDNS issues in your cluster, see [How to Troubleshoot CoreDNS Issues in DOKS Clusters](https://docs.digitalocean.com/support/how-to-troubleshoot-coredns-issues-in-doks-clusters/index.html.md) for detailed diagnostic steps. To improve CoreDNS performance, see [How can I improve the performance of cluster DNS?](https://docs.digitalocean.com/support/how-can-i-improve-the-performance-of-cluster-dns/index.html.md).