diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 6468c67fcd28..014b7180f7a0 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/_topic_maps/_topic_map_rosa.yml b/_topic_maps/_topic_map_rosa.yml index 66982f0fd687..c84427096557 100644 --- a/_topic_maps/_topic_map_rosa.yml +++ b/_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 diff --git a/_topic_maps/_topic_map_rosa_hcp.yml b/_topic_maps/_topic_map_rosa_hcp.yml index 79f13edc7180..9b3841d844fd 100644 --- a/_topic_maps/_topic_map_rosa_hcp.yml +++ b/_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 diff --git a/modules/virt-add-custom-golden-image-heterogeneous-cluster.adoc b/modules/virt-add-custom-golden-image-heterogeneous-cluster.adoc new file mode 100644 index 000000000000..debfe0c2eb16 --- /dev/null +++ b/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: "" <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. diff --git a/modules/virt-creating-vm-from-template.adoc b/modules/virt-creating-vm-from-template.adoc index fcf461f90117..74a6e6d52153 100644 --- a/modules/virt-creating-vm-from-template.adoc +++ b/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. diff --git a/modules/virt-creating-vm-instancetype.adoc b/modules/virt-creating-vm-instancetype.adoc index d37e2d80e727..9cc13d5d4cbe 100644 --- a/modules/virt-creating-vm-instancetype.adoc +++ b/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. + diff --git a/modules/virt-enabling-heterogeneous-clusters.adoc b/modules/virt-enabling-heterogeneous-clusters.adoc new file mode 100644 index 000000000000..c77b9dc07fcc --- /dev/null +++ b/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}]' +---- diff --git a/modules/virt-generalizing-linux-vm-image.adoc b/modules/virt-generalizing-linux-vm-image.adoc index 312f013fb0cf..a87130c9a6d9 100644 --- a/modules/virt-generalizing-linux-vm-image.adoc +++ b/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. diff --git a/modules/virt-mod-golden-image-heterogeneous-clusters.adoc b/modules/virt-mod-golden-image-heterogeneous-clusters.adoc new file mode 100644 index 000000000000..8078c0193c7c --- /dev/null +++ b/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: "" <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. \ No newline at end of file diff --git a/modules/virt-modify-workload-node-heterogeneous-cluster.adoc b/modules/virt-modify-workload-node-heterogeneous-cluster.adoc new file mode 100644 index 000000000000..e48e46b5d5f2 --- /dev/null +++ b/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: + - <1> +---- +<1> Replace `` with the target architecture. For example, to limit placement to AMD nodes, use `amd64`. + +. Save and exit the editor to update the `HyperConverged` CR. diff --git a/virt/creating_vms_advanced/advanced-vm-creation-overview.adoc b/virt/creating_vms_advanced/advanced-vm-creation-overview.adoc index c8d35387ba30..0d3a9333efeb 100644 --- a/virt/creating_vms_advanced/advanced-vm-creation-overview.adoc +++ b/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] diff --git a/virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc b/virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc index 3552d1176ff1..30f8d6e1294a 100644 --- a/virt/creating_vms_advanced/creating_vms_advanced_web/virt-creating-vms-from-rh-images-overview.adoc +++ b/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] \ No newline at end of file +include::modules/virt-golden-images-namespace-cli.adoc[leveloffset=+1] \ No newline at end of file diff --git a/virt/creating_vms_advanced/creating_vms_advanced_web/virt-golden-image-heterogeneous-clusters.adoc b/virt/creating_vms_advanced/creating_vms_advanced_web/virt-golden-image-heterogeneous-clusters.adoc new file mode 100644 index 000000000000..7ef97551abc1 --- /dev/null +++ b/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] +