From d44a8ca4c2f3c8d6f14d74ceb850612ba6d5ef1b Mon Sep 17 00:00:00 2001
From: Ashleigh Brennan <abrennan@redhat.com>
Date: Wed, 19 Nov 2025 12:30:35 -0600
Subject: [PATCH] CNV-69410: Customizing VM MAC pool range

---
 modules/virt-custom-kubemacpool-range.adoc    | 78 +++++++++++++++++++
 .../virt-using-mac-address-pool-for-vms.adoc  |  6 +-
 2 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 modules/virt-custom-kubemacpool-range.adoc

diff --git a/modules/virt-custom-kubemacpool-range.adoc b/modules/virt-custom-kubemacpool-range.adoc
new file mode 100644
index 0000000000..472354805b
--- /dev/null
+++ b/modules/virt-custom-kubemacpool-range.adoc
@@ -0,0 +1,78 @@
+// Module included in the following assemblies:
+//
+// * virt/vm_networking/virt-using-mac-address-pool-for-vms.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-custom-kubemacpool-range_{context}"]
+= Customizing the MAC pool range
+
+[role="_abstract"]
+KubeMacPool works by allocating MAC addresses to VMs from a range. The `rangeStart` and `rangeEnd` parameters in the `HyperConverged` custom resource (CR) define the MAC pool range.
+
+As a cluster administrator, you can configure this range to ensure that MAC addresses for VMs hosted on {VirtProductName} do not conflict with other virtualization solutions on the same network.
+
+.Prerequisites
+
+* You have cluster administrator access on an {product-title} cluster.
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Edit the `HyperConverged` CR by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc edit hyperconverged kubevirt-hyperconverged -n {CNVNamespace}
+----
+
+. Update the `HyperConverged` CR to configure the `rangeStart` and `rangeEnd` parameters that define your required MAC address range:
++
+[source,yaml]
+----
+apiVersion: hco.kubevirt.io/v1beta1
+kind: HyperConverged
+metadata:
+  name: kubevirt-hyperconverged
+spec:
+  kubeMacPoolConfiguration:
+    rangeStart: "AA:00:00:00:00:00"
+    rangeEnd: "FD:FF:FF:FF:FF:FF"
+# ...
+----
+
+.Verification
+
+. Run the following command and observe the output:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc get hco kubevirt-hyperconverged -n {CNVNamespace} -o=jsonpath='{.spec.kubeMacPoolConfiguration}'
+----
++
+If you have successfully applied the configuration changes, the output shows the new MAC pool range you have configured:
++
+Example output:
++
+[source,terminal]
+----
+{
+  "rangeStart": "AA:00:00:00:00:00",
+  "rangeEnd": "FD:FF:FF:FF:FF:FF"
+}
+----
+
+. Optional. Create a new VM and run the following command to check the MAC address of the VM's network interface:
++
+[source,terminal]
+----
+$ oc get vmi <vm-name> -o=jsonpath='{.status.interfaces[0].macAddress}'
+----
++
+Example output:
++
+[source,yaml]
+----
+macAddress: AA:00:00:00:00:04
+----
++
+If you have successfully applied the configuration changes, the `macAddress` field in the VM interface is within the range you specified in your `kubeMacPoolConfiguration`, between the value of `rangeStart` and `rangeEnd`.
diff --git a/virt/vm_networking/virt-using-mac-address-pool-for-vms.adoc b/virt/vm_networking/virt-using-mac-address-pool-for-vms.adoc
index 4e385d9a02..b7e26706d9 100644
--- a/virt/vm_networking/virt-using-mac-address-pool-for-vms.adoc
+++ b/virt/vm_networking/virt-using-mac-address-pool-for-vms.adoc
@@ -1,12 +1,13 @@
 :_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
 [id="virt-using-mac-address-pool-for-vms"]
 = Managing MAC address pools for network interfaces
-include::_attributes/common-attributes.adoc[]
 :context: virt-using-mac-address-pool-for-vms
 
 toc::[]
 
-The _KubeMacPool_ component allocates MAC addresses for virtual machine (VM) network interfaces from a shared MAC address pool. This ensures that each network interface is assigned a unique MAC address.
+[role="_abstract"]
+KubeMacPool allocates MAC addresses for virtual machine (VM) network interfaces from a shared MAC address pool. This ensures that each network interface is assigned a unique MAC address.
 
 A virtual machine instance created from that VM retains the assigned MAC address across reboots.
 
@@ -17,3 +18,4 @@ KubeMacPool does not handle virtual machine instances created independently from
 
 include::modules/virt-managing-kubemacpool-cli.adoc[leveloffset=+1]
 
+include::modules/virt-custom-kubemacpool-range.adoc[leveloffset=+1]