XTesting/kubespray/docs/dns-stack.md

   1 # K8s DNS stack by Kubespray
   2
   3 For K8s cluster nodes, Kubespray configures a [Kubernetes DNS](https://kubernetes.io/docs/admin/dns/)
   4 [cluster add-on](https://releases.k8s.io/master/cluster/addons/README.md)
   5 to serve as an authoritative DNS server for a given ``dns_domain`` and its
   6 ``svc, default.svc`` default subdomains (a total of ``ndots: 5`` max levels).
   7
   8 Other nodes in the inventory, like external storage nodes or a separate etcd cluster
   9 node group, considered non-cluster and left up to the user to configure DNS resolve.
  10
  11 ## DNS variables
  12
  13 There are several global variables which can be used to modify DNS settings:
  14
  15 ### ndots
  16
  17 ndots value to be used in ``/etc/resolv.conf``
  18
  19 It is important to note that multiple search domains combined with high ``ndots``
  20 values lead to poor performance of DNS stack, so please choose it wisely.
  21
  22 ### searchdomains
  23
  24 Custom search domains to be added in addition to the cluster search domains (``default.svc.{{ dns_domain }}, svc.{{ dns_domain }}``).
  25
  26 Most Linux systems limit the total number of search domains to 6 and the total length of all search domains
  27 to 256 characters. Depending on the length of ``dns_domain``, you're limited to less than the total limit.
  28
  29 Please note that ``resolvconf_mode: docker_dns`` will automatically add your systems search domains as
  30 additional search domains. Please take this into the accounts for the limits.
  31
  32 ### nameservers
  33
  34 This variable is only used by ``resolvconf_mode: host_resolvconf``. These nameservers are added to the hosts
  35 ``/etc/resolv.conf`` *after* ``upstream_dns_servers`` and thus serve as backup nameservers. If this variable
  36 is not set, a default resolver is chosen (depending on cloud provider or 8.8.8.8 when no cloud provider is specified).
  37
  38 ### upstream_dns_servers
  39
  40 DNS servers to be added *after* the cluster DNS. Used by all ``resolvconf_mode`` modes. These serve as backup
  41 DNS servers in early cluster deployment when no cluster DNS is available yet.
  42
  43 ### coredns_external_zones
  44
  45 Array of optional external zones to coredns forward queries to. It's  injected into
  46 `coredns`' config file before default kubernetes zone. Use it as an optimization for well-known zones and/or internal-only
  47 domains, i.e. VPN for internal networks (default is unset)
  48
  49 Example:
  50
  51 ```yaml
  52 coredns_external_zones:
  53 - zones:
  54   - example.com
  55   - example.io:1053
  56   nameservers:
  57   - 1.1.1.1
  58   - 2.2.2.2
  59   cache: 5
  60 - zones:
  61   - https://mycompany.local:4453
  62   nameservers:
  63   - 192.168.0.53
  64   cache: 0
  65 ```
  66
  67 or as INI
  68
  69 ```ini
  70 coredns_external_zones='[{"cache": 30,"zones":["example.com","example.io:453"],"nameservers":["1.1.1.1","2.2.2.2"]}]'
  71 ```
  72
  73 ### dns_etchosts (coredns)
  74
  75 Optional hosts file content to coredns use as /etc/hosts file. This will also be used by nodelocaldns, if enabled.
  76
  77 Example:
  78
  79 ```yaml
  80 dns_etchosts: |
  81   192.168.0.100 api.example.com
  82   192.168.0.200 ingress.example.com
  83 ```
  84
  85 ### enable_coredns_reverse_dns_lookups
  86
  87 Whether reverse DNS lookups are enabled in the coredns config. Defaults to `true`.
  88
  89 ### CoreDNS default zone cache plugin
  90
  91 If you wish to configure the caching behaviour of CoreDNS on the default zone, you can do so using the `coredns_default_zone_cache_block` string block.
  92
  93 An example value (more information on the [plugin's documentation](https://coredns.io/plugins/cache/)) to:
  94
  95 * raise the max cache TTL to 3600 seconds
  96 * raise the max amount of success responses to cache to 3000
  97 * disable caching of denial responses altogether
  98 * enable pre-fetching of lookups with at least 10 lookups per minute before they expire
  99
 100 Would be as follows:
 101
 102 ```yaml
 103 coredns_default_zone_cache_block: |
 104   cache 3600 {
 105     success 3000
 106     denial 0
 107     prefetch 10 1m
 108   }
 109 ```
 110
 111 ## DNS modes supported by Kubespray
 112
 113 You can modify how Kubespray sets up DNS for your cluster with the variables ``dns_mode`` and ``resolvconf_mode``.
 114
 115 ### dns_mode
 116
 117 ``dns_mode`` configures how Kubespray will setup cluster DNS. There are four modes available:
 118
 119 #### dns_mode: coredns (default)
 120
 121 This installs CoreDNS as the default cluster DNS for all queries.
 122
 123 #### dns_mode: coredns_dual
 124
 125 This installs CoreDNS as the default cluster DNS for all queries, plus a secondary CoreDNS stack.
 126
 127 #### dns_mode: manual
 128
 129 This does not install coredns, but allows you to specify
 130 `manual_dns_server`, which will be configured on nodes for handling Pod DNS.
 131 Use this method if you plan to install your own DNS server in the cluster after
 132 initial deployment.
 133
 134 #### dns_mode: none
 135
 136 This does not install any of DNS solution at all. This basically disables cluster DNS completely and
 137 leaves you with a non functional cluster.
 138
 139 ## resolvconf_mode
 140
 141 ``resolvconf_mode`` configures how Kubespray will setup DNS for ``hostNetwork: true`` PODs and non-k8s containers.
 142 There are three modes available:
 143
 144 ### resolvconf_mode: host_resolvconf (default)
 145
 146 This activates the classic Kubespray behavior that modifies the hosts ``/etc/resolv.conf`` file and dhclient
 147 configuration to point to the cluster dns server (either coredns or coredns_dual, depending on dns_mode).
 148
 149 As cluster DNS is not available on early deployment stage, this mode is split into 2 stages. In the first
 150 stage (``dns_early: true``), ``/etc/resolv.conf`` is configured to use the DNS servers found in ``upstream_dns_servers``
 151 and ``nameservers``. Later, ``/etc/resolv.conf`` is reconfigured to use the cluster DNS server first, leaving
 152 the other nameservers as backups.
 153
 154 Also note, existing records will be purged from the `/etc/resolv.conf`,
 155 including resolvconf's base/head/cloud-init config files and those that come from dhclient.
 156
 157 ### resolvconf_mode: docker_dns
 158
 159 This sets up the docker daemon with additional --dns/--dns-search/--dns-opt flags.
 160
 161 The following nameservers are added to the docker daemon (in the same order as listed here):
 162
 163 * cluster nameserver (depends on dns_mode)
 164 * content of optional upstream_dns_servers variable
 165 * host system nameservers (read from hosts /etc/resolv.conf)
 166
 167 The following search domains are added to the docker daemon (in the same order as listed here):
 168
 169 * cluster domains (``default.svc.{{ dns_domain }}``, ``svc.{{ dns_domain }}``)
 170 * content of optional searchdomains variable
 171 * host system search domains (read from hosts /etc/resolv.conf)
 172
 173 The following dns options are added to the docker daemon
 174
 175 * ndots:{{ ndots }}
 176 * timeout:2
 177 * attempts:2
 178
 179 These dns options can be overridden by setting a different list:
 180
 181 ```yaml
 182 docker_dns_options:
 183 - ndots:{{ ndots }}
 184 - timeout:2
 185 - attempts:2
 186 - rotate
 187 ```
 188
 189 For normal PODs, k8s will ignore these options and setup its own DNS settings for the PODs, taking
 190 the --cluster_dns (either coredns or coredns_dual, depending on dns_mode) kubelet option into account.
 191 For ``hostNetwork: true`` PODs however, k8s will let docker setup DNS settings. Docker containers which
 192 are not started/managed by k8s will also use these docker options.
 193
 194 The host system name servers are added to ensure name resolution is also working while cluster DNS is not
 195 running yet. This is especially important in early stages of cluster deployment. In this early stage,
 196 DNS queries to the cluster DNS will timeout after a few seconds, resulting in the system nameserver being
 197 used as a backup nameserver. After cluster DNS is running, all queries will be answered by the cluster DNS
 198 servers, which in turn will forward queries to the system nameserver if required.
 199
 200 ### resolvconf_mode: none
 201
 202 Does nothing regarding ``/etc/resolv.conf``. This leaves you with a cluster that works as expected in most cases.
 203 The only exception is that ``hostNetwork: true`` PODs and non-k8s managed containers will not be able to resolve
 204 cluster service names.
 205
 206 ## Nodelocal DNS cache
 207
 208 Setting ``enable_nodelocaldns`` to ``true`` will make pods reach out to the dns (core-dns) caching agent running on the same node, thereby avoiding iptables DNAT rules and connection tracking. The local caching agent will query core-dns (depending on what main DNS plugin is configured in your cluster) for cache misses of cluster hostnames(cluster.local suffix by default).
 209
 210 More information on the rationale behind this implementation can be found [here](https://github.com/kubernetes/enhancements/blob/master/keps/sig-network/0030-nodelocal-dns-cache.md).
 211
 212 **As per the 2.10 release, Nodelocal DNS cache is enabled by default.**
 213
 214 ### External zones
 215
 216 It's possible to extent the `nodelocaldns`' configuration by adding an array of external zones. For example:
 217
 218 ```yaml
 219 nodelocaldns_external_zones:
 220 - zones:
 221   - example.com
 222   - example.io:1053
 223   nameservers:
 224   - 1.1.1.1
 225   - 2.2.2.2
 226   cache: 5
 227 - zones:
 228   - https://mycompany.local:4453
 229   nameservers:
 230   - 192.168.0.53
 231 ```
 232
 233 ### dns_etchosts (nodelocaldns)
 234
 235 See [dns_etchosts](#dns_etchosts-coredns) above.
 236
 237 ### Nodelocal DNS HA
 238
 239 Under some circumstances the single POD nodelocaldns implementation may not be able to be replaced soon enough and a cluster upgrade or a nodelocaldns upgrade can cause DNS requests to time out for short intervals. If for any reason your applications cannot tollerate this behavior you can enable a redundant nodelocal DNS pod on each node:
 240
 241 ```yaml
 242 enable_nodelocaldns_secondary: true
 243 ```
 244
 245 **Note:** when the nodelocaldns secondary is enabled, the primary is instructed to no longer tear down the iptables rules it sets up to direct traffic to itself. In case both daemonsets have failing pods on the same node, this can cause a DNS blackout with traffic no longer being forwarded to the coredns central service as a fallback. Please ensure you account for this also if you decide to disable the nodelocaldns cache.
 246
 247 There is a time delta (in seconds) allowed for the secondary nodelocaldns to survive in case both primary and secondary daemonsets are updated at the same time. It is advised to tune this variable after you have performed some tests in your own environment.
 248
 249 ```yaml
 250 nodelocaldns_secondary_skew_seconds: 5
 251 ```
 252
 253 ## Limitations
 254
 255 * Kubespray has yet ways to configure Kubedns addon to forward requests SkyDns can
 256   not answer with authority to arbitrary recursive resolvers. This task is left
 257   for future. See [official SkyDns docs](https://github.com/skynetservices/skydns)
 258   for details.
 259
 260 * There is
 261   [no way to specify a custom value](https://github.com/kubernetes/kubernetes/issues/33554)
 262   for the SkyDNS ``ndots`` param.
 263
 264 * the ``searchdomains`` have a limitation of a 6 names and 256 chars
 265   length. Due to default ``svc, default.svc`` subdomains, the actual
 266   limits are a 4 names and 239 chars respectively.
 267
 268 * the ``nameservers`` have a limitation of a 3 servers, although there
 269   is a way to mitigate that with the ``upstream_dns_servers``,
 270   see below. Anyway, the ``nameservers`` can take no more than a two
 271   custom DNS servers because of one slot is reserved for a Kubernetes
 272   cluster needs.