Merge pull request #93737 from dfitzmau/OCPBUGS-56684

OCPBUGS#56684: Documented the mac-address property for the virt-creat…

Author: dfitzmau

modules/virt-creating-infiniband-interface-on-nodes.adoc

@@ -48,12 +48,16 @@ spec:
         enabled: false
       name: ibp27s0
       state: up
-      type: infiniband <3>
+      identifier: mac-address <3>
+      mac-address: 20:00:55:04:01:FE:80:00:00:00:00:00:00:00:02:C9:02:00:23:13:92 <4>
+      type: infiniband <5>
 # ...
 ----
 <1> `datagram` is the default mode for an IPoIB interface, and this mode improves optimizes performance and latency. `connected` mode is a supported mode but consider only using this mode when you need to adjust the maximum transmission unit (MTU) value to improve node connectivity with surrounding network devices.  
 <2> Supports a string or an integer value. The parameter defines the protection key, or _P-key_, for the interface for the purposes of authentication and encrypted communications with a third-party vendor, such as NVIDIA. Values `None` and `0xffff` indicate the protection key for the base interface in an InfiniBand system.
-<3> Sets the type of interface to `infiniband `.
+<3> Supported values include `name`, the default value, and `mac-address`. The `name` value applies a configuration to an interface that holds a specified interface name. 
+<4> Holds the MAC address of an interface. For an IP-over-InfiniBand (IPoIB) interface, the address is a 20-byte string. 
+<5> Sets the type of interface to `infiniband`.
 
 . Apply the NNCP configuration to each node in your cluster by running the following command. The Kubernetes NMState Operator can then create an IPoIB interface on each node. 
 +

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

@@ -93,6 +93,34 @@ The following snippet configures an Ethernet interface that uses a dynamic IP ad
 # ...
 ----
 
+[id="virt-example-nmstate-IP-management-mac_{context}"]
+== Media Access Control (MAC) address
+
+You can use a MAC address to identify a network interface instead of using the name of the network interface. A network interface name can change for various reasons, such as an operating system configuration change. However, every network interface has a unique MAC address that does not change. This means that using a MAC address is a more permanent way to identify a specific network interface.
+
+Supported values for the `identifier` parameter include the default `name` value and the value `mac-address`. The `name` value applies a configuration to an interface that holds a specified interface name. 
+
+Using a `mac-address` value for the `identifier` parameter indicates that a MAC address is the identifier for the network interface. If you set the `identifier` value to `mac-address`, you must enter a specific MAC address in the following `mac-address` parameter field. 
+
+[NOTE]
+====
+You can still specify a value for the `name` parameter, but setting the `identifier: mac-address` value means that a MAC address is used as the primary identifier for a network interface. If you specify an incorrect MAC address, `nmstate` reports an invalid argument error. 
+====
+
+The following snippet specifies a MAC address as the primary identifier for an Ethernet device, named `eth1`, with a MAC address of `8A:8C:92:1A:F6:98`:
+
+[source,yaml]
+----
+# ...
+interfaces:
+- name: eth1
+  profile-name: wan0
+  type: ethernet
+  state: up
+  identifier: mac-address
+  mac-address: 8A:8C:92:1A:F6:98
+# ...
+----
 
 [id="virt-example-nmstate-IP-management-dns_{context}"]
 == DNS