Updates for golden image heterogenous cluster support

_topic_maps/_topic_map.yml

@@ -4791,13 +4791,16 @@ Topics:
 - Name: Advanced VM creation
   Dir: creating_vms_advanced
   Topics:
-  - Name: Advanced virtual machine creation overview
-    File: advanced-vm-creation-overview
-  - Name: Creating VMs in the web console
+  - Name: Creating VMs from Red Hat images
     Dir: creating_vms_advanced_web
     Topics:
-    - Name: Creating VMs from Red Hat images
+    - Name: Creating virtual machines from Red Hat images
       File: virt-creating-vms-from-rh-images-overview
+    - Name: Heterogeneous cluster support
+      File: virt-golden-image-heterogeneous-clusters
+  - Name: Creating VMs in the web console
+    Dir: creating_vms_advanced_web
+    Topics:
     - Name: Creating VMs by importing images from web pages
       File: virt-creating-vms-from-web-images
     - Name: Creating VMs by uploading images

_topic_maps/_topic_map_rosa.yml

@@ -1756,11 +1756,16 @@ Topics:
   Topics:
 #  - Name: Overview
 #    File: virt-advanced-vm-overview
-  - Name: Creating VMs in the web console
+  - Name: Creating VMs from Red Hat images
     Dir: creating_vms_advanced_web
     Topics:
-    - Name: Creating VMs from Red Hat images
+    - Name: Creating virtual machines from Red Hat images
       File: virt-creating-vms-from-rh-images-overview
+    - Name: Heterogeneous cluster support
+      File: virt-golden-image-heterogeneous-clusters
+  - Name: Creating VMs in the web console
+    Dir: creating_vms_advanced_web
+    Topics:
     - Name: Creating VMs by importing images from web pages
       File: virt-creating-vms-from-web-images
     - Name: Creating VMs by uploading images

_topic_maps/_topic_map_rosa_hcp.yml

@@ -1585,11 +1585,16 @@ Topics:
   Topics:
 #  - Name: Overview
 #    File: virt-advanced-vm-overview
-  - Name: Creating VMs in the web console
+  - Name: Creating VMs from Red Hat images
     Dir: creating_vms_advanced_web
     Topics:
-    - Name: Creating VMs from Red Hat images
+    - Name: Creating virtual machines from Red Hat images
       File: virt-creating-vms-from-rh-images-overview
+    - Name: Heterogeneous cluster support
+      File: virt-golden-image-heterogeneous-clusters
+  - Name: Creating VMs in the web console
+    Dir: creating_vms_advanced_web
+    Topics:
     - Name: Creating VMs by importing images from web pages
       File: virt-creating-vms-from-web-images
     - Name: Creating VMs by uploading images

modules/virt-add-custom-golden-image-heterogeneous-cluster.adoc

@@ -0,0 +1,59 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/advanced_vm_management/virt-creating-vms-from-rh-images-overview.adoc
+
+:_mod-docs-content-type: PROCEDURE 
+[id="virt-add-custom-golden-image-heterogeneous-cluster_{context}"]
+
+= Adding a custom golden image in a heterogeneous cluster
+
+:FeatureName: Golden image support for heterogeneous clusters
+include::snippets/technology-preview.adoc[]
+
+Add a custom golden image in a heterogeneous cluster by setting the `ssp.kubevirt.io/dict.architectures` annotation in the `spec.dataImportCronTemplates.metadata.annotations` stanza of the `HyperConverged` custom resource (CR). This annotation lists the architectures supported by the image.
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Open the `HyperConverged` CR in your default editor by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc edit hyperconverged kubevirt-hyperconverged -n {CNVNamespace}
+----
+
+. Edit the `HyperConverged` CR, to add the custom golden image. You must add the appropriate values for `ssp.kubevirt.io/dict.architectures` annotation in the `dataImportCronTemplates` section. For example:
++
+[source,yaml]
+----
+apiVersion: hco.kubevirt.io/v1beta1
+kind: HyperConverged
+metadata:
+  name: kubevirt-hyperconverged
+spec:
+  dataImportCronTemplates:
+  - metadata:
+      name: custom-image1
+      annotations:
+        ssp.kubevirt.io/dict.architectures: "<architecture_list>" <1>
+    spec:
+      schedule: "0 */12 * * *"
+      template:
+        spec:
+          source:
+            registry:
+              url: docker://myprivateregistry/custom1
+      managedDataSource: custom1
+      retentionPolicy: "All" 
+#...
+----
+<1> The comma-separated list of supported architectures for this image. For example, if the image supports `amd64` and `arm64` architectures, the value would be `"amd64,arm64"`.
++
+[NOTE]
+====
+An image may support more architectures than you want to use in your cluster. You do not have to list all of the architectures an image supports, only those for which you want to create a boot source.
+====
+. Save and exit the editor to update the `HyperConverged` CR.

modules/virt-creating-vm-from-template.adoc

@@ -21,6 +21,9 @@ You can choose between two views in the web console to create the VM:
 ** For a general view, navigate to *Virtualization* -> *Catalog*.
 . Click the *Template catalog* tab.
 . Click the *Boot source available* checkbox to filter templates with boot sources. The catalog displays the default templates.
+
+. Heterogeneous clusters only: To filter the search results to show templates associated with a particular architecture, click *Architecture Type* .
+
 . Click *All templates* to view the available templates for your filters.
 ** To focus on particular templates, enter the keyword in the `Filter by keyword` field.
 ** Choose a template project from the *All projects* dropdown menu, or view all projects.

modules/virt-creating-vm-instancetype.adoc

@@ -51,6 +51,8 @@ The *InstanceTypes* tab opens by default.
 When configuring a downward-metrics device on an {ibm-z-name} system that uses a VM preference, set the `spec.preference.name` value to `rhel.9.s390x` or another available preference with the format `*.s390x`.
 ====
 
+. Heterogeneous clusters only: To filter the bootable volumes using the options provided, click *Architecture*.
+
 . Select either of the following options:
 * Select a suitable bootable volume from the list. If the list is truncated, click the *Show all* button to display the entire list.
 +

modules/virt-enabling-heterogeneous-clusters.adoc

@@ -0,0 +1,27 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/advanced_vm_management/virt-creating-vms-from-rh-images-overview.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-enabling-heterogeneous-clusters_{context}"]
+= Enabling heterogeneous cluster support
+
+You can enable golden image support for heterogeneous clusters by setting the `enableMultiArchBootImageImport` feature gate to `true` in the `HyperConverged` custom resource (CR).
+
+:FeatureName: Golden image support for heterogeneous clusters
+include::snippets/technology-preview.adoc[]
+
+.Prerequisites
+
+* You have access to the cluster as a user with `cluster-admin` permissions.
+* You have installed the {oc-first}.
+
+.Procedure
+
+* Enable the `enableMultiArchBootImageImport` feature gate by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc patch hyperconverged kubevirt-hyperconverged -n {CNVNamespace} \
+  --type json -p '[{"op":"replace","path":"/spec/featureGates/enableMultiArchBootImageImport", "value": true}]'
+----

modules/virt-generalizing-linux-vm-image.adoc

@@ -95,6 +95,8 @@ $ virt-sysprep -a disk.img
 
 .. From the *Default Instance Type* list, select the instance type with the correct CPU and memory requirements for the version of {op-system-base} you selected previously.
 
+.. Heterogeneous clusters only: From the *Architecture* list, select the architecture that corresponds with the selected volume.
+
 .. Click *Save*.
 
 The new volume appears in the *Select volume to boot from* list. This is your new golden image. You can use this volume to create new VMs.

modules/virt-mod-golden-image-heterogeneous-clusters.adoc

@@ -0,0 +1,50 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/advanced_vm_management/virt-creating-vms-from-rh-images-overview.adoc
+
+:_mod-docs-content-type: PROCEDURE 
+[id="virt-mod-golden-image-heterogeneous-clusters_{context}"]
+= Modifying a common golden image source in a heterogeneous cluster
+
+You can modify the image source of a common golden image in a heterogeneous cluster by specifying the supported architectures in the `ssp.kubevirt.io/dict.architectures` annotation in the `HyperConverged` custom resource (CR).
+
+:FeatureName: Golden image support for heterogeneous clusters
+include::snippets/technology-preview.adoc[]
+
+.Prerequisites
+
+* You have installed the {oc-first}.   
+
+.Procedure
+
+. Open the `HyperConverged` CR in your default editor by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc edit hyperconverged kubevirt-hyperconverged -n {CNVNamespace}
+----
+
+. Edit the `HyperConverged` CR, adding the appropriate values for `ssp.kubevirt.io/dict.architectures` annotation in the `dataImportCronTemplates` section. For example:
++
+[source,yaml]
+----
+#...
+spec:
+  dataImportCronTemplates:
+  - metadata:
+      name: kubevirt-hyperconverged
+      annotations:
+        ssp.kubevirt.io/dict.architectures: "<architecture_list>" <1>
+    spec:
+      schedule: "0 */12 * * *"
+      template:
+        spec:
+          source:
+            registry:
+                url: docker://my-private-registry/my-own-version-of-centos:8
+      managedDataSource: centos-stream8
+#...
+----
+<1> The comma-separated list of supported architectures for this image. For example, if the image supports `amd64` and `arm64` architectures, the value would be `"amd64,arm64"`.
+
+. Save and exit the editor to update the `HyperConverged` CR.

modules/virt-modify-workload-node-heterogeneous-cluster.adoc

@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/advanced_vm_management/virt-creating-vms-from-rh-images-overview.adoc
+
+:_mod-docs-content-type: PROCEDURE 
+[id="virt-modify-workload-node-heterogeneous-cluster_{context}"]
+
+= Modifying workloads node placement in a heterogeneous cluster
+
+:FeatureName: Golden image support for heterogeneous clusters
+include::snippets/technology-preview.adoc[]
+
+If you have a heterogeneous cluster but not want to enable multiple archiecture support, you can modify the workloads node placement in the `HyperConverged` custom resource (CR) to only include nodes with a specific architecture.
+
+.Prerequisites
+
+* You have installed the {oc-first}.
+
+.Procedure
+
+. Open the `HyperConverged` CR in your default editor by running the following command:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc edit hyperconverged kubevirt-hyperconverged -n {CNVNamespace}
+----
+
+. Edit the `HyperConverged` CR, to modify the workloads node placement to include only nodes with a specific architecture. For example:
++
+[source,yaml]
+----
+apiVersion: hco.kubevirt.io/v1beta1
+kind: HyperConverged
+metadata:
+  name: kubevirt-hyperconverged
+spec:
+#...
+  workloads:
+    nodePlacement:
+      affinity:
+        nodeAffinity:
+          requiredDuringSchedulingIgnoredDuringExecution:
+            nodeSelectorTerms:
+              - matchExpressions:
+                  - key: kubernetes.io/arch
+                    operator: In
+                    values:
+                      - <node_architecture> <1>
+----
+<1> Replace `<node_architecture>` with the target architecture. For example, to limit placement to AMD nodes, use `amd64`.
+
+. Save and exit the editor to update the `HyperConverged` CR.

virt/creating_vms_advanced/advanced-vm-creation-overview.adoc

@@ -8,13 +8,19 @@ toc::[]
 
 Advanced virtual machine (VM) creation offers flexibility for cloud administrators, developers, security teams, and platform engineering teams to ensure consistency, optimize performance, enforce policies, and integrate with automated deployment pipelines. This helps to streamline provisioning and scalability, whether using the command-line interface (CLI) or web console.
 
+
+[id="adv-creating-vms-red-hat-images"]
+
+== Creating virtual machines from Red Hat images
+
+* xref:../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#virt-creating-vms-from-rh-images-overview[Creating virtual machines from Red Hat images overview]
+
 [id="adv-creating-vms-in-web-console"]
+
 == Creating VMs in the web console
 
 Use the following advanced methods for creating VMs in the web console:
 
-* xref:../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#virt-creating-vms-from-rh-images-overview[Creating virtual machines from Red Hat images overview]
-
 * xref:../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-web-images.adoc#virt-creating-vms-from-web-images[Creating VMs by importing images from web pages]
 
 * xref:../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-uploading-images.adoc#virt-creating-vms-uploading-images[Creating VMs by uploading images]

virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc

@@ -1,12 +1,16 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="virt-creating-vms-from-rh-images-overview"]
-= Creating virtual machines from Red Hat images overview
+= Creating virtual machines from Red Hat images
 include::_attributes/common-attributes.adoc[]
 :context: virt-creating-vms-from-rh-images-overview
 
 toc::[]
 
-Red Hat images are xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#virt-about-golden-images_virt-creating-vms-from-rh-images-overview[golden images]. They are published as container disks in a secure registry. The Containerized Data Importer (CDI) polls and imports the container disks into your cluster and stores them in the `openshift-virtualization-os-images` project as snapshots or persistent volume claims (PVCs). You can optionally xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#configuring-custom-namespace-golden-images[use a custom namespace] for golden images.
+Red Hat images are xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#virt-about-golden-images_virt-creating-vms-from-rh-images-overview[golden images]. They are published as container disks in a secure registry. The Containerized Data Importer (CDI) polls and imports the container disks into your cluster and stores them in the `openshift-virtualization-os-images` project as snapshots or persistent volume claims (PVCs). You can optionally use a custom namespace for golden images. For more information about using a custom namespace, see:
+
+* xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#virt-golden-images-namespace-web_virt-creating-vms-from-rh-images-overview[Configuring a custom namespace for golden images by using the web console]
+
+* xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc#virt-golden-images-namespace-cli_virt-creating-vms-from-rh-images-overview[Configuring a custom namespace for golden images by using the CLI]
 
 Red Hat images are automatically updated. You can disable and re-enable automatic updates for these images. See xref:../../../virt/storage/virt-automatic-bootsource-updates.adoc#managing-rh-boot-source-updates_virt-automatic-bootsource-updates[Managing Red Hat boot source updates].
 
@@ -29,11 +33,6 @@ include::modules/virt-golden-images.adoc[leveloffset=+1]
 
 include::modules/virt-about-vms-and-boot-sources.adoc[leveloffset=+1]
 
-[id="configuring-custom-namespace-golden-images"]
-== Configuring a custom namespace for golden images
-
-The default namespace for golden images is `openshift-virtualization-os-images`, but you can configure a custom namespace to restrict user access to the default boot sources.
-
-include::modules/virt-golden-images-namespace-web.adoc[leveloffset=+2]
+include::modules/virt-golden-images-namespace-web.adoc[leveloffset=+1]
 
-include::modules/virt-golden-images-namespace-cli.adoc[leveloffset=+2]
+include::modules/virt-golden-images-namespace-cli.adoc[leveloffset=+1]

virt/creating_vms_advanced/creating_vms_advanced_web/virt-golden-image-heterogeneous-clusters.adoc

@@ -0,0 +1,37 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="virt-golden-image-heterogeneous-clusters"]
+= Heterogeneous cluster support
+include::_attributes/common-attributes.adoc[]
+:context: virt-golden-image-heterogeneous-clusters
+
+toc::[]
+
+:FeatureName: Golden image support for heterogeneous clusters
+include::snippets/technology-preview.adoc[]
+
+A heterogeneous cluster is a cluster where nodes have differing architectures. Heterogeneous clusters promote optimal compute resource usage by mixing different types of hardware in one cluster. This allows workloads to be better matched to hardware intended for the workload task instead of general purpose compute platforms. For example, in a heterogeneous cluster, GPU and general purpose compute resources could be combined and workloads assigned to the appropriate hardware.
+
+[IMPORTANT]
+====
+If golden image support is disabled in a heterogeneous cluster, you can encounter inconsistencies between node and image architectures. This happens when images are used for virtual machine creation that do not match the node architecture. This can lead to the failure of virtual machine boot up or virtual machines that do not run as expected. The warning level alert `HCOMultiArchGoldenImagesDisabled` is produced when this feature is not enabled in a heterogeneous cluster. 
+====
+
+If you have a heterogeneous cluster but do not want to enable multiple architecture support, see xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-golden-image-heterogeneous-clusters.adoc#virt-modify-workload-node-heterogeneous-cluster_virt-golden-image-heterogeneous-clusters[Modifying workloads node placement in a hetergeneous cluster] for the procedure to limit node placement to a specific architecture.
+
+Golden image support for heterogeneous clusters extends golden image support in the following areas:
+
+* Enables VM creators to deploy persistent virtual machines with specific architectures.
+* Enables VM creators to define custom golden images that support heterogenous clusters.
+
+The same golden image can be used with nodes of different architectures if the boot image supports the required architectures. For example, a golden image that supports both ARM and AMD architectures can be used with both types of nodes. 
+
+Golden image support for heterogeneous clusters is not enabled by default. For the procedure to enable this feature, see xref:../../../virt/creating_vms_advanced/creating_vms_advanced_web/virt-golden-image-heterogeneous-clusters.adoc#virt-enabling-heterogeneous-clusters_virt-golden-image-heterogeneous-clusters[Enabling hetergenous cluster support]
+
+include::modules/virt-enabling-heterogeneous-clusters.adoc[leveloffset=+1]
+
+include::modules/virt-mod-golden-image-heterogeneous-clusters.adoc[leveloffset=+1]
+
+include::modules/virt-add-custom-golden-image-heterogeneous-cluster.adoc[leveloffset=+1]
+
+include::modules/virt-modify-workload-node-heterogeneous-cluster.adoc[leveloffset=+1]
+