dns-stack.md

K8s DNS stack by Kubespray

For K8s cluster nodes, Kubespray configures a Kubernetes DNS cluster add-on to serve as an authoritative DNS server for a given dns_domain and its svc, default.svc default subdomains (a total of ndots: 5 max levels).

Other nodes in the inventory, like external storage nodes or a separate etcd cluster node group, considered non-cluster and left up to the user to configure DNS resolve.

DNS variables

There are several global variables which can be used to modify DNS settings:

ndots

ndots value to be used in /etc/resolv.conf

It is important to note that multiple search domains combined with high ndots values lead to poor performance of DNS stack, so please choose it wisely.

dns_timeout

timeout value to be used in /etc/resolv.conf

dns_attempts

attempts value to be used in /etc/resolv.conf

searchdomains

Custom search domains to be added in addition to the cluster search domains (default.svc.{{ dns_domain }}, svc.{{ dns_domain }}).

Most Linux systems limit the total number of search domains to 6 and the total length of all search domains to 256 characters. Depending on the length of dns_domain, you're limited to less than the total limit.

remove_default_searchdomains: true will remove the default cluster search domains.

Please note that resolvconf_mode: docker_dns will automatically add your systems search domains as additional search domains. Please take this into the accounts for the limits.

nameservers

This variable is only used by resolvconf_mode: host_resolvconf. These nameservers are added to the hosts /etc/resolv.conf after upstream_dns_servers and thus serve as backup nameservers. If this variable is not set, a default resolver is chosen (depending on cloud provider or 8.8.8.8 when no cloud provider is specified).

upstream_dns_servers

DNS servers to be added after the cluster DNS. Used by all resolvconf_mode modes. These serve as backup DNS servers in early cluster deployment when no cluster DNS is available yet.

dns_upstream_forward_extra_opts

Whether or not upstream DNS servers come from upstream_dns_servers variable or /etc/resolv.conf, related forward block in coredns (and nodelocaldns) configuration can take options (see https://coredns.io/plugins/forward/ for details). These are configurable in inventory in as a dictionary in the dns_upstream_forward_extra_opts variable. By default, no other option than the ones hardcoded (see roles/kubernetes-apps/ansible/templates/coredns-config.yml.j2 and roles/kubernetes-apps/ansible/templates/nodelocaldns-config.yml.j2).

coredns_kubernetes_extra_opts

Custom options to be added to the kubernetes coredns plugin.

coredns_kubernetes_extra_domains

Extra domains to be forwarded to the kubernetes coredns plugin.

coredns_additional_configs

Extra configuration to be added to CoreDNS configuration

coredns_rewrite_block

Rewrite plugin block to perform internal message rewriting.

coredns_external_zones

Array of optional external zones to coredns forward queries to. It's injected into coredns' config file before default kubernetes zone. Use it as an optimization for well-known zones and/or internal-only domains, i.e. VPN for internal networks (default is unset)

Example:

coredns_external_zones:
- zones:
  - example.com
  - example.io:1053
  nameservers:
  - 1.1.1.1
  - 2.2.2.2
  cache: 5
- zones:
  - https://mycompany.local:4453
  nameservers:
  - 192.168.0.53
  cache: 0
- zones:
  - mydomain.tld
  nameservers:
  - 10.233.0.3
  cache: 5
  rewrite:
  - name stop website.tld website.namespace.svc.cluster.local

or as INI

coredns_external_zones='[{"cache": 30,"zones":["example.com","example.io:453"],"nameservers":["1.1.1.1","2.2.2.2"]}]'

dns_etchosts (coredns)

Optional hosts file content to coredns use as /etc/hosts file. This will also be used by nodelocaldns, if enabled.

Example: