From 651d7b1bc38e2ac1c33da85113838bc383e02a8c Mon Sep 17 00:00:00 2001 From: Michael Burke Date: Fri, 3 Apr 2026 16:56:22 -0400 Subject: [PATCH] [docs] Document scenarios with multiple discovered images This patch adds a docs page for the process of using multiple different discovered images with the reproducer, explaining which values need to be modified and where in order to to support running such a setup Signed-off-by: Michael Burke --- .../04-multiple-discovered-images.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/source/reproducers/04-multiple-discovered-images.md diff --git a/docs/source/reproducers/04-multiple-discovered-images.md b/docs/source/reproducers/04-multiple-discovered-images.md new file mode 100644 index 0000000000..4a2cfc2330 --- /dev/null +++ b/docs/source/reproducers/04-multiple-discovered-images.md @@ -0,0 +1,112 @@ +# Deploy nodes with different discovered OS images + +This page documents the reproducer workflow for nodes with different discovered +OS images than other nodes. + +With the `discover_latest_image` role, it is possible to find the latest qcow2 +OS images from multiple different URLs. With those discovered images, we can +then modify the Libvirt configuration to run different OS versions on different +nodes. + +In the below example, we will modify a reproducer to run CentOS 10 on the +compute nodes, and CentOS 9 on a controller and a networker node. + +## Request the discovery of multiple different images + +Provide a `cifmw_discover_latest_image_requests` dict with the required fields +for multiple different image URLs to discover multiple different images. For +example: + +```yaml +cifmw_discover_latest_image_requests: + centos10: + base_url: "https://cloud.centos.org/centos/10-stream/x86_64/images/" + qcow_prefix: "CentOS-Stream-GenericCloud-x86_64-" + images_file: CHECKSUM + centos9: + base_url: "https://cloud.centos.org/centos/9-stream/x86_64/images/" + qcow_prefix: "CentOS-Stream-GenericCloud-x86_64-" + images_file: CHECKSUM +``` + +## Update VM Image Sources In the Libvirt Config + +Use one of the following patterns depending on how +`cifmw_libvirt_manager_configuration` is defined in your scenario. + +### Direct configuration + +If you wish to modify a `cifmw_libvirt_manager_configuration` directly, edit +the `image_url`, `sha256_image_name`, and `disk_file_name` fields in your +desired entries. For example: + +```yaml +cifmw_libvirt_manager_configuration: + vms: + compute: + image_url: "{{ cifmw_discovered_images_dict.centos10.image_url }}" + sha256_image_name: "{{ cifmw_discovered_images_dict.centos10.hash }}" + disk_file_name: "base-os-centos10.qcow2" + controller: + image_url: "{{ cifmw_discovered_images_dict.centos9.image_url }}" + sha256_image_name: "{{ cifmw_discovered_images_dict.centos9.hash }}" + disk_file_name: "base-os-centos9.qcow2" + networker: + image_url: "{{ cifmw_discovered_images_dict.centos9.image_url }}" + sha256_image_name: "{{ cifmw_discovered_images_dict.centos9.hash }}" + disk_file_name: "base-os-centos9.qcow2" +``` +~~~{tip} +Be careful to supply different filenames to the `disk_file_name` field for +different VM types when you don't want them to use the same OS image. Failing +to do so will cause the different VM types to be created using the same OS +image. + +When two different VM types are using the same base VM image, then they can +use the same `disk_file_name` to avoid downloading the same image multiple +times. +~~~ + +### Configuration sourced from external file + +If the `cifmw_libvirt_manager_configuration` is sourced from an external file +and you wish to modify it to use separate images for separate VM types, use +`cifmw_libvirt_manager_configuration_patch_*` variables instead: + +```yaml +cifmw_libvirt_manager_configuration_patch_01_compute_image: + vms: + compute: + image_url: "{{ cifmw_discovered_images_dict.centos10.image_url }}" + sha256_image_name: "{{ cifmw_discovered_images_dict.centos10.hash }}" + disk_file_name: "base-os-centos10.qcow2" + +cifmw_libvirt_manager_configuration_patch_02_controller_image: + vms: + controller: + image_url: "{{ cifmw_discovered_images_dict.centos9.image_url }}" + sha256_image_name: "{{ cifmw_discovered_images_dict.centos9.hash }}" + disk_file_name: "base-os-centos9.qcow2" + +cifmw_libvirt_manager_configuration_patch_03_networker_image: + vms: + networker: + image_url: "{{ cifmw_discovered_images_dict.centos9.image_url }}" + sha256_image_name: "{{ cifmw_discovered_images_dict.centos9.hash }}" + disk_file_name: "base-os-centos9.qcow2" +``` + +The `libvirt_manager` role collects all +`cifmw_libvirt_manager_configuration_patch_*` variables, sorts them by variable +name, then merges them recursively on top of the base configuration. + +## Run the reproducer + +Run the reproducer, and once the virtual machines are up, validate that they +are running the appropriate operating systems. For example, run commands like: + +```bash +ssh controller-0 "cat /etc/redhat-release" +ssh compute-0 "cat /etc/redhat-release" +ssh networker-0 "cat /etc/redhat-release" +```