CNV#21150: instance types CLI

modules/virt-about-instance-types.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="virt-about-instance-types_{context}"]
+= About instance types
+
+An instance type is a reusable object where you can define resources and characteristics to apply to new VMs. You can define custom instance types or use the variety that are included when you install {VirtProductName}. You can create instance types by using YAML files or the `virtctl` CLI tool.
+
+{VirtProductName} provides two CRDs for configuring instance types: 
+
+* A namespaced object: `VirtualMachineInstancetype`
+* A cluster-wide object: `VirtualMachineClusterInstancetype`
+
+These objects use the same `VirtualMachineInstancetypeSpec`.
+
+[id="required-attributes_{context}"]
+== Required attributes
+
+When you configure an instance type, you must define the `cpu` and `memory` attributes. Other attributes are optional. 
+
+[NOTE]
+====
+When you create a VM from an instance type, you cannot override any parameters defined in the instance type. 
+
+Because CPU and memory resources must be defined in an instance type, requests for these resources are always rejected.
+====
+
+.Example YAML file with required fields
+[source,yaml]
+----
+apiVersion: instancetype.kubevirt.io/v1beta1
+kind: VirtualMachineInstancetype
+metadata:
+  name: example-instancetype
+spec:
+  cpu:
+    guest: 1 <1>
+  memory:
+    guest: 128Mi <2>
+----
+<1> Required. The number of vCPUs to allocate to the guest.
+<2> Required. The amount of memory to allocate to the guest.
+
+.Example `virtctl` command with required fields
+[source,terminal]
+----
+$ virtctl create instancetype --cpu 2 --memory 256Mi
+----
+
+[id="optional-attributes_{context}"]
+== Optional attributes
+
+In addition to the required `cpu` and `memory` attributes, you can include the following optional attributes in the `VirtualMachineInstancetypeSpec`:
+
+[%collapsible]
+--
+`annotations`:: List annotations to apply to the VM.
+`gpus`:: List vGPUs for passthrough.
+`hostDevices`:: List host devices for passthrough.
+`ioThreadsPolicy`:: Define an IO threads policy for managing dedicated disk access.
+`launchSecurity`:: Configure Secure Encrypted Virtualization (SEV).
+`nodeSelector`:: Specify node selectors to control the nodes where this VM is scheduled.
+`schedulerName`:: Define a custom scheduler to use for this VM instead of the default scheduler.
+--

modules/virt-common-instancetypes.adoc

@@ -0,0 +1,83 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc
+// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-cli.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="virt-common-instancetypes_{context}"]
+= Pre-defined instance types 
+
+{VirtProductName} includes a set of pre-defined instance types called `common-instancetypes`. Some are specialized for specific workloads and others are workload-agnostic.
+
+These instance type resources are named according to their series, version, and size. The size value follows the `.` delimiter and ranges from `nano` to `8xlarge`.
+
+.`common-instancetypes` series comparison
+
+[cols="2a,1a,2a,1a,2a"][%collapsible]
+|===
+^.^|Use case ^.^|Series ^.^|Characteristics ^.^|vCPU to memory ratio ^.^|Example resource
+
+^.^|Universal
+^.^|U 
+a| 
+* Burstable CPU performance
+^.^|1:4
+.^a|`u1.medium`:: 
+* 1 vCPUs
+* 4 Gi memory
+
+^.^|Overcommitted
+^.^|O
+a| 
+* Overcommitted memory
+* Burstable CPU performance
+^.^|1:4
+.^a|`o1.small`::
+* 1 vCPU
+* 2Gi memory
+
+^.^|Compute-exclusive
+^.^|CX
+a| 
+* Hugepages
+* Dedicated CPU
+* Isolated emulator threads
+* vNUMA
+^.^|1:2
+.^a|`cx1.2xlarge`::
+* 8 vCPUs
+* 16Gi memory
+
+^.^|NVIDIA GPU
+^.^|GN
+a|
+* For VMs that use GPUs provided by the NVIDIA GPU Operator
+* Has predefined GPUs
+* Burstable CPU performance
+^.^|1:4
+.^a|`gn1.8xlarge`::
+* 32 vCPUs
+* 128Gi memory
+
+^.^|Memory-intensive
+^.^|M 
+a| 
+* Hugepages
+* Burstable CPU performance
+^.^|1:8
+.^a|`m1.large`::
+* 2 vCPUs
+* 16Gi memory
+
+^.^|Network-intensive
+^.^|N
+a| 
+* Hugepages
+* Dedicated CPU
+* Isolated emulator threads
+* Requires nodes capable of running DPDK workloads
+^.^|1:2
+.^a|`n1.medium`::
+* 4 vCPUs
+* 4Gi memory
+|===

modules/virt-creating-vm-instancetype.adoc

@@ -18,7 +18,7 @@ endif::[]
 
 :_mod-docs-content-type: PROCEDURE
 [id="virt-creating-vm-instancetype_{context}"]
-= {title} from an instance type
+= {title} from an instance type by using the web console
 
 ifdef::virt-create-vms[]
 You can create a virtual machine (VM) from an instance type by using the {product-title} web console. You can also use the web console to create a VM by copying an existing snapshot or to clone a VM.

modules/virt-virtctl-commands.adoc

@@ -57,6 +57,41 @@ You can use `virtctl` to view information about virtual machines (VMs) and virtu
 |View the logged-in users on a guest machine.
 |===
 
+[id="vm-manifest-creation-commands_{context}"]
+== VM manifest creation commands
+
+You can use `virtctl create` commands to create manifests for virtual machines, instance types, and preferences.
+
+.VM manifest creation commands
+[width="100%",cols="2a,1a",options="header"]
+|===
+|Command |Description
+
+|`virtctl create vm`::
+|Create a manifest for a `VirtualMachine` (VM).
+
+|`virtctl create vm --name <vm_name>`
+|Create a VM manifest, specifying a name for the VM.
+
+|`virtctl create vm --instancetype <instancetype_name>`
+|Create a VM manifest that uses an existing cluster-wide instance type.
+
+|`virtctl create vm --instancetype=virtualmachineinstancetype/<instancetype_name>`
+|Create a VM manifest that uses an existing namespaced instance type.
+
+|`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name>`
+|Create a manifest for a cluster-wide instance type.
+
+|`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name> --namespace <namespace_value>`
+|Create a manifest for a namespaced instance type.
+
+|`virtctl create preference --name <preference_name>`
+|Create a manifest for a cluster-wide VM preference.
+
+|`virtctl create preference --namespace <namespace_value>`
+|Create a manifest for a namespaced VM preference.
+|===
+
 [id='vm-management-commands_{context}']
 == VM management commands
 
@@ -67,9 +102,6 @@ You use `virtctl` virtual machine (VM) management commands to manage and migrate
 |===
 |Command |Description
 
-|`virtctl create -name <vm_name>`
-|Create a `VirtualMachine` manifest.
-
 |`virtctl start <vm_name>`
 |Start a VM.
 
@@ -96,12 +128,6 @@ You use `virtctl` virtual machine (VM) management commands to manage and migrate
 
 |`virtctl restart <vm_name>`
 |Restart a VM.
-
-|`virtctl create instancetype --cpu <cpu_value> --memory <memory_value> --name <instancetype_name>`
-|Create an `InstanceType` manifest for a `ClusterInstanceType`, or a namespaced `InstanceType`, to streamline the creation of your `InstanceType` specifications.
-
-|`virtctl create preference --name <preference_name>`
-|Create a `Preference` manifest for a `ClusterPreference`, or a namespaced `Preference`, to streamline the creation of your `Preference` specifications.
 |===
 
 [id='vm-connection-commands_{context}']

virt/getting_started/virt-getting-started.adoc

@@ -49,10 +49,7 @@ Create a virtual machine (VM):
 * xref:../../virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-rh-images-overview.adoc#virt-creating-vms-from-rh-images-overview[Create a VM from a Red Hat image].
 ifndef::openshift-rosa,openshift-dedicated[]
 +
-You can create a VM by using a Red Hat template or an instance type.
-+
-:FeatureName: Creating a VM from an instance type
-include::snippets/technology-preview.adoc[]
+You can create a VM by using a Red Hat template or an xref:../../virt/virtual_machines/virt-creating-vms-from-instance-types.adoc#virt-creating-vms-from-instance-types[instance type].
 endif::openshift-rosa,openshift-dedicated[]
 ifdef::openshift-rosa,openshift-dedicated[]
 +

virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-cli.adoc

@@ -8,4 +8,12 @@ toc::[]
 
 You can create virtual machines (VMs) from the command line by editing or creating a `VirtualMachine` manifest.
 
+[id="creating-manifests-virtctl_{context}"]
+== Creating manifests by using the virtctl tool
+
+You can use the `virtctl` CLI utility to simplify creating manifests for VMs, VM instance types, and VM preferences. For more information, see xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-manifest-creation-commands_virt-using-the-cli-tools[VM manifest creation commands].
+
+.Additional resources
+* xref:../../virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc#virt-creating-vms-from-instance-types[Creating VMs from instance types]
+
 include::modules/virt-creating-vm-cli.adoc[leveloffset=+1]

virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc

@@ -6,13 +6,25 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can create virtual machines (VMs) from instance types by using the {product-title} web console.
+You can simplify virtual machine (VM) creation by using instance types, whether you use the {product-title} web console or the CLI to create VMs.
 
+// special TP note for ROSA only:
 ifdef::openshift-rosa,openshift-dedicated[]
 [NOTE]
 ====
-Creating a VM from an instance type in {VirtProductName} 4.15 and higher is supported for use on {product-title} clusters. In {VirtProductName} 4.14, creating a VM from an instance type is a Technology Preview feature and is not supported for use on {product-title} clusters.
+Creating a VM from an instance type in {VirtProductName} 4.15 and higher is supported on {product-title} clusters. In {VirtProductName} 4.14, creating a VM from an instance type is a Technology Preview feature and is not supported on {product-title} clusters.
 ====
 endif::openshift-rosa,openshift-dedicated[]
 
+include::modules/virt-about-instance-types.adoc[leveloffset=+1]
+
+include::modules/virt-common-instancetypes.adoc[leveloffset=+1]
+
+[id="creating-manifests-virtctl_{context}"]
+== Creating manifests by using the virtctl tool
+
+You can use the `virtctl` CLI utility to simplify creating manifests for VMs, VM instance types, and VM preferences. For more information, see xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-manifest-creation-commands_virt-using-the-cli-tools[VM manifest creation commands].
+
+When you have a `VirtualMachine` manifest, you can create a VM from the xref:../../virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-cli.adoc#virt-creating-vms-from-cli[command line].
+
 include::modules/virt-creating-vm-instancetype.adoc[leveloffset=+1]