docs: update network dns setup (#117)

* docs: update network dns setup * docs: improve readme --------- Co-authored-by: Evelyn Gurschler <[email protected]>
eclipse-tractusx · Aug 12, 2024 · f7bacb2 · f7bacb2
1 parent ab2f3e0
commit f7bacb2
Showing 1 changed file with 123 additions and 31 deletions.
diff --git a/charts/umbrella/README.md b/charts/umbrella/README.md
@@ -1,18 +1,20 @@
 - [Umbrella Chart](#umbrella-chart)
   - [Usage](#usage)
     - [Cluster setup](#cluster-setup)
-      - [Linux \& Mac](#linux--mac)
-      - [Windows](#windows)
+      - [Linux \& Mac](#cluster-setup-on-linux--mac)
+      - [Windows](#cluster-setup-on-windows)
     - [Network setup](#network-setup)
-      - [Linux \& Mac](#linux--mac-1)
-      - [Windows](#windows-1)
+      - [Linux](#network-setup-on-linux)
+      - [Mac](#network-setup-on-mac)
+      - [Windows](#network-setup-on-windows)
+      - [Hosts](#hosts)
     - [Install](#install)
       - [Use released chart](#use-released-chart)
-        - [Option 1](#option-1)
-        - [Option 2](#option-2)
+        - [Install selected components](#option-1)
+        - [Install predefined subsets of components](#option-2)
       - [Use local repository](#use-local-repository)
-        - [Option 1](#option-1-1)
-        - [Option 2](#option-2-1)
+        - [Install selected components](#option-1-1)
+        - [Install predefined subsets of components](#option-2-1)
     - [E2E Adopter Journeys](#e2e-adopter-journeys)
       - [Data exchange](#data-exchange)
       - [Get to know the Portal](#get-to-know-the-portal)
@@ -58,13 +60,13 @@ Assuming you have a running cluster and your `kubectl` context is set to that cl
 > minikube dashboard
 > ```
 
-#### Linux & Mac
+#### Cluster setup on Linux & Mac
 
 ```bash
 minikube start --cpus=4 --memory 6gb
 ```
 
-#### Windows
+#### Cluster setup on Windows
 
 For DNS resolution to work you need to either use `--driver=hyperv` option which requires administrator privileges:
 
@@ -99,15 +101,88 @@ minikube addons enable ingress-dns
 
 And execute installation step [3 Add the `minikube ip` as a DNS server](https://minikube.sigs.k8s.io/docs/handbook/addons/ingress-dns) for your OS:
 
-To find out the IP address of your Minikube execute:
+#### Network setup on Linux
 
-```bash
-minikube ip
+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.
+
+```
+search test
+nameserver 192.168.99.169
+timeout 5
 ```
 
-In the following steps, replace `192.168.49.2` with your `minikube ip` if it differs.
+Replace `192.168.99.169 with` the output of `minikube ip`.
+
+If your Linux OS uses `systemctl`, run the following commands.
+
+```shell
+sudo resolvconf -u
+systemctl disable --now resolvconf.service
+```
+
+See https://linux.die.net/man/5/resolver
+
+##### 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 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 domain names ending with `.test`:
+
+```shell
+sudo mkdir -p /etc/NetworkManager/dnsmasq.d/
+echo "server=/test/$(minikube ip)" | sudo tee /etc/NetworkManager/dnsmasq.d/minikube.conf
+```
+
+Restart Network Manager:
+
+```shell
+systemctl restart NetworkManager.service
+```
+
+Ensure your `/etc/resolv.conf` contains only single nameserver:
+
+```shell
+cat /etc/resolv.conf | grep nameserver
+nameserver 127.0.0.1
+```
+
+##### Linux OS with systemd-resolved
+
+Run the following commands to add the minikube DNS for `.test` domains:
+
+```shell
+sudo mkdir -p /etc/systemd/resolved.conf.d
+sudo tee /etc/systemd/resolved.conf.d/minikube.conf << EOF
+[Resolve]
+DNS=$(minikube ip)
+Domains=~test
+EOF
+sudo systemctl restart systemd-resolved
+```
+
+If you still face DNS issues, add [the hosts](#hosts) to your `/etc/hosts` file.
+
+#### Network setup on Mac
 
-#### Linux & Mac
 Create a file in /etc/resolver/minikube-test with the following contents.
 
 ```
@@ -117,32 +192,41 @@ search_order 1
 timeout 5
 ```
 
-If you still face DNS issues, add the hosts to your /etc/hosts file:
+Replace `192.168.49.2` with your `minikube ip` if it differs.
 
+To find out the IP address of your Minikube execute:
+
+```bash
+minikube ip
 ```
-192.168.49.2    centralidp.tx.test
-192.168.49.2    sharedidp.tx.test
-192.168.49.2    portal.tx.test
-192.168.49.2    portal-backend.tx.test
-192.168.49.2    managed-identity-wallets.tx.test
-192.168.49.2    semantics.tx.test
-192.168.49.2    sdfactory.tx.test
-192.168.49.2    dataconsumer-1-dataplane.tx.test
-192.168.49.2    dataconsumer-1-controlplane.tx.test
-192.168.49.2    dataprovider-dataplane.tx.test
-192.168.49.2    dataconsumer-2-dataplane.tx.test
-192.168.49.2    dataconsumer-2-controlplane.tx.test
-```
+
+If you still face DNS issues, add [the hosts](#hosts) to your `/etc/hosts` file.
 
 **Additional network setup for Mac**
 
 Install and start [Docker Mac Net Connect](https://github.com/chipmk/docker-mac-net-connect#installation).
 
 We also recommend to execute the usage example after install to check proper setup.
 
-#### Windows
+#### Network setup on Windows
+
+Open `Powershell` as Administrator and execute the following.
+
+```shell
+Add-DnsClientNrptRule -Namespace ".test" -NameServers "$(minikube ip)"
+```
 
-For Windows edit the hosts file under `C:\Windows\System32\drivers\etc\hosts`:
+The following will remove any matching rules before creating a new one. This is useful for updating the minikube ip.
+
+```shell
+Get-DnsClientNrptRule | Where-Object {$_.Namespace -eq '.test'} | Remove-DnsClientNrptRule -Force; Add-DnsClientNrptRule -Namespace ".test" -NameServers "$(minikube ip)"
+```
+
+If you still face DNS issues, add [the hosts](#hosts) to your `C:\Windows\System32\drivers\etc\hosts` file.
+
+#### Hosts
+
+Collection of hosts to be added to the `/etc/hosts` (Linux and Mac) or the `C:\Windows\System32\drivers\etc\hosts` (Windows) file, in case [Network setup#Linux](#network-setup-on-linux), [Network setup#Mac](#network-setup-on-mac) or [Network setup#Windows](#network-setup-on-windows) doesn't work:
 
 ```
 192.168.49.2    centralidp.tx.test
@@ -159,6 +243,14 @@ For Windows edit the hosts file under `C:\Windows\System32\drivers\etc\hosts`:
 192.168.49.2    dataconsumer-2-controlplane.tx.test
 ```
 
+Replace `192.168.49.2` with your `minikube ip` if it differs.
+
+To find out the IP address of your Minikube execute:
+
+```bash
+minikube ip
+```
+
 ### Install
 
 Select a subset of components which are designed to integrate with each other for a certain functional use case and enable those at install.