diff --git a/docs/dns-stack.md b/docs/dns-stack.md
index e56ee2fdad0716e18fff316273b259ea42c65294..ae631a44bedeefb6ee2cf6ac1d0393721f4725e4 100644
--- a/docs/dns-stack.md
+++ b/docs/dns-stack.md
@@ -4,18 +4,44 @@ K8s DNS stack by Kargo
Here is an approximate picture of how DNS things working and
being configured by Kargo ansible playbooks:
-
+
Note that an additional dnsmasq daemon set is installed by Kargo
-by default. Kubelet will configure DNS base of all pods to use that
-dnsmasq cluster IP. You can disable it with the ``skip_dnsmasq``
-var. This may be the case, if you're fine with Linux limit of max 3
-nameservers in the ``/etc/resolv.conf``. When skipped and bypassed
-directly to Kubedns's dnsmasq cluster IP, it greatly simplifies things
-by the price of limited nameservers though.
+by default. Kubelet will configure DNS base of all pods to use the
+given dnsmasq cluster IP, which is defined via the ``dns_server`` var.
+The dnsmasq forwards requests for a given cluster ``dns_domain`` to
+Kubedns's SkyDns service. The SkyDns server is configured to be an
+authoritative DNS server for the given cluser domain (and its subdomains
+up to ``ndots:5`` depth). Note: you should scale its replication controller
+up, if SkyDns chokes. These two layered DNS forwarders provide HA for the
+DNS cluster IP endpoint, which is a critical moving part for Kubernetes apps.
-Nameservers are configured in the hosts' ``/etc/resolv.conf`` files
-from the ``nameservers`` (see also ``searchdomains``) vars. While the
-``upstream_dns_servers`` will define additional DNS servers for the
-dnsmasq daemon set running on all hosts (unless bypassed with
-``skip_dnsmasq``).
+Nameservers are as well configured in the hosts' ``/etc/resolv.conf`` files,
+as the given DNS cluster IP merged with ``nameservers`` values. While the
+DNS cluster IP merged with the ``upstream_dns_servers`` defines additional
+nameservers for the aforementioned nsmasq daemon set running on all hosts.
+This mitigates existing Linux limitation of max 3 nameservers in the
+``/etc/resolv.conf`` and also brings an additional caching layer for the
+clustered DNS services.
+
+You can skip the dnsmasq daemon set install steps by setting the
+``skip_dnsmasq: true``. This may be the case, if you're fine with
+the nameservers limitation. Sadly, there is no way to work around the
+search domain limitations of a 256 chars and 6 domains. Thus, you can
+use the ``searchdomains`` var to define no more than a three custom domains.
+Remaining three slots are reserved for K8s cluster default subdomains.
+
+When dnsmasq skipped, Kargo redefines the DNS cluster IP to point directly
+to SkyDns cluster IP ``skydns_server`` and configures Kubelet's
+``--dns_cluster`` to use that IP as well. While this greatly simplifies
+things, it comes by the price of limited nameservers though. As you know now,
+the DNS cluster IP takes a slot in the ``/etc/resolv.conf``, thus you can
+specify no more than a two nameservers for infra and/or external use.
+Those may be specified either in ``nameservers`` or ``upstream_dns_servers``
+and will be merged together with the ``skydns_server`` IP into the hots'
+``/etc/resolv.conf``.
+
+Kargo has yet ways to configure Kubedns addon to forward requests SkyDns can
+not answer with authority to arbitrary recursive resolvers. This task is left
+for future. See [official SkyDns docs](https://github.com/skynetservices/skydns)
+for details.
diff --git a/docs/figures/dns.jpeg b/docs/figures/dns.jpeg
new file mode 100644
index 0000000000000000000000000000000000000000..f61f2f1dc50ae838a559ecf160925ec89c4ad547
Binary files /dev/null and b/docs/figures/dns.jpeg differ
diff --git a/docs/figures/dns.png b/docs/figures/dns.png
deleted file mode 100644
index dbdb0c07125fa05b33cc6c2db1fc98d6739fe48a..0000000000000000000000000000000000000000
Binary files a/docs/figures/dns.png and /dev/null differ
diff --git a/roles/dnsmasq/tasks/resolvconf.yml b/roles/dnsmasq/tasks/resolvconf.yml
index 22c135262293414a05abcd19b254dafa1e076d13..db6f5ec026a0e3d8637ee2dd1e45128a8134b922 100644
--- a/roles/dnsmasq/tasks/resolvconf.yml
+++ b/roles/dnsmasq/tasks/resolvconf.yml
@@ -22,7 +22,7 @@
- name: generate nameservers to resolvconf
set_fact:
nameserverentries:
- "{{ nameservers|default([]) + dnsmasq_server|default([]) }}"
+ "{{ dnsmasq_server|default([]) + nameservers|default([]) }}"
- name: Remove search and nameserver options from resolvconf head
lineinfile:
@@ -37,7 +37,7 @@
when: resolvconf.rc == 0
notify: Dnsmasq | update resolvconf
-- name: Add search resolv.conf
+- name: Add search domains to resolv.conf
lineinfile:
line: "search {{searchentries}}"
dest: "{{resolvconffile}}"
@@ -47,7 +47,7 @@
follow: yes
notify: Dnsmasq | update resolvconf
-- name: Add local dnsmasq to resolv.conf
+- name: Add nameservers to resolv.conf
blockinfile:
dest: "{{resolvconffile}}"
block: |-