CNV#21150: instance types CLI

modules/virt-about-instance-types.adoc

@@ -0,0 +1,68 @@
+// 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 instance types require defined CPU and memory attributes, {VirtProductName} always rejects additional requests for these resources when creating a VM from an instance type.
+====
+
+.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. Specifies the number of vCPUs to allocate to the guest.
+<2> Required. Specifies an amount of memory to allocate to the guest.
+
+.Example `virtctl` command with required fields
+[source,terminal]
+----
+$ virtctl create instancetype --cpu 2 --memory 256Mi
+----
+
+where: 
+
+`--cpu <value>`:: Specifies the number of vCPUs to allocate to the guest. Required.
+`--memory <value>`:: Specifies an amount of memory to allocate to the guest. Required.
+
+[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`:
+
+`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,82 @@
+// Module included in the following assemblies:
+//
+// * virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.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-cli.adoc

@@ -12,84 +12,46 @@ You can create a virtual machine (VM) from a `VirtualMachine` manifest.
 
 . Edit the `VirtualMachine` manifest for your VM. The following example configures a {op-system-base-full} VM:
 +
+[NOTE]
+====
+This example manifest does not configure VM authentication.
+====
++
 .Example manifest for a {op-system-base} VM
 [source,yaml]
-[%collapsible]
-====
 ----
-apiVersion: kubevirt.io/v1
-kind: VirtualMachine
-metadata:
-  labels:
-    app: <vm_name> <1>
-  name: <vm_name>
-spec:
+ apiVersion: kubevirt.io/v1
+ kind: VirtualMachine
+ metadata:
+  name: rhel-9-minimal
+ spec:
   dataVolumeTemplates:
-  - apiVersion: cdi.kubevirt.io/v1beta1
-    kind: DataVolume
-    metadata:
-      name: <vm_name>
-    spec:
-      sourceRef:
-        kind: DataSource
-        name: rhel9 <2>
-        namespace: openshift-virtualization-os-images
-      storage:
-        resources:
-          requests:
-            storage: 30Gi
-  running: false
+    - metadata:
+        name: rhel-9-minimal-volume
+      spec:
+        sourceRef:
+          kind: DataSource
+          name: rhel9 <1>
+          namespace: openshift-virtualization-os-images <2>
+        storage: {}
+  instancetype:
+    name: u1.medium <3>
+  preference:
+    name: rhel.9 <4>
+  running: true
   template:
-    metadata:
-      labels:
-        kubevirt.io/domain: <vm_name>
     spec:
       domain:
-        cpu:
-          cores: 1
-          sockets: 2
-          threads: 1
-        devices:
-          disks:
-          - disk:
-              bus: virtio
-            name: rootdisk
-          - disk:
-              bus: virtio
-            name: cloudinitdisk
-          interfaces:
-          - masquerade: {}
-            name: default
-          rng: {}
-        features:
-          smm:
-            enabled: true
-        firmware:
-          bootloader:
-            efi: {}
-        resources:
-          requests:
-            memory: 8Gi
-      evictionStrategy: LiveMigrate
-      networks:
-      - name: default
-        pod: {}
+        devices: {}
       volumes:
-      - dataVolume:
-          name: <vm_name>
-        name: rootdisk
-      - cloudInitNoCloud:
-          userData: |-
-            #cloud-config
-            user: cloud-user
-            password: '<password>' <3>
-            chpasswd: { expire: False }
-        name: cloudinitdisk
+        - dataVolume:
+            name: rhel-9-minimal-volume
+          name: rootdisk
 ----
-<1> Specify the name of the virtual machine.
-<2> Specify the name in the `spec.dataImportCronTemplate.spec.managedDataSource` field in the `Hyperconvered` CR.
-<3> Specify the password for cloud-user.
-====
+<1> The `rhel9` golden image is used to install {op-system-base} 9 as the guest operating system.
+<2> Golden images are stored in the `openshift-virtualization-os-images` namespace.
+<3> The `u1.medium` instance type requests 1 vCPU and 4Gi memory for the VM. These resource values cannot be overridden within the VM.
+<4> The `rhel.9` preference specifies additional attributes that support the {op-system-base} 9 guest operating system.
 
 . Create a virtual machine by using the manifest file:
 +

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 `VirtualMachine` (VM) manifest.
+
+|`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, specifying a name for the 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/creating_vms_rh/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

@@ -6,6 +6,20 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can create virtual machines (VMs) from the command line by editing or creating a `VirtualMachine` manifest.
+You can create virtual machines (VMs) from the command line by editing or creating a `VirtualMachine` manifest. You can simplify VM configuration by using an xref:../../../virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc#virt-creating-vms-from-instance-types[instance type] in your VM manifest. 
 
-include::modules/virt-creating-vm-cli.adoc[leveloffset=+1]
+[NOTE]
+====
+You can also xref:../../../virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc#virt-creating-vm-instancetype_virt-creating-vms-from-instance-types[create VMs from instance types by using the web console].
+====
+
+[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].
+
+include::modules/virt-creating-vm-cli.adoc[leveloffset=+1]
+
+.Next steps
+
+* xref:../../../virt/virtual_machines/virt-accessing-vm-ssh.adoc#virt-accessing-vm-ssh[Configuring SSH access to virtual machines]