Chapter 7. Creating a virtual machine
Chapter 7. Creating a virtual machine 7.1. Creating virtual machines from instance types You can simplify virtual machine (VM) creation by using instance types, whether you use the OpenShift Container Platform web console or the CLI to create VMs. 7.1.1. 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 OpenShift Virtualization. To create a new instance type, you must first create a manifest, either manually or by using the virtctl CLI tool. You then create the instance type object by applying the manifest to your cluster. OpenShift Virtualization provides two CRDs for configuring instance types: A namespaced object: VirtualMachineInstancetype A cluster-wide object: VirtualMachineClusterInstancetype These objects use the same VirtualMachineInstancetypeSpec . 7.1.1.1. 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, OpenShift Virtualization always rejects additional requests for these resources when creating a VM from an instance type. You can manually create an instance type manifest. For example: Example YAML file with required fields 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. You can create an instance type manifest by using the virtctl CLI utility. For example: Example virtctl command with required fields USD 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. Tip You can immediately create the object from the new manifest by running the following command: USD virtctl create instancetype --cpu 2 --memory 256Mi | oc apply -f - 7.1.1.2. 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. 7.1.2. Pre-defined instance types OpenShift Virtualization 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 . Table 7.1. common-instancetypes series comparison Use case Series Characteristics vCPU to memory ratio Example resource Network N Hugepages Dedicated CPU Isolated emulator threads Requires nodes capable of running DPDK workloads 1:2 n1.medium 4 vCPUs 4GiB Memory Overcommitted O Overcommitted memory Burstable CPU performance 1:4 o1.small 1 vCPU 2GiB Memory Compute Exclusive CX Hugepages Dedicated CPU Isolated emulator threads vNUMA 1:2 cx1.2xlarge 8 vCPUs 16GiB Memory General Purpose U Burstable CPU performance 1:4 u1.medium 1 vCPU 4GiB Memory Memory Intensive M Hugepages Burstable CPU performance 1:8 m1.large 2 vCPUs 16GiB Memory 7.1.3. Specifying an instance type or preference 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. 7.1.3.1. 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: USD 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: USD virtctl create vm --instancetype virtualmachineinstancetype/<my_instancetype> --preference virtualmachinepreference/<my_preference> 7.1.3.2. 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 VM, use the --infer-instancetype flag. To explicitly infer preferences, use the --infer-preference flag. The following command includes both flags: USD virtctl create vm --volume-import type:pvc,src:my-ns/my-pvc --infer-instancetype --infer-preference To infer an instance type or preference from a volume other than the volume used to boot the VM, use the --infer-instancetype-from and --infer-preference-from flags to specify any of the virtual machine's volumes. In the example below, the virtual machine boots from volume-a but infers the instancetype and preference from volume-b . USD virtctl create vm \ --volume-import=type:pvc,src:my-ns/my-pvc-a,name:volume-a \ --volume-import=type:pvc,src:my-ns/my-pvc-b,name:volume-b \ --infer-instancetype-from volume-b \ --infer-preference-from volume-b 7.1.3.3. 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: USD oc label DataSource foo instancetype.kubevirt.io/default-instancetype=<my_instancetype> 7.1.4. Creating a VM from an instance type by using the web console You can create a virtual machine (VM) from an instance type by using the OpenShift Container Platform web console. You can also use the web console to create a VM by copying an existing snapshot or to clone a VM. You can create a VM from a list of available bootable volumes. You can add Linux- or Windows-based volumes to the list. Procedure In the web console, navigate to Virtualization Catalog . The InstanceTypes tab opens by default. Select either of the following options: Select a suitable bootable volume from the list. If the list is truncated, click the Show all button to display the entire list. Note The bootable volume table lists only those volumes in the openshift-virtualization-os-images namespace that have the instancetype.kubevirt.io/default-preference label. Optional: Click the star icon to designate a bootable volume as a favorite. Starred bootable volumes appear first in the volume list. Click Add volume to upload a new volume or to use an existing persistent volume claim (PVC), a volume snapshot, or a containerDisk volume. Click Save . Logos of operating systems that are not available in the cluster are shown at the bottom of the list. You can add a volume for the required operating system by clicking the Add volume link. In addition, there is a link to the Create a Windows boot source quick start. The same link appears in a popover if you hover the pointer over the question mark icon to the Select volume to boot from line. Immediately after you install the environment or when the environment is disconnected, the list of volumes to boot from is empty. In that case, three operating system logos are displayed: Windows, RHEL, and Linux. You can add a new volume that meets your requirements by clicking the Add volume button. Click an instance type tile and select the resource size appropriate for your workload. Optional: Choose the virtual machine details, including the VM's name, that apply to the volume you are booting from: For a Linux-based volume, follow these steps to configure SSH: If you have not already added a public SSH key to your project, click the edit icon beside Authorized SSH key in the VirtualMachine details section. Select one of the following options: Use existing : Select a secret from the secrets list. Add new : Follow these steps: Browse to the public SSH key file or paste the file in the key field. Enter the secret name. Optional: Select Automatically apply this key to any new VirtualMachine you create in this project . Click Save . For a Windows volume, follow either of these set of steps to configure sysprep options: If you have not already added sysprep options for the Windows volume, follow these steps: Click the edit icon beside Sysprep in the VirtualMachine details section. Add the Autoattend.xml answer file. Add the Unattend.xml answer file. Click Save . If you want to use existing sysprep options for the Windows volume, follow these steps: Click Attach existing sysprep . Enter the name of the existing sysprep Unattend.xml answer file. Click Save . Optional: If you are creating a Windows VM, you can mount a Windows driver disk: Click the Customize VirtualMachine button. On the VirtualMachine details page, click Storage . Select the Mount Windows drivers disk checkbox. Optional: Click View YAML & CLI to view the YAML file. Click CLI to view the CLI commands. You can also download or copy either the YAML file contents or the CLI commands. Click Create VirtualMachine . After the VM is created, you can monitor the status on the VirtualMachine details page. 7.1.5. Changing the instance type of a VM You can change the instance type associated with a running virtual machine (VM) by using the web console. The change takes effect immediately. Prerequisites You created the VM by using an instance type. Procedure In the OpenShift Container Platform web console, click Virtualization VirtualMachines . Select a VM to open the VirtualMachine details page. Click the Configuration tab. On the Details tab, click the instance type text to open the Edit Instancetype dialog. For example, click 1 CPU | 2 GiB Memory . Edit the instance type by using the Series and Size lists. Select an item from the Series list to show the relevant sizes for that series. For example, select General Purpose . Select the VM's new instance type from the Size list. For example, select medium: 1 CPUs, 4Gi Memory , which is available in the General Purpose series. Click Save . Verification Click the YAML tab. Click Reload . Review the VM YAML to confirm that the instance type changed. 7.2. Creating virtual machines from templates You can create virtual machines (VMs) from Red Hat templates by using the OpenShift Container Platform web console. 7.2.1. About VM templates You can use VM templates to help you easily create VMs. Expedite creation with boot sources You can expedite VM creation by using templates that have an available boot source. Templates with a boot source are labeled Available boot source if they do not have a custom label. Templates without a boot source are labeled Boot source required . See Managing automatic boot source updates for details. Customize before starting the VM You can customize the disk source and VM parameters before you start the VM. Note If you copy a VM template with all its labels and annotations, your version of the template is marked as deprecated when a new version of the Scheduling, Scale, and Performance (SSP) Operator is deployed. You can remove this designation. See Removing a deprecated designation from a customized VM template by using the web console . Single-node OpenShift Due to differences in storage behavior, some templates are incompatible with single-node OpenShift. To ensure compatibility, do not set the evictionStrategy field for templates or VMs that use data volumes or storage profiles. 7.2.2. Creating a VM from a template You can create a virtual machine (VM) from a template with an available boot source by using the OpenShift Container Platform web console. You can customize template or VM parameters, such as data sources, Cloud-init, or SSH keys, before you start the VM. You can choose between two views in the web console to create the VM: A virtualization-focused view, which provides a concise list of virtualization-related options at the top of the view A general view, which provides access to the various web console options, including Virtualization Procedure From the OpenShift Container Platform web console, choose your view: For a virtualization-focused view, select Administrator Virtualization Catalog . For a general view, navigate to Virtualization Catalog . Click the Template catalog tab. Click the Boot source available checkbox to filter templates with boot sources. The catalog displays the default templates. Click All templates to view the available templates for your filters. To focus on particular templates, enter the keyword in the Filter by keyword field. Choose a template project from the All projects dropdown menu, or view all projects. Click a template tile to view its details. Optional: If you are using a Windows template, you can mount a Windows driver disk by selecting the Mount Windows drivers disk checkbox. If you do not need to customize the template or VM parameters, click Quick create VirtualMachine to create a VM from the template. If you need to customize the template or VM parameters, do the following: Click Customize VirtualMachine . The Customize and create VirtualMachine page displays the Overview , YAML , Scheduling , Environment , Network interfaces , Disks , Scripts , and Metadata tabs. Click the Scripts tab to edit the parameters that must be set before the VM boots, such as Cloud-init , SSH key , or Sysprep (Windows VM only). Optional: Click the Start this virtualmachine after creation (Always) checkbox. Click Create VirtualMachine . The VirtualMachine details page displays the provisioning status. 7.2.2.1. Removing a deprecated designation from a customized VM template by using the web console You can customize an existing virtual machine (VM) template by modifying the VM or template parameters, such as data sources, cloud-init, or SSH keys, before you start the VM. If you customize a template by copying it and including all of its labels and annotations, the customized template is marked as deprecated when a new version of the Scheduling, Scale, and Performance (SSP) Operator is deployed. You can remove the deprecated designation from the customized template. Procedure Navigate to Virtualization Templates in the web console. From the list of VM templates, click the template marked as deprecated. Click Edit to the pencil icon beside Labels . Remove the following two labels: template.kubevirt.io/type: "base" template.kubevirt.io/version: "version" Click Save . Click the pencil icon beside the number of existing Annotations . Remove the following annotation: template.kubevirt.io/deprecated Click Save . 7.2.2.2. Creating a custom VM template in the web console You create a virtual machine template by editing a YAML file example in the OpenShift Container Platform web console. Procedure In the web console, click Virtualization Templates in the side menu. Optional: Use the Project drop-down menu to change the project associated with the new template. All templates are saved to the openshift project by default. Click Create Template . Specify the template parameters by editing the YAML file. Click Create . The template is displayed on the Templates page. Optional: Click Download to download and save the YAML file.
apiVersion: instancetype.kubevirt.io/v1beta1 kind: VirtualMachineInstancetype metadata: name: example-instancetype spec: cpu: guest: 1 1 memory: guest: 128Mi 2 virtctl create instancetype --cpu 2 --memory 256Mi virtctl create instancetype --cpu 2 --memory 256Mi | oc apply -f - virtctl create vm --instancetype <my_instancetype> --preference <my_preference> virtctl create vm --instancetype virtualmachineinstancetype/<my_instancetype> --preference virtualmachinepreference/<my_preference> virtctl create vm --volume-import type:pvc,src:my-ns/my-pvc --infer-instancetype --infer-preference virtctl create vm --volume-import=type:pvc,src:my-ns/my-pvc-a,name:volume-a --volume-import=type:pvc,src:my-ns/my-pvc-b,name:volume-b --infer-instancetype-from volume-b --infer-preference-from volume-b oc label DataSource foo instancetype.kubevirt.io/default-instancetype=<my_instancetype>