Merge pull request #80756 from dfitzmau/OSDOCS-11753

OSDOCS-11753: Update the Networking DNS documentation with more accur…

Author: skopacz1

modules/virt-example-nmstate-IP-management.adoc

@@ -6,7 +6,7 @@
 [id="virt-example-nmstate-IP-management_{context}"]
 = Examples: IP management
 
-The following example configuration snippets demonstrate different methods of IP management.
+The following example configuration snippets show different methods of IP management.
 
 These examples use the `ethernet` interface type to simplify the example while showing the related context in the policy configuration. These IP management examples can be used with the other interface types.
 
@@ -109,8 +109,9 @@ For more information, see "Creating a manifest object that includes a customized
 
 The following example shows a default situation that stores DNS values globally:
 
-* Configure a static DNS without a network interface. Note that when updating the `/etc/resolv.conf` file on a host node, you do not need to specify an interface (IPv4 or IPv6) in the `NodeNetworkConfigurationPolicy` (NNCP) manifest.
+* Configure a static DNS without a network interface. Note that when updating the `/etc/resolv.conf` file on a host node, you do not need to specify an interface, IPv4 or IPv6, in the `NodeNetworkConfigurationPolicy` (NNCP) manifest.
 +
+.Example of a DNS configuration for a network interface that globally stores DNS values
 [source,yaml]
 ----
 apiVersion: nmstate.io/v1
@@ -134,81 +135,79 @@ spec:
 
 The following examples show situations that require configuring a network interface to store DNS values:
 
-* Configure a static DNS for a network interface with an automatic IP configuration. Note that for this configuration, you must set the `auto-dns` parameter to `false`, so that the Kubernetes NMState Operator can store custom DNS settings for the network interface.
+* If you want to rank a static DNS name server over a dynamic DNS name server, define the interface that runs either the Dynamic Host Configuration Protocol (DHCP) or the IPv6 Autoconfiguration (`autoconf`) mechanism in the network interface YAML configuration file.
 +
+.Example configuration that adds `192.0.2.1` to DNS name servers retrieved from the DHCPv4 network protocol
 [source,yaml]
 ----
+# ...
 dns-resolver:
   config:
-    search:
-    - example.com
-    - example.org
     server:
-    - 2001:db8:f::1
-    - 192.0.2.251
+    - 192.0.2.1
 interfaces:
   - name: eth1
     type: ethernet
     state: up
     ipv4:
       enabled: true
       dhcp: true
-      auto-dns: false
-    ipv6:
-      enabled: true
-      dhcp: true
-      autoconf: true
-      auto-dns: false
+      auto-dns: true
 # ...
 ----
 
-* Configure a static DNS for a network interface with a static IP configuration. Note that for this configuration, you must set the `dhcp` parameter to `false` and the `autoconf` parameter to `false`.
+* If you need to configure a network interface to store DNS values instead of adopting the default method, which uses the `nmstate` API to store DNS values globally, you can set static DNS values and static IP addresses in the network interface YAML file.
 +
+[IMPORTANT]
+====
+Storing DNS values at the network interface level might cause name resolution issues after you attach the interface to network components, such as an Open vSwitch (OVS) bridge, a Linux bridge, or a bond. 
+====
++
+.Example configuration that stores DNS values at the interface level
 [source,yaml]
 ----
+# ...
 dns-resolver:
   config:
-# ...
+    search:
+    - example.com
+    - example.org
     server:
-    - 2001:4860:4860::8844
-    - 192.0.2.251
+    - 2001:db8:1::d1
+    - 2001:db8:1::d2
+    - 192.0.2.1
 interfaces:
   - name: eth1
     type: ethernet
     state: up
     ipv4:
-      enabled: true
-      dhcp: false
       address:
       - ip: 192.0.2.251
         prefix-length: 24
-    ipv6:
-      enabled: true
       dhcp: false
-      autoconf: false
+      enabled: true
+    ipv6:
       address:
       - ip: 2001:db8:1::1
         prefix-length: 64
-routes:
-  config:
-  - destination: 0.0.0.0/0
-    next-hop-address: 192.0.2.1
-    next-hop-interface: eth1
-  - destination: ::/0
-    next-hop-address: 2001:db8:1::3
-    next-hop-interface: eth1
+      dhcp: false
+      enabled: true
+      autoconf: false
 # ...
 ----
 
-* Configure a static DNS name server to append to Dynamic Host Configuration Protocol (DHCP) and IPv6 Stateless Address AutoConfiguration (SLAAC) servers.
+* If you want to set static DNS search domains and dynamic DNS name servers for your network interface, define the dynamic interface that runs either the Dynamic Host Configuration Protocol (DHCP) or the IPv6 Autoconfiguration (`autoconf`) mechanism in the network interface YAML configuration file.
 +
+.Example configuration that sets `example.com` and `example.org` static DNS search domains along with dynamic DNS name server settings
 [source,yaml]
 ----
+# ...
 dns-resolver:
   config:
-# ...
-    server:
-    - 192.0.2.251
+    search:
+    - example.com
+    - example.org
+    server: []
 interfaces:
   - name: eth1
     type: ethernet