From e984ba0972e00e7410dcfea120ae1e08076eba7e Mon Sep 17 00:00:00 2001
From: xenolinux <sdudhgao@redhat.com>
Date: Tue, 11 Mar 2025 15:22:36 +0530
Subject: [PATCH] OSDOCS#12034: HCP Kubevirt topology spread constraint

---
 .../hcp-manage/hcp-manage-virt.adoc           |  7 +++
 modules/hcp-topology-spread-constraint.adoc   | 50 +++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 modules/hcp-topology-spread-constraint.adoc

diff --git a/hosted_control_planes/hcp-manage/hcp-manage-virt.adoc b/hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
index 5a6833edae..aaf46eb970 100644
--- a/hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
+++ b/hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
@@ -59,3 +59,10 @@ include::modules/hcp-virt-etcd-storage.adoc[leveloffset=+2]
 include::modules/hcp-virt-attach-nvidia-gpus.adoc[leveloffset=+1]
 
 include::modules/hcp-virt-attach-nvidia-gpus-np-api.adoc[leveloffset=+1]
+
+include::modules/hcp-topology-spread-constraint.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../nodes/scheduling/descheduler/nodes-descheduler-configuring.adoc#nodes-descheduler-installing_virt-enabling-descheduler-evictions[Installing the descheduler]
diff --git a/modules/hcp-topology-spread-constraint.adoc b/modules/hcp-topology-spread-constraint.adoc
new file mode 100644
index 0000000000..aff970371a
--- /dev/null
+++ b/modules/hcp-topology-spread-constraint.adoc
@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-manage/hcp-manage-virt.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-topology-spread-constraint_{context}"]
+= Spreading node pool VMs by using topologySpreadConstraint
+
+By default, KubeVirt virtual machines (VMs) created by a node pool are scheduled on any available nodes that have the capacity to run the VMs. By default, the `topologySpreadConstraint` constraint is set to schedule VMs on multiple nodes.
+
+In some scenarios, node pool VMs might run on the same node, which can cause availability issues. To avoid distribution of VMs on a single node, use the descheduler to continuously honor the `topologySpreadConstraint` constraint to spread VMs on multiple nodes.
+
+.Prerequisites
+
+* You installed the {descheduler-operator}. For more information, see "Installing the descheduler".
+
+.Procedure
+
+* Open the `KubeDescheduler` custom resource (CR) by entering the following command, and then modify the `KubeDescheduler` CR to use the `SoftTopologyAndDuplicates` and `DevKubeVirtRelieveAndMigrate` profiles so that you maintain the `topologySpreadConstraint` constraint settings.
++
+The `KubeDescheduler` CR named `cluster` runs in the `openshift-kube-descheduler-operator` namespace.
++
+[source,terminal]
+----
+$ oc edit kubedescheduler cluster -n openshift-kube-descheduler-operator
+----
++
+.Example `KubeDescheduler` configuration
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: KubeDescheduler
+metadata:
+  name: cluster
+  namespace: openshift-kube-descheduler-operator
+spec:
+  mode: Automatic
+  managementState: Managed
+  deschedulingIntervalSeconds: 30 # <1>
+  profiles:
+  - SoftTopologyAndDuplicates   # <2>
+  - DevKubeVirtRelieveAndMigrate          # <3>
+  profileCustomizations:
+    devDeviationThresholds: AsymmetricLow
+    devActualUtilizationProfile: PrometheusCPUCombined
+# ...
+----
+<1> Sets the number of seconds between the descheduler running cycles.
+<2> This profile evicts pods that follow the soft topology constraint: `whenUnsatisfiable: ScheduleAnyway`.
+<3> This profile balances resource usage between nodes and enables the strategies, such as `RemovePodsHavingTooManyRestarts` and `LowNodeUtilization`.