Merge pull request #80363 from sabrinajess/CNV31862

#CNV-38162: new inferfromvolume content

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -4389,6 +4389,8 @@ Topics:
       File: virt-creating-vms-by-cloning-pvcs
   - Name: Connecting to VM consoles
     File: virt-accessing-vm-consoles
+  - Name: Specifying an instance type or preference
+    File: virt-specifying-instance-preference
   - Name: Configuring SSH access to VMs
     File: virt-accessing-vm-ssh
   - Name: Editing virtual machines

modules/virt-infer-instancetype-preference.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virt-specifying-instance-preference.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-infer-instancetype-preference_{context}"]
+= Inferring an instance type or preference
+
+Inferring instance types, preferences, or both is enabled by default, and the `inferFromVolumeFailure` policy of the `inferFromVolume` attribute is set to `Ignore`. When inferring from the boot volume, errors are ignored, and the VM is created with the instance type and preference left unset.
+
+However, when flags are applied, the `inferFromVolumeFailure` policy defaults to `Reject`. When inferring from the boot volume, errors result in the rejection of the creation of that VM.
+
+You can use the `--infer-instancetype` and `--infer-preference` flags to infer which instance type, preference, or both to use to define the workload sizing and runtime characteristics of a VM.
+
+.Prerequisites
+
+* You have installed the `virtctl` tool.
+
+.Procedure
+
+* To explicitly infer instance types from the volume used to boot the virtual machine, use the `--infer-instancetype` flag. To explicitly infer preferences, use the `--infer-preference` flag. The following command includes both flags:
+
++
+[source,terminal]
+----
+$ virtctl create vm --volume-import type:pvc,src:my-ns/my-pvc --infer-instancetype --infer-preference
+----
+

modules/virt-inferfromvolume-labels.adoc

@@ -0,0 +1,28 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virt-specifying-instance-preference.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="inferfromvolume-labels_{context}"]
+= Setting the inferFromVolume labels
+
+Use the following labels on your PVC, data source, or data volume to instruct the inference mechanism which instance type, preference, or both to use when trying to boot from a volume.
+
+* A cluster-wide instance type: `instancetype.kubevirt.io/default-instancetype` label.
+* A namespaced instance type: `instancetype.kubevirt.io/default-instancetype-kind` label. Defaults to the `VirtualMachineClusterInstancetype` label if left empty.
+* A cluster-wide preference: `instancetype.kubevirt.io/default-preference` label.
+* A namespaced preference: `instancetype.kubevirt.io/default-preference-kind` label. Defaults to `VirtualMachineClusterPreference` label, if left empty.
+
+.Prerequisites
+
+* You must have an instance type, preference, or both on the cluster.
+
+.Procedure
+
+* To apply a label to a data source, use `oc label`. The following command applies a label that points to a cluster-wide instance type:
+
++
+[source,terminal]
+----
+$ oc label DataSource foo instancetype.kubevirt.io/default-instancetype=<my_instancetype>
+----

modules/virt-using-flags-specify.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/virt-specifying-instance-preference.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="virt-using-flags-specify_{context}"]
+= Using flags to specify instance types and preferences
+
+Specify instance types and preferences by using flags.
+
+.Prerequisites
+
+* You must have an instance type, preference, or both on the cluster.
+
+.Procedure
+
+. To specify an instance type when creating a VM, use the `--instancetype` flag. To specify a preference, use the `--preference` flag. The following example includes both flags:
+
++
+[source,terminal]
+----
+$ virtctl create vm --instancetype <my_instancetype> --preference <my_preference>
+----
+
+. Optional: To specify a namespaced instance type or preference, include the `kind` in the value passed to the `--instancetype` or `--preference` flag command. The namespaced instance type or preference must be in the same namespace you are creating the VM in. The following example includes flags for a namespaced instance type and a namespaced preference:
+
++
+[source,terminal]
+----
+$ virtctl create vm --instancetype virtualmachineinstancetype/<my_instancetype> --preference virtualmachinepreference/<my_preference>
+----

virt/virtual_machines/virt-specifying-instance-preference.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="virt-specifying-instance-preference"]
+= Specifying an instance type or preference
+include::_attributes/common-attributes.adoc[]
+:context: virt-specifying-instance-preference
+
+toc::[]
+
+You can specify an instance type, a preference, or both to define a set of workload sizing and runtime characteristics for reuse across multiple VMs.
+
+include::modules/virt-using-flags-specify.adoc[leveloffset=+1]
+
+include::modules/virt-infer-instancetype-preference.adoc[leveloffset=+1]
+
+include::modules/virt-inferfromvolume-labels.adoc[leveloffset=+1]
+