Merge pull request #59623 from ousleyp/cnv-25648

CNV-25648: boot source doc improvements

Author: ousleyp

_topic_maps/_topic_map.yml

@@ -3710,8 +3710,6 @@ Topics:
       File: virt-configuring-vgpu-passthrough
     - Name: Configuring mediated devices
       File: virt-configuring-mediated-devices
-    - Name: Automatic importing and updating of pre-defined boot sources
-      File: virt-automatic-bootsource-updates
     - Name: Enabling descheduler evictions on virtual machines
       File: virt-enabling-descheduler-evictions
 # Importing virtual machines
@@ -3790,8 +3788,6 @@ Topics:
       File: virt-expanding-virtual-storage-with-blank-disk-images
     - Name: Cloning a data volume using smart-cloning
       File: virt-cloning-a-datavolume-using-smart-cloning
-    - Name: Creating and using boot sources
-      File: virt-creating-and-using-boot-sources
     - Name: Hot plugging virtual disks
       File: virt-hot-plugging-virtual-disks
     - Name: Using container disks with virtual machines
@@ -3816,6 +3812,11 @@ Topics:
     File: virt-deploying-vm-template-to-custom-namespace
   - Name: Deleting a virtual machine template
     File: virt-deleting-vm-template
+  - Name: Creating and using boot sources
+    File: virt-creating-and-using-boot-sources
+  - Name: Managing automatic boot source updates
+    File: virt-automatic-bootsource-updates
+    Distros: openshift-enterprise
 # Virtual machine live migration
 - Name: Live migration
   Dir: live_migration

modules/virt-about-auto-bootsource-updates.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assembly:
+//
+// * virt/vm_templates/virt-automatic-bootsource-updates.adoc
+//
+
+:_content-type: CONCEPT
+[id="virt-about-auto-bootsource-updates_{context}"]
+= About automatic boot source updates
+
+Boot sources can make virtual machine (VM) creation more accessible and efficient for users. If automatic boot source updates are enabled, the Containerized Data Importer (CDI) imports, polls, and updates the images so that they are ready to be cloned for new VMs. By default, CDI automatically updates the _system-defined_ boot sources that {VirtProductName} provides.
+
+You can opt out of automatic updates for all system-defined boot sources by disabling the `enableCommonBootImageImport` feature gate. If you disable this feature gate, all `DataImportCron` objects are deleted. This does not remove previously imported `PersistentVolumeClaim` (PVC) objects that store operating system images, though administrators can delete them manually. 
+
+When the `enableCommonBootImageImport` feature gate is disabled, `DataSource` objects are reset so that they no longer point to the original PVCs. An administrator can manually provide a boot source by creating a new PVC for the `DataSource` object and populating the PVC with an operating system image.
+
+_Custom_ boot sources that are not provided by {VirtProductName} are not controlled by the feature gate. You must manage them individually by editing the `HyperConverged` custom resource (CR). You can also use this method to manage individual system-defined boot sources.

modules/virt-adding-a-boot-source-web.adoc

@@ -32,9 +32,9 @@ There are four methods for selecting and adding a boot source in the web console
 . Click the options menu beside a template and select *Edit boot source*.
 . Click *Add disk*.
 . In the *Add disk* window, select *Use this disk as a boot source*.
-. Enter the disk name and select a *Source*, for example, *Blank (creates PVC)* or *Use an existing PVC*.
+. Enter the disk name and select a *Source*, for example, *Blank (creates PVC)*.
 . Enter a value for *Persistent Volume Claim size* to specify the PVC size that is adequate for the uncompressed image and any additional space that is required.
-. Select a *Type*, for example, *Disk* or *CD-ROM*.
+. Select a *Type*, for example, *Disk*.
 . Optional: Click *Storage class* and select the storage class that is used to create the disk. Typically, this storage class is the default storage class that is created for use by all PVCs.
 +
 [NOTE]

modules/virt-autoupdate-custom-bootsource.adoc

@@ -1,26 +1,30 @@
 // Module included in the following assembly:
 //
-// * virt/virtual_machines/advanced_vm_management/virt-automatic-bootsource-updates.adoc
+// * virt/vm_templates/virt-automatic-bootsource-updates.adoc
 //
 
 :_content-type: PROCEDURE
 [id="virt-autoupdate-custom-bootsource_{context}"]
-= Enabling automatic updates for user-defined boot sources
+= Enabling automatic updates for custom boot sources
 
-{VirtProductName} automatically updates system-defined boot sources by default, but does not automatically update user-defined boot sources. You must manually enable automatic imports and updates on a user-defined boot sources by editing the `HyperConverged` custom resource (CR).
+{VirtProductName} automatically updates system-defined boot sources by default, but does not automatically update custom boot sources. You must manually enable automatic updates by editing the `HyperConverged` custom resource (CR).
+
+.Prerequisites
+
+* The cluster has a default storage class.
 
 .Procedure
 
-. Use the following command to open the `HyperConverged` CR for editing:
+. Open the `HyperConverged` CR in your default editor by running the following command:
 +
 [source,terminal]
 ----
-$ oc edit -n openshift-cnv HyperConverged
+$ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv
 ----
 
 . Edit the `HyperConverged` CR, adding the appropriate template and boot source in the `dataImportCronTemplates` section. For example:
 +
-.Example in CentOS 7
+.Example custom resource
 [source,yaml]
 ----
 apiVersion: hco.kubevirt.io/v1beta1
@@ -52,3 +56,5 @@ spec:
 <3> Use to create a data volume from a registry source. Use the default `pod` `pullMethod` and not `node` `pullMethod`, which is based on the `node` docker cache. The `node` docker cache is useful when a registry image is available via `Container.Image`, but the CDI importer is not authorized to access it.
 <4> For the custom image to be detected as an available boot source, the name of the image's `managedDataSource` must match the name of the template's `DataSource`, which is found under `spec.dataVolumeTemplates.spec.sourceRef.name` in the VM template YAML file.
 <5> Use `All` to retain data volumes and data sources when the cron job is deleted. Use `None` to delete data volumes and data sources when the cron job is deleted.
+
+. Save the file.

modules/virt-configuring-storage-class-bootsource-update.adoc

@@ -1,17 +1,29 @@
 // Module included in the following assembly:
 //
-// * virt/virtual_machines/advanced_vm_management/virt-automatic-bootsource-updates.adoc
+// * virt/vm_templates/virt-automatic-bootsource-updates.adoc
 //
 
 :_content-type: PROCEDURE
 [id="virt-configuring-storage-class-bootsource-update_{context}"]
-= Configuring a storage class for user-defined boot source updates
+= Configuring a storage class for custom boot source updates
 
-You can configure a storage class that allows automatic importing and updating for user-defined boot sources.
+Specify a new default storage class in the `HyperConverged` custom resource (CR).
+
+[IMPORTANT]
+====
+Boot sources are created from storage using the default storage class. If your cluster does not have a default storage class, you must define one before configuring automatic updates for custom boot sources.
+====
 
 .Procedure
 
-. Define a new `storageClassName` by editing the `HyperConverged` custom resource (CR).
+. Open the `HyperConverged` CR in your default editor by running the following command:
++
+[source,terminal]
+----
+$ oc edit hco -n openshift-cnv kubevirt-hyperconverged
+----
+
+. Define a new storage class by entering a value in the `storageClassName` field:
 +
 [source,yaml]
 ----
@@ -26,17 +38,42 @@ spec:
     spec:
       template:
         spec:
-          storageClassName: <appropriate_class_name>
-# ...
+          storageClassName: <new_storage_class> <1>
+#...
 ----
-. Set the new default storage class by running the following commands:
+<1> Define the storage class.
+
+. Remove the `storageclass.kubernetes.io/is-default-class` annotation from the current default storage class. 
+.. Retrieve the name of the current default storage class by running the following command:
 +
 [source,terminal]
 ----
-$ oc patch storageclass <current_default_storage_class> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'
+$ oc get sc
+----
++
+.Example output
+[source,text]
 ----
+NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE
+csi-manila-ceph manila.csi.openstack.org Delete Immediate false 11d
+hostpath-csi-basic (default) kubevirt.io.hostpath-provisioner Delete WaitForFirstConsumer false 11d <1>
+...
+----
++
+<1> In this example, the current default storage class is named `hostpath-csi-basic`.
+
+.. Remove the annotation from the current default storage class by running the following command:
++
+[source,terminal]
+----
+$ oc patch storageclass <current_default_storage_class> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}' <1>
+----
+<1> Replace `<current_default_storage_class>` with the `storageClassName` value of the default storage class.
+
+. Set the new storage class as the default by running the following command:
 +
 [source,terminal]
 ----
-$ oc patch storageclass <appropriate_storage_class> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
+$ oc patch storageclass <new_storage_class> -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' <1>
 ----
+<1> Replace `<new_storage_class>` with the `storageClassName` value that you added to the `HyperConverged` CR.

modules/virt-disable-auto-updates-single-boot-source.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assembly:
+//
+// * virt/vm_templates/virt-automatic-bootsource-updates.adoc
+//
+
+:_content-type: PROCEDURE
+[id="virt-disable-auto-updates-single-boot-source_{context}"]
+= Disabling automatic updates for a single boot source
+
+You can disable automatic updates for an individual boot source, whether it is custom or system-defined, by editing the `HyperConverged` custom resource (CR).
+
+.Procedure
+
+. Open the `HyperConverged` CR in your default editor by running the following command:
++
+[source,terminal]
+----
+$ oc edit hyperconverged kubevirt-hyperconverged -n openshift-cnv
+----
+
+. Disable automatic updates for an individual boot source by editing the `spec.dataImportCronTemplates` field.
++
+Custom boot source::
+* Remove the boot source from the `spec.dataImportCronTemplates` field. Automatic updates are disabled for custom boot sources by default.
+
++
+System-defined boot source::
+.. Add the boot source to `spec.dataImportCronTemplates`. 
++
+[NOTE]
+====
+Automatic updates are enabled by default for system-defined boot sources, but these boot sources are not listed in the CR unless you add them.
+====
+.. Set the value of the `dataimportcrontemplate.kubevirt.io/enable` annotation to `false`.
++
+--
+For example:
+[source,yaml]
+----
+apiVersion: hco.kubevirt.io/v1beta1
+kind: HyperConverged
+metadata:
+  name: kubevirt-hyperconverged
+spec:
+  dataImportCronTemplates:
+  - metadata:
+      annotations:
+        dataimportcrontemplate.kubevirt.io/enable: false
+      name: rhel8-image-cron
+# ...
+----
+--
+
+. Save the file.

modules/virt-disable-bootsource-update.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assembly:
+//
+// * virt/vm_templates/virt-automatic-bootsource-updates.adoc
+//
+
+:_content-type: PROCEDURE
+[id="virt-managing-auto-update-all-system-boot-sources_{context}"]
+= Managing automatic updates for all system-defined boot sources
+
+Disabling automatic boot source imports and updates can lower resource usage. In disconnected environments, disabling automatic boot source updates prevents `CDIDataImportCronOutdated` alerts from filling up logs.
+
+To disable automatic updates for all system-defined boot sources, turn off the `enableCommonBootImageImport` feature gate by setting the value to `false`. Setting this value to `true` re-enables the feature gate and turns automatic updates back on.
+
+[NOTE]
+====
+Custom boot sources are not affected by this setting.
+====
+
+.Procedure
+
+* Toggle the feature gate for automatic boot source updates by editing the `HyperConverged` custom resource (CR).
+
+** To disable automatic boot source updates, set the `spec.featureGates.enableCommonBootImageImport` field in the `HyperConverged` CR to `false`. For example:
++
+[source,terminal]
+----
+$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
+  --type json -p '[{"op": "replace", "path": \
+  "/spec/featureGates/enableCommonBootImageImport", \
+  "value": false}]'
+----
+
+** To re-enable automatic boot source updates, set the `spec.featureGates.enableCommonBootImageImport` field in the `HyperConverged` CR to `true`. For example:
++
+[source,terminal]
+----
+$ oc patch hco kubevirt-hyperconverged -n openshift-cnv \
+  --type json -p '[{"op": "replace", "path": \
+  "/spec/featureGates/enableCommonBootImageImport", \
+  "value": true}]'
+----