Chapter 9. Virtual machine templates
Chapter 9. Virtual machine templates 9.1. Creating virtual machine templates 9.1.1. About virtual machine templates Preconfigured Red Hat virtual machine templates are listed in the Templates tab within the Virtualization page. These templates are available for different versions of Red Hat Enterprise Linux, Fedora, Microsoft Windows 10, and Microsoft Windows Servers. Each Red Hat virtual machine template is preconfigured with the operating system image, default settings for the operating system, flavor (CPU and memory), and workload type (server). The Templates tab displays four types of virtual machine templates: Red Hat Supported templates are fully supported by Red Hat. User Supported templates are Red Hat Supported templates that were cloned and created by users. Red Hat Provided templates have limited support from Red Hat. User Provided templates are Red Hat Provided templates that were cloned and created by users. Note In the Templates tab, you cannot edit or delete Red Hat Supported or Red Hat Provided templates. You can only edit or delete custom virtual machine templates that were created by users. Using a Red Hat template is convenient because the template is already preconfigured. When you select a Red Hat template to create your own custom template, the Create Virtual Machine Template wizard prompts you to add a boot source if a boot source was not added previously. Then, you can either save your custom template or continue to customize it and save it. You can also select the Create Virtual Machine Template wizard directly and create a custom virtual machine template. The wizard prompts you to provide configuration details for the operating system, flavor, workload type, and other settings. You can add a boot source and continue to customize your template and save it. 9.1.2. About virtual machines and boot sources Virtual machines consist of a virtual machine definition and one or more disks that are backed by data volumes. Virtual machine templates enable you to create virtual machines using predefined virtual machine specifications. Every virtual machine template requires a boot source, which is a fully configured virtual machine disk image including configured drivers. Each virtual machine template contains a virtual machine definition with a pointer to the boot source. Each boot source has a predefined name and namespace. For some operating systems, a boot source is automatically provided. If it is not provided, then an administrator must prepare a custom boot source. Provided boot sources are updated automatically to the latest version of the operating system. For auto-updated boot sources, persistent volume claims (PVCs) are created with the cluster's default storage class. If you select a different default storage class after configuration, you must delete the existing data volumes in the cluster namespace that are configured with the default storage class. To use the boot sources feature, install the latest release of OpenShift Virtualization. The namespace openshift-virtualization-os-images enables the feature and is installed with the OpenShift Virtualization Operator. Once the boot source feature is installed, you can create boot sources, attach them to templates, and create virtual machines from the templates. Define a boot source by using a persistent volume claim (PVC) that is populated by uploading a local file, cloning an existing PVC, importing from a registry, or by URL. Attach a boot source to a virtual machine template by using the web console. After the boot source is attached to a virtual machine template, you create any number of fully configured ready-to-use virtual machines from the template. 9.1.3. Adding a boot source for a virtual machine template A boot source can be configured for any virtual machine template that you want to use for creating virtual machines or custom templates. When virtual machine templates are configured with a boot source, they are labeled Available in the Templates tab. After you add a boot source to a template, you can create a new virtual machine from the template. There are four methods for selecting and adding a boot source in the web console: Upload local file (creates PVC) Import via URL (creates PVC) Clone existing PVC (creates PVC) Import via Registry (creates PVC) Prerequisites To add a boot source, you must be logged in as a user with the os-images.kubevirt.io:edit RBAC role or as an administrator. You do not need special privileges to create a virtual machine from a template with a boot source added. To upload a local file, the operating system image file must exist on your local machine. To import via URL, access to the web server with the operating system image is required. For example: the Red Hat Enterprise Linux web page with images. To clone an existing PVC, access to the project with a PVC is required. To import via registry, access to the container registry is required. Procedure In the OpenShift Virtualization console, click Workloads Virtualization from the side menu. Click the Templates tab. Identify the virtual machine template for which you want to configure a boot source and click Add source . In the Add boot source to template window, click Select boot source , select a method for creating a persistent volume claim (PVC): Upload local file , Import via URL , Clone existing PVC , or Import via Registry . Optional: Click This is a CD-ROM boot source to mount a CD-ROM and use it to install the operating system on to an empty disk. The additional empty disk is automatically created and mounted by OpenShift Virtualization. If the additional disk is not needed, you can remove it when you create the virtual machine. Enter a value for Persistent Volume Claim size to specify the PVC size that is adequate for the uncompressed image and any additional space that is required. Optional: Enter a name for Source provider to associate the name with this template. Optional: Advanced Storage settings : Click Storage class and select the storage class that is used to create the disk. Typically, this storage class is the default storage class that is created for use by all PVCs. Note Provided boot sources are updated automatically to the latest version of the operating system. For auto-updated boot sources, persistent volume claims (PVCs) are created with the cluster's default storage class. If you select a different default storage class after configuration, you must delete the existing data volumes in the cluster namespace that are configured with the default storage class. Optional: Advanced Storage settings : Click Access mode and select an access mode for the persistent volume: Single User (RWO) mounts the volume as read-write by a single node. Shared Access (RWX) mounts the volume as read-write by many nodes. Read Only (ROX) mounts the volume as read-only by many nodes. Optional: Advanced Storage settings : Click Volume mode if you want to select Block instead of the default value Filesystem . OpenShift Virtualization can statically provision raw block volumes. These volumes do not have a file system, and can provide performance benefits for applications that either write to the disk directly or implement their own storage service. Select the appropriate method to save your boot source: Click Save and upload if you uploaded a local file. Click Save and import if you imported content from a URL or the registry. Click Save and clone if you cloned an existing PVC. Your custom virtual machine template with a boot source is listed in the Templates tab, and you can create virtual machines by using this template. 9.1.3.1. Virtual machine template fields for adding a boot source The following table describes the fields for Add boot source to template window. This window displays when you click Add Source for a virtual machine template in the Templates tab. Name Parameter Description Boot source type Upload local file (creates PVC) Upload a file from your local device. Supported file types include gz, xz, tar, and qcow2. Import via URL (creates PVC) Import content from an image available from an HTTP or HTTPS endpoint. Obtain the download link URL from the web page where the image download is available and enter that URL link in the Import via URL (creates PVC) field. Example: For a Red Hat Enterprise Linux image, log on to the Red Hat Customer Portal, access the image download page, and copy the download link URL for the KVM guest image. Clone existing PVC (creates PVC) Use a PVC that is already available in the cluster and clone it. Import via Registry (creates PVC) Specify the bootable operating system container that is located in a registry and accessible from the cluster. Example: kubevirt/cirros-registry-dis-demo. Source provider Optional field. Add descriptive text about the source for the template or the name of the user who created the template. Example: Red Hat. Advanced Storage class The storage class that is used to create the disk. Access mode Access mode of the persistent volume. Supported access modes are Single User (RWO) , Shared Access (RWX) , Read Only (ROX) . If Single User (RWO) is selected, the disk can be mounted as read/write by a single node. If Shared Access (RWX) is selected, the disk can be mounted as read-write by many nodes. The kubevirt-storage-class-defaults config map provides access mode defaults for data volumes. The default value is set according to the best option for each storage class in the cluster. + Note Shared Access (RWX) is required for some features, such as live migration of virtual machines between nodes. Volume mode Defines whether the persistent volume uses a formatted file system or raw block state. Supported modes are Block and Filesystem . The kubevirt-storage-class-defaults config map provides volume mode defaults for data volumes. The default value is set according to the best option for each storage class in the cluster. 9.1.4. Marking virtual machine templates as favorites For easier access to virtual machine templates that are used frequently, you can mark those templates as favorites. Procedure In the OpenShift Virtualization console, click Workloads Virtualization from the side menu. Click the Templates tab. Identify the Red Hat template that you want to mark as a favorite. Click the Options menu and select Favorite template . The template moves up higher in the list of displayed templates. 9.1.5. Filtering the list of virtual machine templates by providers In the Templates tab, you can use the Search by name field to search for virtual machine templates by specifying either the name of the template or a label that identfies the template. You can also filter templates by the provider, and display only those templates that meet your filtering criteria. Procedure In the OpenShift Virtualization console, click Workloads Virtualization from the side menu. Click the Templates tab. To filter templates, click Filter . Select the appropriate checkbox from the list to filter the templates: Red Hat Supported , User Supported , Red Hat Provided , and User Provided . 9.1.6. Creating a virtual machine template with the wizard in the web console The web console features the Create Virtual Machine Template wizard that guides you through the General , Networking , Storage , Advanced , and Review steps to simplify the process of creating virtual machine templates. All required fields are marked with a *. The Create Virtual Machine Template wizard prevents you from moving to the step until you provide values in the required fields. Note The wizard guides you to create a custom virtual machine template where you specify the operating system, boot source, flavor, and other settings. Procedure In the OpenShift Virtualization console, click Workloads Virtualization from the side menu. Click the Templates tab. Click Create and select Template with Wizard . Fill in all required fields in the General step. Click to progress to the Networking step. A NIC that is named nic0 is attached by default. Optional: Click Add Network Interface to create additional NICs. Optional: You can remove any or all NICs by clicking the Options menu and selecting Delete . Virtual machines created from a template do not need a NIC attached. NICs can be created after a virtual machine has been created. Click to progress to the Storage step. Click Add Disk to add a disk, and complete your selections for the fields in the Add Disk screen. Note If Import via URL (creates PVC) , Import via Registry (creates PVC) , or Container (ephemeral) is selected as Source , a rootdisk disk is created and attached to the virtual machine as the Bootable Disk . A Bootable Disk is not required for virtual machines provisioned from a PXE source if there are no disks attached to the virtual machine. If one or more disks are attached to the virtual machine, you must select one as the Bootable Disk . Blank disks, PVC disks without a valid boot source, and the cloudinitdisk cannot be used as a boot source. Optional: Click Advanced to configure cloud-init and SSH access. Note Statically inject an SSH key by using the custom script in cloud-init or in the wizard. This allows you to securely and remotely manage virtual machines and manage and transfer information. This step is strongly recommended to secure your VM. Click Review to review and confirm your settings. Click Create Virtual Machine template . Click See virtual machine template details to view details about the virtual machine template. The template is also listed in the Templates tab. 9.1.7. Virtual machine template wizard fields The following tables describe the fields for the General , Networking , Storage , and Advanced steps in the Create Virtual Machine Template wizard. 9.1.7.1. Virtual machine template wizard fields Name Parameter Description Template Template from which to create the virtual machine. Selecting a template will automatically complete other fields. Name The name can contain lowercase letters ( a-z ), numbers ( 0-9 ), and hyphens ( - ), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, periods ( . ), or special characters. Template provider The name of the user who is creating the template for the cluster or any meaningful name that identifies this template. Template support No additional support This template does not have additional support in the cluster. Support by template provider This template is supported by the template provider. Description Optional description field. Operating System The operating system that is selected for the virtual machine. Selecting an operating system automatically selects the default Flavor and Workload Type for that operating system. Boot Source Import via URL (creates PVC) Import content from an image available from an HTTP or HTTPS endpoint. Example: Obtaining a URL link from the web page with the operating system image. Clone existing PVC (creates PVC) Select an existent persistent volume claim available on the cluster and clone it. Import via Registry (creates PVC) Provision virtual machine from a bootable operating system container located in a registry accessible from the cluster. Example: kubevirt/cirros-registry-disk-demo . PXE (network boot - adds network interface) Boot an operating system from a server on the network. Requires a PXE bootable network attachment definition. Persistent Volume Claim project Project name that you want to use for cloning the PVC. Persistent Volume Claim name PVC name that should apply to this virtual machine template if you are cloning an existing PVC. Mount this as a CD-ROM boot source A CD-ROM requires an additional disk for installing the operating system. Select the checkbox to add a disk and customize it later. Flavor Tiny, Small, Medium, Large, Custom Presets the amount of CPU and memory in a virtual machine template with predefined values that are allocated to the virtual machine, depending on the operating system associated with that template. If you choose a default template, you can override the cpus and memsize values in the template using custom values to create a custom template. Alternatively, you can create a custom template by modifying the cpus and memsize values in the Details tab on the Workloads Virtualization page. Workload Type Note If you choose the incorrect Workload Type , there could be performance or resource utilization issues (such as a slow UI). Desktop A virtual machine configuration for use on a desktop. Ideal for consumption on a small scale. Recommended for use with the web console. Use this template class or the Server template class to prioritize VM density over guaranteed VM performance. Server Balances performance and it is compatible with a wide range of server workloads. Use this template class or the Desktop template class to prioritize VM density over guaranteed VM performance. High-Performance (requires CPU Manager) A virtual machine configuration that is optimized for high-performance workloads. Use this template class to prioritize guaranteed VM performance over VM density. 9.1.7.2. Networking fields Name Description Name Name for the network interface controller. Model Indicates the model of the network interface controller. Supported values are e1000e and virtio . Network List of available network attachment definitions. Type List of available binding methods. For the default pod network, masquerade is the only recommended binding method. For secondary networks, use the bridge binding method. The masquerade method is not supported for non-default networks. Select SR-IOV if you configured an SR-IOV network device and defined that network in the namespace. MAC Address MAC address for the network interface controller. If a MAC address is not specified, one is assigned automatically. 9.1.7.3. Storage fields Name Selection Description Source Blank (creates PVC) Create an empty disk. Import via URL (creates PVC) Import content via URL (HTTP or HTTPS endpoint). Use an existing PVC Use a PVC that is already available in the cluster. Clone existing PVC (creates PVC) Select an existing PVC available in the cluster and clone it. Import via Registry (creates PVC) Import content via container registry. Container (ephemeral) Upload content from a container located in a registry accessible from the cluster. The container disk should be used only for read-only filesystems such as CD-ROMs or temporary virtual machines. Name Name of the disk. The name can contain lowercase letters ( a-z ), numbers ( 0-9 ), hyphens ( - ), and periods ( . ), up to a maximum of 253 characters. The first and last characters must be alphanumeric. The name must not contain uppercase letters, spaces, or special characters. Size Size of the disk in GiB. Type Type of disk. Example: Disk or CD-ROM Interface Type of disk device. Supported interfaces are virtIO , SATA , and SCSI . Storage Class The storage class that is used to create the disk. Advanced storage settings The following advanced storage settings are optional and available for Blank , Import via URL , and Clone existing PVC disks. Before OpenShift Virtualization 4.11, if you do not specify these parameters, the system uses the default values from the kubevirt-storage-class-defaults config map. In OpenShift Virtualization 4.11 and later, the system uses the default values from the storage profile . Note Use storage profiles to ensure consistent advanced storage settings when provisioning storage for OpenShift Virtualization. To manually specify Volume Mode and Access Mode , you must clear the Apply optimized StorageProfile settings checkbox, which is selected by default. Name Mode description Parameter Parameter description Volume Mode Defines whether the persistent volume uses a formatted file system or raw block state. Default is Filesystem . Filesystem Stores the virtual disk on a file system-based volume. Block Stores the virtual disk directly on the block volume. Only use Block if the underlying storage supports it. Access Mode Access mode of the persistent volume. ReadWriteOnce (RWO) Volume can be mounted as read-write by a single node. ReadWriteMany (RWX) Volume can be mounted as read-write by many nodes at one time. Note This is required for some features, such as live migration of virtual machines between nodes. ReadOnlyMany (ROX) Volume can be mounted as read only by many nodes. 9.1.7.4. Cloud-init fields Name Description Hostname Sets a specific hostname for the virtual machine. Authorized SSH Keys The user's public key that is copied to ~/.ssh/authorized_keys on the virtual machine. Custom script Replaces other options with a field in which you paste a custom cloud-init script. 9.1.8. Additional resources Creating and using boot sources Customizing the storage profile 9.2. Editing virtual machine templates You can update a virtual machine template in the web console, either by editing the full configuration in the YAML editor or by selecting a custom template in the Templates tab and modifying the editable items. 9.2.1. Editing a virtual machine template in the web console Edit select values of a virtual machine template in the web console by clicking the pencil icon to the relevant field. Other values can be edited using the CLI. Labels and annotations are editable for both preconfigured Red Hat templates and your custom virtual machine templates. All other values are editable only for custom virtual machine templates that users have created using the Red Hat templates or the Create Virtual Machine Template wizard. Procedure Click Workloads Virtualization from the side menu. Click the Templates tab. Select a virtual machine template. Click the VM Template Details tab. Click the pencil icon to make a field editable. Make the relevant changes and click Save . Editing a virtual machine template will not affect virtual machines already created from that template. 9.2.2. Editing virtual machine template YAML configuration in the web console You can edit the YAML configuration of a virtual machine template from the web console. Some parameters cannot be modified. If you click Save with an invalid configuration, an error message indicates the parameter that cannot be modified. Note Navigating away from the YAML screen while editing cancels any changes to the configuration that you made. Procedure In the OpenShift Virtualization console, click Workloads Virtualization from the side menu. Click the Templates tab. Select a template to open the VM Template Details screen. Click the YAML tab to display the editable configuration. Edit the file and click Save . A confirmation message, which includes the updated version number for the object, shows that the YAML configuration was successfully edited. 9.2.3. Adding a virtual disk to a virtual machine template Use this procedure to add a virtual disk to a virtual machine template. Procedure Click Workloads Virtualization from the side menu. Click the Templates tab. Select a virtual machine template to open the VM Template Details screen. Click the Disks tab. In the Add Disk window, specify the Source , Name , Size , Type , Interface , and Storage Class . Advanced: You can enable preallocation if you use a blank disk source and require maximum write performance when creating data volumes. To do so, select the Enable preallocation checkbox. Optional: In the Advanced list, specify the Volume Mode and Access Mode for the virtual disk. If you do not specify these parameters, the system uses the default values from the kubevirt-storage-class-defaults config map. Click Add . 9.2.4. Adding a network interface to a virtual machine template Use this procedure to add a network interface to a virtual machine template. Procedure Click Workloads Virtualization from the side menu. Click the Templates tab. Select a virtual machine template to open the VM Template Details screen. Click the Network Interfaces tab. Click Add Network Interface . In the Add Network Interface window, specify the Name , Model , Network , Type , and MAC Address of the network interface. Click Add . 9.2.5. Editing CD-ROMs for Templates Use the following procedure to edit CD-ROMs for virtual machine templates. Procedure Click Workloads Virtualization from the side menu. Click the Templates tab. Select a virtual machine template to open the VM Template Details screen. Click the Disks tab. Click the Options menu for the CD-ROM that you want to edit and select Edit . In the Edit CD-ROM window, edit the fields: Source , Persistent Volume Claim , Name , Type , and Interface . Click Save . 9.3. Enabling dedicated resources for virtual machine templates Virtual machines can have resources of a node, such as CPU, dedicated to them to improve performance. 9.3.1. About dedicated resources When you enable dedicated resources for your virtual machine, your virtual machine's workload is scheduled on CPUs that will not be used by other processes. By using dedicated resources, you can improve the performance of the virtual machine and the accuracy of latency predictions. 9.3.2. Prerequisites The CPU Manager must be configured on the node. Verify that the node has the cpumanager = true label before scheduling virtual machine workloads. 9.3.3. Enabling dedicated resources for a virtual machine template You can enable dedicated resources for a virtual machine template in the Details tab. Virtual machines that were created by using a Red Hat template or the wizard can be enabled with dedicated resources. Procedure Click Workloads Virtual Machine Templates from the side menu. Select a virtual machine template to open the Virtual Machine Template tab. Click the Details tab. Click the pencil icon to the right of the Dedicated Resources field to open the Dedicated Resources window. Select Schedule this workload with dedicated resources (guaranteed policy) . Click Save . 9.4. Deleting a virtual machine template Red Hat virtual machine templates cannot be deleted. You can use the web console to delete: Virtual machine templates created from Red Hat templates Custom virtual machine templates that were created by using the Create Virtual Machine Template wizard. 9.4.1. Deleting a virtual machine template in the web console Deleting a virtual machine template permanently removes it from the cluster. Note You can delete virtual machine templates that were created by using a Red Hat template or the Create Virtual Machine Template wizard. Preconfigured virtual machine templates that are provided by Red Hat cannot be deleted. Procedure In the OpenShift Virtualization console, click Workloads Virtualization from the side menu. Click the Templates tab. Select the appropriate method to delete a virtual machine template: Click the Options menu of the template to delete and select Delete Template . Click the template name to open the Virtual Machine Template Details screen and click Actions Delete Template . In the confirmation pop-up window, click Delete to permanently delete the template.