CoreDNS Corefile Migration for Kubernetes

CoreDNS has been the default DNS server for Kubernetes since v1.13. CoreDNS is a DNS server that links plugins to provide customized DNS service.

Due to rapid changes in the CoreDNS project, there have been many plugins that have been deprecated, removed or added. Plugins such as the proxy plugin has been deprecated and removed, while plugins such as the ready plugin have been introduced–plugins providing vital Kubernetes functionality. It is therefore important that these changes are recognized and implemented while upgrading your CoreDNS version.

The Go library for CoreDNS migration has been created for this specific purpose: to help users handle migrations of CoreDNS Corefiles to be compatible with new versions of CoreDNS. This library is mainly written with Kubernetes in mind, since the library currently only supports the plugins which are part of the default Kubernetes deployment.

CoreDNS migration support in Kubeadm

The Corefile migration library helps you to seamlessly migrate your Corefile to be compatible with the latest version of CoreDNS. One of the common situations in which this library has been used is in Kubeadm, which is an installation tool for Kubernetes clusters. The CoreDNS migration functionality is integrated with Kubeadm and has been introduced for Kubernetes v1.16.

Use Case:

If I want to upgrade my Kubernetes cluster from v1.15.3 to v1.16.0 using kubeadm, the Corefile will be upgraded automatically for me from CoreDNS v1.3.1 (in Kubernetes 1.15.3) to be compatible with CoreDNS v1.6.2 (in Kubernetes 1.16.0).

My Corefile for CoreDNS v1.3.1 in Kubernetes 1.15.3 looks like:

apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns
  namespace: kube-system
data:
  Corefile: |
    .:53 {
        errors
        health
        kubernetes cluster.local in-addr.arpa ip6.arpa {
          pods insecure
          upstream
          fallthrough in-addr.arpa ip6.arpa
        }
        prometheus :9153
        proxy . /etc/resolv.conf
        cache 30
        loop
        reload
        loadbalance
    }

Looking at the plugins, I can see that:

The upstream option in the Kubernetes is not required anymore and can be removed.
The proxy plugin is deprecated and removed, replaced by the forward plugin.
The ready plugin, which is required for reporting readiness, is missing.

So, when I upgrade my Kubernetes version to 1.16.0, my Corefile configuration will be automatically migrated. Also note that the Corefile that was present in the previous version will be backed up and saved as Corefile-backup in the ConfigMap.

The final ConfigMap looks like this:

apiVersion: v1
kind: ConfigMap
metadata:
name: coredns
namespace: kube-system
data:
Corefile: |
.:53 {
    errors
    health
    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
    ready
}
Corefile-backup: |
.:53 {
    errors
    health
    kubernetes cluster.local in-addr.arpa ip6.arpa {
      pods insecure
      upstream
      fallthrough in-addr.arpa ip6.arpa
    }
    prometheus :9153
    forward . /etc/resolv.conf
    cache 30
    loop
    reload
    loadbalance
 }

Corefile-tool

If you want to manually upgrade the CoreDNS Corefile configuration, you can also make use of the Corefile-tool command-line tool, which uses the CoreDNS Corefile migration library.

Usage of the Corefile-tool is as follows:

corefile-tool default --corefile <path> [--k8sversion <k8s-ver>]
corefile-tool deprecated --from <coredns-ver> --to <coredns-ver> --corefile <path>
corefile-tool migrate --from <coredns-ver> --to <coredns-ver> --corefile <path> [--deprecations <true|false>]
corefile-tool downgrade --from <coredns-ver> --to <coredns-ver> --corefile <path>
corefile-tool released --dockerImageId <id>
corefile-tool unsupported --from <coredns-ver> --to <coredns-ver> --corefile <path>
corefile-tool validversions

Use-case

I have a Kubernetes Cluster running CoreDNS v1.1.3 and I want to upgrade CoreDNS to version 1.6.2.
First, I want to check if the versions I’m upgrading to and currently installed are supported by the tool:

$ corefile-tool validversions
    The following are valid CoreDNS versions:
    1.1.3, 1.1.4, 1.2.0, 1.2.1, 1.2.2, 1.2.3, 1.2.4, 1.2.5, 1.2.6, 1.3.0, 1.3.1, 1.4.0, 1.5.0, 1.5.1, 1.5.2, 1.6.0, 1.6.1, 1.6.2

Now, my Corefile config currently looks like:

.:53 {
    errors
    health
    kubernetes cluster.local in-addr.arpa ip6.arpa {
        pods insecure
        resyncperiod 5s
        upstream
        fallthrough in-addr.arpa ip6.arpa
    }
    rewrite name suffix .schmoogle.com. .google.com.
    prometheus :9153
    proxy . /etc/resolv.conf
    cache 30
}

If I want to know which plugins have been deprecated, I can use the deprecated command which shows me a list of plugins and options that have been deprecated or removed:

$ corefile-tool deprecated --from 1.1.3 --to 1.6.2 --corefile cm.yaml 
    Plugin "loop" is added as a default in 1.2.1.
    Option "upstream" in plugin "kubernetes" is deprecated in 1.4.0.
    Plugin "proxy" is deprecated in 1.4.0. It is replaced by "forward".
    Option "resyncperiod" in plugin "kubernetes" is deprecated in 1.5.0.
    Option "upstream" in plugin "kubernetes" is ignored in 1.5.0.
    Plugin "proxy" is removed in 1.5.0. It is replaced by "forward".
    Plugin "ready" is added as a default in 1.5.0.
    Option "resyncperiod" in plugin "kubernetes" is deprecated in 1.5.1.
    Option "upstream" in plugin "kubernetes" is ignored in 1.5.1.
    Option "resyncperiod" in plugin "kubernetes" is deprecated in 1.5.2.
    Option "upstream" in plugin "kubernetes" is ignored in 1.5.2.
    Option "resyncperiod" in plugin "kubernetes" is removed in 1.6.0.
    Option "upstream" in plugin "kubernetes" is ignored in 1.6.0.
    Option "upstream" in plugin "kubernetes" is ignored in 1.6.1.
    Option "upstream" in plugin "kubernetes" is ignored in 1.6.2.

Since I have the knowledge of what will be added and removed from the previous command, I can now go ahead and migrate my Corefile.

$ corefile-tool migrate --from 1.1.3 --to 1.6.2 --corefile cm.yaml 

    .:53 {
        errors
        health
        kubernetes cluster.local in-addr.arpa ip6.arpa {
            pods insecure
            fallthrough in-addr.arpa ip6.arpa
        }
        rewrite name suffix .schmoogle.com. .google.com.
        prometheus :9153
        forward . /etc/resolv.conf
        cache 30
        loop
        ready
    }

The migration was successful and I can add the generated Corefile from the tool to update my ConfigMap.

More

You can find more information about the Corefile Migration Library and Corefile-tool from:

Sandeep Rajan

Software Engineer at Infoblox