Chapter 6. Creating virtual machines

Procedure

1. Create a VirtualMachine manifest for your VM and save it as a YAML file. For example, to create a minimal Red Hat Enterprise Linux (RHEL) VM, run the following command:

   $ virtctl create vm --name rhel-9-minimal --volume-import type:ds,src:openshift-virtualization-os-images/rhel9

2. Review the VirtualMachine manifest for your VM:

   Note

   This example manifest does not configure VM authentication.

   Example manifest for a RHEL VM

   apiVersion: kubevirt.io/v1
   kind: VirtualMachine
   metadata:
     name: rhel-9-minimal
   spec:
     dataVolumeTemplates:
     - metadata:
         name: imported-volume-mk4lj
       spec:
         sourceRef:
           kind: DataSource
           name: rhel9
           namespace: openshift-virtualization-os-images
         storage:
           resources: {}
     instancetype:
       inferFromVolume: imported-volume-mk4lj
       inferFromVolumeFailurePolicy: Ignore
     preference:
       inferFromVolume: imported-volume-mk4lj
       inferFromVolumeFailurePolicy: Ignore
     runStrategy: Always
     template:
       spec:
         domain:
           devices:
             video:
               type: virtio
           memory:
             guest: 512Mi
           resources: {}
         terminationGracePeriodSeconds: 180
         volumes:
         - dataVolume:
             name: imported-volume-mk4lj
           name: imported-volume-mk4lj

   • name: rhel-9-minimal specifies the name of the VM.
   • name: rhel9 specifies the boot source for the guest operating system in the sourceRef section.
   • namespace: openshift-virtualization-os-images specifies the namespace for the boot source. Golden images are stored in the openshift-virtualization-os-images namespace.
   • instancetype: inferFromVolume: imported-volume-mk4lj specifies the instance type inferred from the selected DataSource object.
   • preference: inferFromVolume: imported-volume-mk4lj specifies that the preference is inferred from the selected DataSource object.
   • type: virtio specifies the use of a custom video device (a VirtIO device in this example) to enable hardware graphics acceleration. Enabling a custom video device is in Technology Preview for OpenShift Virtualization 4.21.

3. Create a virtual machine by using the manifest file:

   $ oc create -f <vm_manifest_file>.yaml

4. Optional: Start the virtual machine:

   $ virtctl start <vm_name>

Procedure

1. Upload the image by running the virtctl image-upload command:

   $ virtctl image-upload dv <datavolume_name> \
     --size=<datavolume_size> \
     --image-path=</path/to/image>

   <datavolume_name>

   The name of the data volume.

   <datavolume_size>

   The size of the data volume. For example: --size=500Mi, --size=1G

   </path/to/image>

   The file path of the image.

   Note

   • If you do not want to create a new data volume, omit the --size parameter and include the --no-create flag.
   • When uploading a disk image to a PVC, the PVC size must be larger than the size of the uncompressed virtual disk.
   • To allow insecure server connections when using HTTPS, use the --insecure parameter. When you use the --insecure flag, the authenticity of the upload endpoint is not verified.

2. Optional. To verify that a data volume was created, view all data volumes by running the following command:

   $ oc get dvs

Procedure

1. Navigate to Virtualization Catalog in the web console.
2. Click a template tile without an available boot source.
3. Click Customize VirtualMachine.
4. On the Customize template parameters page, expand Storage and select URL (creates PVC) from the Disk source list.
5. Enter the image URL. Example: https://access.redhat.com/downloads/content/69/ver=/rhel---7/7.9/x86_64/product-software
6. Set the disk size.
7. Click Next.
8. Click Create VirtualMachine.

Procedure

1. Create a VirtualMachine manifest for your VM and save it as a YAML file. For example, to create a minimal Red Hat Enterprise Linux (RHEL) VM from an image on a web page, run the following command:

   $ virtctl create vm --name vm-rhel-9 --instancetype u1.small --preference rhel.9 --volume-import type:http,url:https://example.com/rhel9.qcow2,size:10Gi

2. Review the VirtualMachine manifest for your VM:

   apiVersion: kubevirt.io/v1
   kind: VirtualMachine
   metadata:
     name: vm-rhel-9
   spec:
     dataVolumeTemplates:
     - metadata:
         name: imported-volume-6dcpf
       spec:
         source:
           http:
             url: https://example.com/rhel9.qcow2
         storage:
           resources:
             requests:
               storage: 10Gi
     instancetype:
       name: u1.small
     preference:
       name: rhel.9
     runStrategy: Always
     template:
       spec:
         domain:
           devices: {}
           resources: {}
         terminationGracePeriodSeconds: 180
         volumes:
         - dataVolume:
             name: imported-volume-6dcpf
           name: imported-volume-6dcpf

   • metadata.name defines the VM name.
   • spec.dataVolumeTemplates.metadata.name defines the data volume name.
   • spec.dataVolumeTemplates.spec.source.http.url defines the URL of the image.
   • spec.dataVolumeTemplates.spec.storage.resources.requests.storage defines the size of the storage requested for the data volume.
   • spec.instancetype.name defines the instance type to use to control resource sizing of the VM.
   • spec.preference.name defines the preference to use.

3. Create the VM by running the following command:

   $ oc create -f <vm_manifest_file>.yaml

   The oc create command creates the data volume and the VM. The CDI controller creates an underlying PVC with the correct annotation and the import process begins. When the import is complete, the data volume status changes to Succeeded. You can start the VM.

   Data volume provisioning happens in the background, so there is no need to monitor the process.

Verification

1. The importer pod downloads the image from the specified URL and stores it on the provisioned persistent volume. View the status of the importer pod:

   $ oc get pods

2. Monitor the status of the data volume:

   $ oc get dv <data_volume_name>

   If the provisioning is successful, the data volume phase is Succeeded.

   Example output:

   NAME                    PHASE       PROGRESS   RESTARTS   AGE
   imported-volume-6dcpf   Succeeded   100.0%                18s

3. Verify that provisioning is complete and that the VM has started by accessing its serial console:

   $ virtctl console <vm_name>

   If the VM is running and the serial console is accessible, the output looks as follows:

   Successfully connected to vm-rhel-9 console. The escape sequence is ^]

Procedure

1. Navigate to Virtualization Catalog in the web console.
2. Click a template tile without an available boot source.
3. Click Customize VirtualMachine.
4. On the Customize template parameters page, expand Storage and select Upload (Upload a new file to a PVC) from the Disk source list.
5. Browse to the image on your local machine and set the disk size.
6. Click Customize VirtualMachine.
7. Click Create VirtualMachine.

Procedure

1. Upload the Windows image as a new PVC:

   1. Navigate to Storage PersistentVolumeClaims in the web console.
   2. Click Create PersistentVolumeClaim With Data upload form.
   3. Browse to the Windows image and select it.

   4. Enter the PVC name, select the storage class and size and then click Upload.

      The Windows image is uploaded to a PVC.

2. Configure a new VM by cloning the uploaded PVC:

   1. Navigate to Virtualization Catalog.
   2. Select a Windows template tile and click Customize VirtualMachine.
   3. Select Clone (clone PVC) from the Disk source list.
   4. Select the PVC project, the Windows image PVC, and the disk size.

3. Apply the answer file to the VM:

   1. Click Customize VirtualMachine parameters.
   2. On the Sysprep section of the Scripts tab, click Edit.
   3. Browse to the autounattend.xml answer file and click Save.

4. Set the run strategy of the VM:

   1. Clear Start this VirtualMachine after creation so that the VM does not start immediately.
   2. Click Create VirtualMachine.
   3. On the YAML tab, replace running:false with runStrategy: RerunOnFailure and click Save.

5. Click the Options menu and select Control Start.

   The VM boots from the sysprep disk containing the autounattend.xml answer file.

Procedure

1. Upload the image by running the virtctl image-upload command:

   $ virtctl image-upload dv <datavolume_name> \
     --size=<datavolume_size> \
     --image-path=</path/to/image>

   <datavolume_name>

   The name of the data volume.

   <datavolume_size>

   The size of the data volume. For example: --size=500Mi, --size=1G

   </path/to/image>

   The file path of the image.

   Note

   • If you do not want to create a new data volume, omit the --size parameter and include the --no-create flag.
   • When uploading a disk image to a PVC, the PVC size must be larger than the size of the uncompressed virtual disk.
   • To allow insecure server connections when using HTTPS, use the --insecure parameter. When you use the --insecure flag, the authenticity of the upload endpoint is not verified.

2. Optional. To verify that a data volume was created, view all data volumes by running the following command:

   $ oc get dvs

Procedure

1. Create a Dockerfile to build the VM image into a container image. The VM image must be owned by QEMU, which has a UID of 107, and placed in the /disk/ directory inside the container. Permissions for the /disk/ directory must then be set to 0440.

   The following example uses the Red Hat Universal Base Image (UBI) to handle these configuration changes in the first stage, and uses the minimal scratch image in the second stage to store the result:

   $ cat > Dockerfile << EOF
   FROM registry.access.redhat.com/ubi8/ubi:latest AS builder
   ADD --chown=107:107 <vm_image>.qcow2 /disk/ //
   RUN chmod 0440 /disk/*
   
   FROM scratch
   COPY --from=builder /disk/* /disk/
   EOF

   where:

   <vm_image>

   Specifies the image in either QCOW2 or RAW format. If you use a remote image, replace <vm_image>.qcow2 with the complete URL.

2. Build and tag the container:

   $ podman build -t <registry>/<container_disk_name>:latest .

3. Push the container image to the registry:

   $ podman push <registry>/<container_disk_name>:latest

Procedure

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

   $ oc edit hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv

2. Add a list of insecure registries to the spec.storageImport.insecureRegistries field.

   Example HyperConverged custom resource:

   apiVersion: hco.kubevirt.io/v1beta1
   kind: HyperConverged
   metadata:
     name: kubevirt-hyperconverged
     namespace: openshift-cnv
   spec:
     storageImport:
       insecureRegistries:
         - "private-registry-example-1:5000"
         - "private-registry-example-2:5000"

   Replace the examples in the insecureRegistries list with valid registry hostnames.

Procedure

1. Navigate to Virtualization Catalog in the web console.
2. Click a template tile without an available boot source.
3. Click Customize VirtualMachine.
4. On the Customize template parameters page, expand Storage and select Registry (creates PVC) from the Disk source list.
5. Enter the container image URL. Example: https://mirror.arizona.edu/fedora/linux/releases/38/Cloud/x86_64/images/Fedora-Cloud-Base-38-1.6.x86_64.qcow2
6. Set the disk size.
7. Click Next.
8. Click Create VirtualMachine.

Procedure

1. Create a VirtualMachine manifest for your VM and save it as a YAML file. For example, to create a minimal Red Hat Enterprise Linux (RHEL) VM from a container disk, run the following command:

   $ virtctl create vm --name vm-rhel-9 --instancetype u1.small --preference rhel.9 --volume-containerdisk src:registry.redhat.io/rhel9/rhel-guest-image:9.5

2. Review the VirtualMachine manifest for your VM:

   apiVersion: kubevirt.io/v1
   kind: VirtualMachine
   metadata:
     name: vm-rhel-9
   spec:
     instancetype:
       name: u1.small
     preference:
       name: rhel.9
     runStrategy: Always
     template:
       metadata:
         creationTimestamp: null
       spec:
         domain:
           devices: {}
           resources: {}
         terminationGracePeriodSeconds: 180
         volumes:
         - containerDisk:
             image: registry.redhat.io/rhel9/rhel-guest-image:9.5
           name: vm-rhel-9-containerdisk-0

   • metadata.name defines the VM name.
   • spec.instancetype.name defines the instance type to use to control resource sizing of the VM.
   • spec.preference.name defines the preference to use.
   • spec.template.spec.volumes.containerDisk.image defines the URL of the container disk.

3. Create the VM by running the following command:

   $ oc create -f <vm_manifest_file>.yaml

Verification

1. Monitor the status of the VM:

   $ oc get vm <vm_name>

   If the provisioning is successful, the VM status is Running. Example output:

   NAME        AGE   STATUS    READY
   vm-rhel-9   18s   Running   True

2. Verify that provisioning is complete and that the VM has started by accessing its serial console:

   $ virtctl console <vm_name>

   If the VM is running and the serial console is accessible, the output looks as follows:

   Successfully connected to vm-rhel-9 console. The escape sequence is ^]

Procedure

1. Navigate to Virtualization Catalog in the web console.
2. Click a template tile without an available boot source.
3. Click Customize VirtualMachine.
4. On the Customize template parameters page, expand Storage and select PVC (clone PVC) from the Disk source list.
5. Select the PVC project and the PVC name.
6. Set the disk size.
7. Click Next.
8. Click Create VirtualMachine.

Procedure

1. In the web console, navigate to Virtualization Catalog.

   The InstanceTypes tab opens by default.

2. Heterogeneous clusters only: To filter the bootable volumes using the options provided, click Architecture.

3. 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 bootable volume quick start. The same link appears in a popover if you hover the pointer over the question mark icon next 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.

4. Click an instance type tile and select the resource size appropriate for your workload. You can select huge pages for Red Hat-provided instance types of the M and CX series. Huge page options are identified by names that end with 1gi.

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

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

     2. Select one of the following options:

        • Use existing: Select a secret from the secrets list.

        • Add new: Follow these steps:

          1. Browse to the public SSH key file or paste the file in the key field.
          2. Enter the secret name.
          3. Optional: Select Automatically apply this key to any new VirtualMachine you create in this project.
     3. 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:

       1. Click the edit icon beside Sysprep in the VirtualMachine details section.
       2. Add the Autoattend.xml answer file.
       3. Add the Unattend.xml answer file.
       4. Click Save.

     • If you want to use existing sysprep options for the Windows volume, follow these steps:

       1. Click Attach existing sysprep.
       2. Enter the name of the existing sysprep Unattend.xml answer file.
       3. Click Save.

6. Optional: If you are creating a Windows VM, you can mount a Windows driver disk:

   1. Click the Customize VirtualMachine button.
   2. On the VirtualMachine details page, click Storage.
   3. Select the Mount Windows drivers disk checkbox.
7. 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.
8. Click Create VirtualMachine.

Procedure

1. From the OpenShift Dedicated web console, choose your view:

   • For a virtualization-focused view, select Administrator Virtualization Catalog.
   • For a general view, navigate to Virtualization Catalog.
2. Click the Template catalog tab.
3. Click the Boot source available checkbox to filter templates with boot sources. The catalog displays the default templates.
4. Heterogeneous clusters only: To filter the search results to show templates associated with a particular architecture, click Architecture Type .

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

6. 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:

     1. Click Customize VirtualMachine. The Customize and create VirtualMachine page displays the Overview, YAML, Scheduling, Environment, Network interfaces, Disks, Scripts, and Metadata tabs.
     2. 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).
     3. Optional: Click the Start this virtualmachine after creation (Always) checkbox.

     4. Click Create VirtualMachine.

        The VirtualMachine details page displays the provisioning status.

Procedure

1. Navigate to Virtualization Templates in the web console.
2. From the list of VM templates, click the template marked as deprecated.
3. Click Edit next to the pencil icon beside Labels.

4. Remove the following two labels:

   • template.kubevirt.io/type: "base"
   • template.kubevirt.io/version: "version"
5. Click Save.
6. Click the pencil icon beside the number of existing Annotations.

7. Remove the following annotation:

   • template.kubevirt.io/deprecated
8. Click Save.

Procedure

1. In the web console, select Virtualization Settings.
2. On the Cluster tab, select General settings Templates and images management.
3. Click Bootable volumes project.

4. Select a namespace to use for boot source images.

   1. If you already created a namespace, select it from the Project list.

   2. If you did not create a namespace, scroll to the bottom of the list and click Create project.

      1. Enter a name for your new namespace in the Name field of the Create project dialog.
      2. Click Create.

Procedure

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

   $ oc edit hyperconvergeds.v1beta1.hco.kubevirt.io kubevirt-hyperconverged -n openshift-cnv

2. Configure the custom namespace by updating the value of the spec.commonBootImageNamespace field.

   Example configuration file:

   apiVersion: hco.kubevirt.io/v1beta1
   kind: HyperConverged
   metadata:
     name: kubevirt-hyperconverged
     namespace: openshift-cnv
   spec:
     commonBootImageNamespace: <custom_namespace>
   # ...

   where:

   spec.commonBootImageNamespace

   Specifies the namespace to use for boot source images.

3. Save your changes and exit the editor.

Procedure

1. Navigate to Virtualization VirtualMachines in the web console.
2. Select a VM to open the VirtualMachine details page.

3. Click Actions.

   Alternatively, access the same menu in the tree view by right-clicking the VM.

4. Select Clone.
5. On the Clone VirtualMachine page, enter the name of the new VM.
6. Optional: Select the Start cloned VM checkbox to start the cloned VM.

7. Optional: In the Volume name policy section, select how cloned persistent volume claims (PVCs) are named:

   • Randomize names - The cloned PVC names are randomly generated. This is the default setting.
   • Prefix target name - The cloned PVC names use the target VM name as a prefix.
8. Click Clone.

Procedure

1. Navigate to Virtualization VirtualMachines in the web console.
2. Select a VM to open the VirtualMachine details page.
3. Click the Snapshots tab.
4. Click the Options menu for the snapshot you want to copy.
5. Select Create VirtualMachine.
6. Enter the name of the VM.
7. Optional: Select the Start this VM after creation checkbox to start the new VM.

8. Optional: In the Volume name policy section, select how cloned persistent volume claims (PVCs) are named:

   • Randomize names - The cloned PVC names are randomly generated. This is the default setting.
   • Prefix target name - The cloned PVC names use the target VM name as a prefix.
9. Click Create.