Skip to main content

DNS providers

Available DNS Providers​

RKE provides the following DNS providers that can be deployed as add-ons:

RKE versionKubernetes versionDefault DNS provider
v0.2.5 and higherv1.14.0 and higherCoreDNS
v0.2.5 and higherv1.13.x and lowerkube-dns
v0.2.4 and loweranykube-dns

CoreDNS was made the default in RKE v0.2.5 when using Kubernetes 1.14 and higher. If you are using an RKE version lower than v0.2.5, kube-dns will be deployed by default.

note

If you switch from one DNS provider to another, the existing DNS provider will be removed before the new one is deployed.

Disabling Deployment of a DNS Provider​

Available as of v0.2.0

You can disable the default DNS provider by specifying none to the dns provider directive in the cluster configuration. Be aware that this will prevent your pods from doing name resolution in your cluster.

dns:
  provider: none

CoreDNS​

Available as of v0.2.5

CoreDNS can only be used on Kubernetes v1.12.0 and higher.

RKE will deploy CoreDNS as a Deployment with the default replica count of 1. The pod consists of 1 container: coredns. RKE will also deploy coredns-autoscaler as a Deployment, which will scale the coredns Deployment by using the number of cores and nodes. Please see Linear Mode for more information about this logic.

The images used for CoreDNS are under the system_images directive. For each Kubernetes version, there are default images associated with CoreDNS, but these can be overridden by changing the image tag in system_images.

Scheduling CoreDNS​

If you only want the CoreDNS pod to be deployed on specific nodes, you can set a node_selector in the dns section. The label in the node_selector would need to match the label on the nodes for the CoreDNS pod to be deployed.

nodes:
- address: 1.1.1.1
  role: [controlplane,worker,etcd]
  user: root
  labels:
    app: dns

dns:
  provider: coredns
  node_selector:
    app: dns

CoreDNS Upstream nameservers​

By default, CoreDNS will use the host configured nameservers (usually residing at /etc/resolv.conf) to resolve external queries. If you want to configure specific upstream nameservers to be used by CoreDNS, you can use the upstreamnameservers directive.

When you set upstreamnameservers, the provider also needs to be set.

dns:
  provider: coredns
  upstreamnameservers:
  - 1.1.1.1
  - 8.8.4.4

CoreDNS Priority Class Name​

Available as of RKE v1.2.6+

The pod priority is set by configuring a priority class name under options:

dns:
    options:
      coredns_autoscaler_priority_class_name: system-cluster-critical
      coredns_priority_class_name: system-cluster-critical
    provider: coredns

CoreDNS Tolerations​

Available as of v1.2.4

The configured tolerations apply to the coredns and the coredns-autoscaler Deployment.

dns:
  provider: coredns
  tolerations:
  - key: "node.kubernetes.io/unreachable"
    operator: "Exists"
    effect: "NoExecute"
    tolerationseconds: 300
  - key: "node.kubernetes.io/not-ready"
    operator: "Exists"
    effect: "NoExecute"
    tolerationseconds: 300

To check for applied tolerations on the coredns and coredns-autoscaler Deployment, use the following commands:

kubectl -n kube-system get deploy coredns -o jsonpath='{.spec.template.spec.tolerations}'
kubectl -n kube-system get deploy coredns-autoscaler -o jsonpath='{.spec.template.spec.tolerations}'

kube-dns​

RKE will deploy kube-dns as a Deployment with the default replica count of 1. The pod consists of 3 containers: kubedns, dnsmasq and sidecar. RKE will also deploy kube-dns-autoscaler as a Deployment, which will scale the kube-dns Deployment by using the number of cores and nodes. Please see Linear Mode for more information about this logic.

The images used for kube-dns are under the system_images directive. For each Kubernetes version, there are default images associated with kube-dns, but these can be overridden by changing the image tag in system_images.

Scheduling kube-dns​

Available as of v0.2.0

If you only want the kube-dns pod to be deployed on specific nodes, you can set a node_selector in the dns section. The label in the node_selector would need to match the label on the nodes for the kube-dns pod to be deployed.

nodes:
- address: 1.1.1.1
  role: [controlplane,worker,etcd]
  user: root
  labels:
    app: dns

dns:
  provider: kube-dns
  node_selector:
    app: dns

kube-dns Upstream nameservers​

Available as of v0.2.0

By default, kube-dns will use the host configured nameservers (usually residing at /etc/resolv.conf) to resolve external queries. If you want to configure specific upstream nameservers to be used by kube-dns, you can use the upstreamnameservers directive.

When you set upstreamnameservers, the provider also needs to be set.

dns:
  provider: kube-dns
  upstreamnameservers:
  - 1.1.1.1
  - 8.8.4.4

kube-dns Priority Class Name​

Available as of RKE v1.2.6+

The pod priority is set by configuring a priority class name under options:

dns:
    options:
      kube_dns_autoscaler_priority_class_name: system-cluster-critical
      kube_dns_priority_class_name: system-cluster-critical
    provider: kube-dns

kube-dns Tolerations​

Available as of v1.2.4

The configured tolerations apply to the kube-dns and the kube-dns-autoscaler Deployment.

dns:
  provider: kube-dns
  tolerations:
  - key: "node.kubernetes.io/unreachable"
    operator: "Exists"
    effect: "NoExecute"
    tolerationseconds: 300
  - key: "node.kubernetes.io/not-ready"
    operator: "Exists"
    effect: "NoExecute"
    tolerationseconds: 300

To check for applied tolerations on the coredns and coredns-autoscaler Deployment, use the following commands:

kubectl get deploy kube-dns -n kube-system -o jsonpath='{.spec.template.spec.tolerations}'
kubectl get deploy kube-dns-autoscaler -n kube-system -o jsonpath='{.spec.template.spec.tolerations}'

NodeLocal DNS​

Available as of v1.1.0

The option to enable NodeLocal DNS is available for:
  • Kubernetes v1.15.11 and up
  • Kubernetes v1.16.8 and up
  • Kubernetes v1.17.4 and up

NodeLocal DNS is an additional component that can be deployed on each node to improve DNS performance. It is not a replacement for the provider parameter, you will still need to have one of the available DNS providers configured. See Using NodeLocal DNSCache in Kubernetes clusters for more information on how NodeLocal DNS works.

Enable NodeLocal DNS by configuring an IP address.

Configuring NodeLocal DNS​

The ip_address parameter is used to configure what link-local IP address will be configured one each host to listen on, make sure this IP address is not already configured on the host.

dns:
  provider: coredns
  nodelocal:
    ip_address: "169.254.20.10"
note

When enabling NodeLocal DNS on an existing cluster, pods that are currently running will not be modified, the updated /etc/resolv.conf configuration will take effect only for pods started after enabling NodeLocal DNS.

NodeLocal Priority Class Name​

Available as of RKE v1.2.6+

The pod priority is set by configuring a priority class name under options:

dns:
    options:
      nodelocal_autoscaler_priority_class_name: system-cluster-critical
      nodelocal_priority_class_name: system-cluster-critical
    provider: coredns # a DNS provider must be configured

Removing NodeLocal DNS​

By removing the ip_address value, NodeLocal DNS will be removed from the cluster.

warning

When removing NodeLocal DNS, a disruption to DNS can be expected. The updated /etc/resolv.conf configuration will take effect only for pods that are started after removing NodeLocal DNS. In general pods using the default dnsPolicy: ClusterFirst will need to be re-deployed.