diff --git a/modules/virt-about-instance-types.adoc b/modules/virt-about-instance-types.adoc new file mode 100644 index 000000000000..7b97416f1c4d --- /dev/null +++ b/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. +-- diff --git a/modules/virt-common-instancetypes.adoc b/modules/virt-common-instancetypes.adoc new file mode 100644 index 000000000000..8434df1bd206 --- /dev/null +++ b/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 +|=== \ No newline at end of file diff --git a/modules/virt-creating-vm-instancetype.adoc b/modules/virt-creating-vm-instancetype.adoc index 367d3571edb1..a9c1d0c42de5 100644 --- a/modules/virt-creating-vm-instancetype.adoc +++ b/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. diff --git a/modules/virt-virtctl-commands.adoc b/modules/virt-virtctl-commands.adoc index 983b2995b7c3..6a5f22bc80c2 100644 --- a/modules/virt-virtctl-commands.adoc +++ b/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 ` +|Create a VM manifest, specifying a name for the VM. + +|`virtctl create vm --instancetype ` +|Create a VM manifest that uses an existing cluster-wide instance type. + +|`virtctl create vm --instancetype=virtualmachineinstancetype/` +|Create a VM manifest that uses an existing namespaced instance type. + +|`virtctl create instancetype --cpu --memory --name ` +|Create a manifest for a cluster-wide instance type. + +|`virtctl create instancetype --cpu --memory --name --namespace ` +|Create a manifest for a namespaced instance type. + +|`virtctl create preference --name ` +|Create a manifest for a cluster-wide VM preference. + +|`virtctl create preference --namespace ` +|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 ` -|Create a `VirtualMachine` manifest. - |`virtctl start ` |Start a VM. @@ -96,12 +128,6 @@ You use `virtctl` virtual machine (VM) management commands to manage and migrate |`virtctl restart ` |Restart a VM. - -|`virtctl create instancetype --cpu --memory --name ` -|Create an `InstanceType` manifest for a `ClusterInstanceType`, or a namespaced `InstanceType`, to streamline the creation of your `InstanceType` specifications. - -|`virtctl create 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}'] diff --git a/virt/getting_started/virt-getting-started.adoc b/virt/getting_started/virt-getting-started.adoc index d81dc9e29e21..66eb9d5ff553 100644 --- a/virt/getting_started/virt-getting-started.adoc +++ b/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[] + diff --git a/virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-cli.adoc b/virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-cli.adoc index 230745eaad2e..5205801e30de 100644 --- a/virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-cli.adoc +++ b/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] \ No newline at end of file diff --git a/virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc b/virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc index 5b27c242cf20..123d7bee0e05 100644 --- a/virt/virtual_machines/creating_vms_rh/virt-creating-vms-from-instance-types.adoc +++ b/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]