From f72619a476a802bfd1827e0b75623bcc42cb0e14 Mon Sep 17 00:00:00 2001
From: Gabriel Pelouze <gabriel@pelouze.net>
Date: Wed, 8 May 2024 13:17:28 +0200
Subject: [PATCH] improve linux section of ingress-dns documentation

---
 .../en/docs/handbook/addons/ingress-dns.md    | 31 +++++++++++++------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/site/content/en/docs/handbook/addons/ingress-dns.md b/site/content/en/docs/handbook/addons/ingress-dns.md
index 909c295cbe32..cfe05c9ce798 100644
--- a/site/content/en/docs/handbook/addons/ingress-dns.md
+++ b/site/content/en/docs/handbook/addons/ingress-dns.md
@@ -61,6 +61,14 @@ minikube addons enable ingress-dns
 {{% tabs %}}
 {{% linuxtab %}}
 
+On Linux, you should identify your domain name resolver configuration, and update its configuration accordingly. To that end, look at the first lines of `/etc/resolv.conf`:
+
+- if it mentions `resolvconf`, resolution is likely handled by **resolvconf**,
+- if it is `# Generated by NetworkManager`, resolution is handled by **NetworkManager**,
+- if it similar to `# This is /run/systemd/resolve/stub-resolv.conf managed by man:systemd-resolved(8)`, resolution is handled by **systemd-resolved**.
+
+Start minikube, and apply the configuration below matching your system configuration.
+
 ## Linux OS with resolvconf
 
 Update the file `/etc/resolvconf/resolv.conf.d/base` to have the following contents.
@@ -71,7 +79,7 @@ nameserver 192.168.99.169
 timeout 5
 ```
 
-Replace `192.168.99.169` with your `minikube ip`.
+Replace `192.168.99.169` with the output of `minikube ip`.
 
 If your Linux OS uses `systemctl`, run the following commands.
 
@@ -88,30 +96,35 @@ If your Linux OS does not use `systemctl`, run the following commands.
 
 See https://linux.die.net/man/5/resolver
 
-## Linux OS with Network Manager
 
-Network Manager can run integrated caching DNS server - `dnsmasq` plugin and can be configured to use separate nameservers per domain. 
+## Linux OS with NetworkManager
+
+NetworkManager can run integrated caching DNS server - `dnsmasq` plugin and can be configured to use separate nameservers per domain. 
 
-Edit /etc/NetworkManager/NetworkManager.conf and set `dns=dnsmasq`
+Edit `/etc/NetworkManager/NetworkManager.conf` and enable `dns=dnsmasq` by adding:
 
 ```
 [main]
 dns=dnsmasq
 ```
+
 Also see `dns=` in [NetworkManager.conf](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html).
 
-Configure dnsmasq to handle .test domain 
+Configure dnsmasq to handle domain names ending with `.test`:
 
 ```bash
-sudo mkdir /etc/NetworkManager/dnsmasq.d/
+sudo mkdir -p /etc/NetworkManager/dnsmasq.d/
 echo "server=/test/$(minikube ip)" | sudo tee /etc/NetworkManager/dnsmasq.d/minikube.conf
 ```
 
-Restart Network Manager
+Restart Network Manager:
+
 ```
 systemctl restart NetworkManager.service
 ```
-Ensure your /etc/resolv.conf  contains only single nameserver
+
+Ensure your `/etc/resolv.conf` contains only single nameserver:
+
 ```bash
 cat /etc/resolv.conf | grep nameserver
 nameserver 127.0.0.1
@@ -119,8 +132,6 @@ nameserver 127.0.0.1
 
 ## Linux OS with systemd-resolved
 
-Your Linux OS likely uses `systemd-resolved` if the first line of `/etc/resolv.conf` contains `This is /run/systemd/resolve/stub-resolv.conf managed by man:systemd-resolved(8)`.
-
 Run the following commands to add the minikube DNS for `.test` domains:
 
 ```bash