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 Virtualization → Templates 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 page 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.

You can use the filters in the template Catalog to sort the templates by attributes such as boot source availability, operating system, and workload.

You cannot edit or delete a Red Hat Supported or Red Hat Provided template. You can clone the template, save it as a custom virtual machine template, and then edit it.

You can also create a custom virtual machine template by editing a YAML file example.

Important

Due to differences in storage behavior, some virtual machine templates are incompatible with single-node OpenShift. To ensure compatibility, do not set the evictionStrategy field for any templates or virtual machines that use data volumes or storage profiles.

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 previous 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. Creating a virtual machine 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

  1. In the web console, click Virtualization → Templates in the side menu.
  2. Click Create Template.
  3. Specify the template parameters by editing the YAML file.

  4. Click Create.

    The template is displayed on the Templates page.

  5. Optional: Click Download to download and save the YAML file.

9.1.4. 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 Source available on the Templates page. 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)
  • URL (creates PVC)
  • Clone (creates PVC)
  • 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

  1. In the OpenShift Container Platform console, click Virtualization → Templates from the side menu.
  2. Click the options menu beside a template and select Edit boot source.
  3. Click Add disk.
  4. In the Add disk window, select Use this disk as a boot source.
  5. Enter the disk name and select a Source, for example, Blank (creates PVC) or Use an existing PVC.
  6. 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.
  7. Select a Type, for example, Disk or CD-ROM.

  8. Optional: 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 previous default storage class.

  9. Optional: Clear Apply optimized StorageProfile settings to edit the access mode or volume mode.

  10. Select the appropriate method to save your boot source:

    1. Click Save and upload if you uploaded a local file.
    2. Click Save and import if you imported content from a URL or the registry.
    3. Click Save and clone if you cloned an existing PVC.

Your custom virtual machine template with a boot source is listed on the Catalog page. You can use this template to create a virtual machine.

9.1.4.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 on the Virtualization → Templates page.

NameParameterDescription

Boot source type

Upload local file (creates PVC)

Upload a file from your local device. Supported file types include gz, xz, tar, and qcow2.

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 URL 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.

PVC (creates PVC)

Use a PVC that is already available in the cluster and clone it.

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 settings

StorageClass

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.5. Marking virtual machine templates as favorites

You can mark frequently used templates as favorites.

Procedure

  1. In the OpenShift Container Platform console, click Virtualization → Templates from the side menu.

  2. Click the star icon next to a template to mark it as a favorite.

    Favorite templates are displayed at the top of the template list.

9.1.6. 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

  1. In the OpenShift Virtualization console, click Workloads → Virtualization from the side menu.
  2. Click the Templates tab.
  3. To filter templates, click Filter.
  4. Select the appropriate checkbox from the list to filter the templates: Red Hat Supported, User Supported, Red Hat Provided, and User Provided.

9.1.7. Additional resources

9.2. Editing virtual machine templates

You can edit a virtual machine template in the web console.

Note

You cannot edit a template provided by the Red Hat Virtualization Operator. If you clone the template, you can edit it.

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 next 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

  1. Click Virtualization → Templates from the side menu.
  2. Optional: Use the Filter drop-down menu to sort the list of virtual machine templates by attributes such as status, template, node, or operating system (OS).
  3. Select a virtual machine template to open the Template details page.
  4. Click the pencil icon to make a field editable.
  5. Make the relevant changes and click Save.

Editing a virtual machine template will not affect virtual machines already created from that template.

9.2.1.1. Virtual machine template fields

The following table lists the virtual machine template fields that you can edit in the OpenShift Container Platform web console:

Table 9.1. Virtual machine template fields

TabFields or functionality

Details

  • Labels
  • Annotations
  • Display name
  • Description
  • Workload profile
  • CPU/Memory
  • Boot mode
  • GPU devices
  • Host devices

YAML

  • View, edit, or download the custom resource.

Scheduling

  • Node selector
  • Tolerations
  • Affinity rules
  • Dedicated resources
  • Eviction strategy
  • Descheduler setting

Network Interfaces

  • Add, edit, or delete a network interface.

Disks

  • Add, edit, or delete a disk.

Scripts

  • cloud-init settings

Parameters (optional)

  • Virtual machine name
  • cloud-user password

9.2.1.2. Adding a network interface to a virtual machine template

Use this procedure to add a network interface to a virtual machine template.

Procedure

  1. Click Virtualization → Templates from the side menu.
  2. Select a virtual machine template to open the Template details screen.
  3. Click the Network Interfaces tab.
  4. Click Add Network Interface.
  5. In the Add Network Interface window, specify the Name, Model, Network, Type, and MAC Address of the network interface.
  6. Click Add.

9.2.1.3. Adding a virtual disk to a virtual machine template

Use this procedure to add a virtual disk to a virtual machine template.

Procedure

  1. Click Virtualization → Templates from the side menu.
  2. Select a virtual machine template to open the Template details screen.
  3. Click the Disks tab and then click Add disk.

  4. In the Add disk window, specify the Source, Name, Size, Type, Interface, and Storage Class.

    1. Optional: 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.
    2. Optional: You can clear Apply optimized StorageProfile settings to change 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.
  5. Click Add.

9.2.1.4. Editing CD-ROMs for Templates

Use the following procedure to edit CD-ROMs for virtual machine templates.

Procedure

  1. Click Virtualization → Templates from the side menu.
  2. Select a virtual machine template to open the Template details screen.
  3. Click the Disks tab.
  4. Click the Options menu kebab for the CD-ROM that you want to edit and select Edit.
  5. In the Edit CD-ROM window, edit the fields: Source, Persistent Volume Claim, Name, Type, and Interface.
  6. 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 enable dedicated resources for a virtual machine template in the Details tab. Virtual machines that were created from a Red Hat template can be configured with dedicated resources.

Procedure

  1. In the OpenShift Container Platform console, click Virtualization → Templates from the side menu.
  2. Select a virtual machine template to open the Template details page.
  3. On the Scheduling tab, click the pencil icon beside Dedicated Resources.
  4. Select Schedule this workload with dedicated resources (guaranteed policy).
  5. Click Save.

9.4. Deploying a virtual machine template to a custom namespace

Red Hat provides preconfigured virtual machine templates that are installed in the openshift namespace. The ssp-operator deploys virtual machine templates to the openshift namespace by default. Templates in the openshift namespace are publicly available to all users. These templates are listed on the Virtualization → Templates page for different operating systems.

9.4.1. Creating a custom namespace for templates

You can create a custom namespace that is used to deploy virtual machine templates for use by anyone who has permissions to access those templates. To add templates to a custom namespace, edit the HyperConverged custom resource (CR), add commonTemplatesNamespace to the spec, and specify the custom namespace for the virtual machine templates. After the HyperConverged CR is modified, the ssp-operator populates the templates in the custom namespace.

Prerequisites

  • Install the OpenShift Container Platform CLI oc.
  • Log in as a user with cluster-admin privileges.

Procedure

  • Use the following command to create your custom namespace: 

    $ oc create namespace <mycustomnamespace>

9.4.2. Adding templates to a custom namespace

The ssp-operator deploys virtual machine templates to the openshift namespace by default. Templates in the openshift namespace are publicly availably to all users. When a custom namespace is created and templates are added to that namespace, you can modify or delete virtual machine templates in the openshift namespace. To add templates to a custom namespace, edit the HyperConverged custom resource (CR) which contains the ssp-operator.

Procedure

  1. View the list of virtual machine templates that are available in the openshift namespace. 

    $ oc get templates -n openshift

  2. Edit the HyperConverged CR in your default editor by running the following command: 

    $ oc edit hco -n openshift-cnv kubevirt-hyperconverged

  3. View the list of virtual machine templates that are available in the custom namespace. 

    $ oc get templates -n customnamespace

  4. Add the commonTemplatesNamespace attribute and specify the custom namespace. Example: 

    apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
spec:
  commonTemplatesNamespace: customnamespace 1
    1
    The custom namespace for deploying templates.
  5. Save your changes and exit the editor. The ssp-operator adds virtual machine templates that exist in the default openshift namespace to the custom namespace.

9.4.2.1. Deleting templates from a custom namespace

To delete virtual machine templates from a custom namespace, remove the commonTemplateNamespace attribute from the HyperConverged custom resource (CR) and delete each template from that custom namespace.

Procedure

  1. Edit the HyperConverged CR in your default editor by running the following command: 

    $ oc edit hco -n openshift-cnv kubevirt-hyperconverged

  2. Remove the commonTemplateNamespace attribute. 

    apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
spec:
  commonTemplatesNamespace: customnamespace 1
    1
    The commonTemplatesNamespace attribute to be deleted.

  3. Delete a specific template from the custom namespace that was removed. 

    $ oc delete templates -n customnamespace <template_name>

Verification

  • Verify that the template was deleted from the custom namespace. 

    $ oc get templates -n customnamespace

9.4.2.2. Additional resources

9.5. Deleting virtual machine templates

You can delete customized virtual machine templates based on Red Hat templates by using the web console.

You cannot delete Red Hat templates.

9.5.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 customized virtual machine templates. You cannot delete Red Hat-supplied templates.

Procedure

  1. In the OpenShift Container Platform console, click Virtualization → Templates from the side menu.
  2. Click the Options menu kebab of a template and select Delete template.
  3. Click Delete.