OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Creating virtual machine templates

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.

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.

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.

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

  1. In the OpenShift Virtualization console, click Workloads → Virtualization from the side menu.

  2. Click the Templates tab.

  3. Identify the virtual machine template for which you want to configure a boot source and click Add source.

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

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

  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.

    1. Optional: Enter a name for Source provider to associate the name with this template.

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

      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.

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

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

  7. 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 in the Templates tab, and you can create virtual machines by using this template.

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.

+

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.

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

  1. In the OpenShift Virtualization console, click Workloads → Virtualization from the side menu.

  2. Click the Templates tab.

  3. Identify the Red Hat template that you want to mark as a favorite.

  4. Click the Options menu kebab and select Favorite template. The template moves up higher in the list of displayed templates.

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.

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 next step until you provide values in the required fields.

The wizard guides you to create a custom virtual machine template where you specify the operating system, boot source, flavor, and other settings.
Procedure

  1. In the OpenShift Virtualization console, click Workloads → Virtualization from the side menu.

  2. Click the Templates tab.

  3. Click Create and select Template with Wizard.

  4. Fill in all required fields in the General step.

  5. Click Next to progress to the Networking step. A NIC that is named nic0 is attached by default.

    1. Optional: Click Add Network Interface to create additional NICs.

    2. Optional: You can remove any or all NICs by clicking the Options menu kebab 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.

  6. Click Next to progress to the Storage step.

  7. Click Add Disk to add a disk, and complete your selections for the fields in the Add Disk screen.

    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.

  8. Optional: Click Advanced to configure cloud-init and SSH access.

    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. 

  9. Click Review to review and confirm your settings.

  10. Click Create Virtual Machine template.

  11. Click See virtual machine template details to view details about the virtual machine template.

The template is also listed in the Templates tab.

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.

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

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.

Server

Balances performance and it is compatible with a wide range of server workloads.

High-Performance

A virtual machine configuration that is optimized for high-performance workloads.

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.

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 → Volume Mode

Defines whether the persistent volume uses a formatted file system or raw block state. Default is Filesystem.

Advanced → Access Mode

Access mode of the persistent volume. Supported access modes are Single User (RWO), Shared Access (RWX), and Read Only (ROX).

Advanced storage settings

The following advanced storage settings are available for Blank, Import via URL, and Clone existing PVC disks. These parameters are optional. If you do not specify these parameters, the system uses the default values from the kubevirt-storage-class-defaults config map.

Name Parameter Description

Volume Mode

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

Single User (RWO)

The disk can be mounted as read/write by a single node.

Shared Access (RWX)

The disk can be mounted as read/write by many nodes.

This is required for some features, such as live migration of virtual machines between nodes.

Read Only (ROX)

The disk can be mounted as read-only by many nodes.

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.

Additional resources