Importing virtual machine images with DataVolumes - Virtual machines | OpenShift Virtualization

Prerequisites
CDI supported operations matrix
About DataVolumes
Importing a virtual machine image into a PersistentVolumeClaim by using a DataVolume

Use the Containerized Data Importer (CDI) to import a virtual machine image into a PersistentVolumeClaim (PVC) by using a DataVolume. You can attach a DataVolume to a virtual machine for persistent storage.

The virtual machine image can be hosted at an HTTP or HTTPS endpoint, or built into a container disk and stored in a container registry.

When you import a disk image into a PVC, the disk image is expanded to use the full storage capacity that is requested in the PVC. To use this space, the disk partitions and file system(s) in the virtual machine might need to be expanded.

The resizing procedure varies based on the operating system installed on the virtual machine. Refer to the operating system documentation for details.

Prerequisites

If the endpoint requires a TLS certificate, the certificate must be included in a configmap in the same namespace as the DataVolume and referenced in the DataVolume configuration.
To import a container disk:
- You might need to prepare a container disk from a virtual machine image and store it in your container registry before importing it.
- If the container registry does not have TLS, you must add the registry to the cdi-insecure-registries configmap before you can import a container disk from it.
You might need to define a StorageClass or prepare CDI scratch space for this operation to complete successfully.

CDI supported operations matrix

This matrix shows the supported CDI operations for content types against endpoints, and which of these operations requires scratch space.

Content types	HTTP	HTTPS	HTTP basic auth	Registry	Upload
KubeVirt(QCOW2)	✓ QCOW2 ✓ GZ* ✓ XZ*	✓ QCOW2** ✓ GZ* ✓ XZ*	✓ QCOW2 ✓ GZ* ✓ XZ*	✓ QCOW2* □ GZ □ XZ	✓ QCOW2* ✓ GZ* ✓ XZ*
KubeVirt (RAW)	✓ RAW ✓ GZ ✓ XZ	✓ RAW ✓ GZ ✓ XZ	✓ RAW ✓ GZ ✓ XZ	✓ RAW* □ GZ □ XZ	✓ RAW* ✓ GZ* ✓ XZ*

Content types

HTTP

HTTPS

HTTP basic auth

Registry

Upload

KubeVirt(QCOW2)

✓ QCOW2
✓ GZ*
✓ XZ*

✓ QCOW2**
✓ GZ*
✓ XZ*

✓ QCOW2
✓ GZ*
✓ XZ*

✓ QCOW2*
□ GZ
□ XZ

✓ QCOW2*
✓ GZ*
✓ XZ*

KubeVirt (RAW)

✓ RAW
✓ GZ
✓ XZ

✓ RAW*
□ GZ
□ XZ

✓ RAW*
✓ GZ*
✓ XZ*

✓ Supported operation

□ Unsupported operation

* Requires scratch space

** Requires scratch space if a custom certificate authority is required

About DataVolumes

DataVolume objects are custom resources that are provided by the Containerized Data Importer (CDI) project. DataVolumes orchestrate import, clone, and upload operations that are associated with an underlying PersistentVolumeClaim (PVC). DataVolumes are integrated with KubeVirt, and they prevent a virtual machine from being started before the PVC has been prepared.

Importing a virtual machine image into a PersistentVolumeClaim by using a DataVolume

You can import a virtual machine image into a PersistentVolumeClaim (PVC) by using a DataVolume.

The virtual machine image can be hosted at an HTTP or HTTPS endpoint, or the image can be built into a container disk and stored in a container registry.

To create a virtual machine from an imported virtual machine image, specify the image or container disk endpoint in the VirtualMachine configuration file before you create the virtual machine.

Prerequisites

You have installed the OpenShift CLI (oc).
Your cluster has at least one available PersistentVolume.
To import a virtual machine image you must have the following:
- A virtual machine disk image in RAW, ISO, or QCOW2 format, optionally compressed by using xz or gz.
- An HTTP endpoint where the image is hosted, along with any authentication credentials needed to access the data source. For example: http://www.example.com/path/to/data
To import a container disk you must have the following:
- A container disk built from a virtual machine image stored in your container image registry, along with any authentication credentials needed to access the data source. For example: docker://registry.example.com/container-image

Procedure

Optional: If your data source requires authentication credentials, edit the endpoint-secret.yaml file, and apply the updated configuration to the cluster:
```
apiVersion: v1
kind: Secret
metadata:
  name: <endpoint-secret>
  labels:
    app: containerized-data-importer
type: Opaque
data:
  accessKeyId: "" (1)
  secretKey:   "" (2)
```
1 Optional: your key or user name, base64 encoded

2 Optional: your secret or password, base64 encoded
```
$ oc apply -f endpoint-secret.yaml
```

Edit the virtual machine configuration file, specifying the data source for the virtual machine image you want to import. In this example, a Fedora image is imported from an http source:

apiVersion: kubevirt.io/v1alpha3
kind: VirtualMachine
metadata:
  creationTimestamp: null
  labels:
    kubevirt.io/vm: vm-fedora-datavolume
  name: vm-fedora-datavolume
spec:
  dataVolumeTemplates:
  - metadata:
      creationTimestamp: null
      name: fedora-dv
    spec:
      pvc:
        accessModes:
        - ReadWriteOnce
        resources:
          requests:
            storage: 10Gi
        storageClassName: local
      source:
        http: (1)
          url: "https://download.fedoraproject.org/pub/fedora/linux/releases/33/Cloud/x86_64/images/Fedora-Cloud-Base-33-1.2.x86_64.qcow2" (2)
          secretRef: "" (3)
          certconfigmap: "" (4)
    status: {}
  running: true
  template:
    metadata:
      creationTimestamp: null
      labels:
        kubevirt.io/vm: vm-fedora-datavolume
    spec:
      domain:
        devices:
          disks:
          - disk:
              bus: virtio
            name: datavolumedisk1
        machine:
          type: "" (5)
        resources:
          requests:
            memory: 1.5Gi
      terminationGracePeriodSeconds: 60
      volumes:
      - dataVolume:
          name: fedora-dv
        name: datavolumedisk1
status: {}

1	The source type to import the image from. This example uses an HTTP endpoint. To import a container disk from a registry, replace `http` with `registry`.
2	The source of the virtual machine image you want to import. This example references a virtual machine image at an HTTP endpoint. An example of a container registry endpoint is `url: "docker://kubevirt/fedora-cloud-container-disk-demo:latest"`.
3	The `secretRef` parameter is optional.
4	The `certconfigmap` is required for communicating with servers that use self-signed certificates or certificates not signed by the system CA bundle. The referenced configmap must be in the same namespace as the DataVolume.
5	Specify `type: dataVolume` or `type: ""`. If you specify any other value for `type`, such as `persistentVolumeClaim`, a warning is displayed, and the virtual machine does not start.

Create the virtual machine:

$ oc create -f vm-<name>-datavolume.yaml

The oc create command creates the DataVolume and the virtual machine. The CDI controller creates an underlying PVC with the correct annotation, and the import process begins. When the import completes, the DataVolume status changes to Succeeded, and the virtual machine is allowed to start.

DataVolume provisioning happens in the background, so there is no need to monitor it. You can start the virtual machine, and it will not run until the import is complete.

Verification

The importer Pod downloads the virtual machine image or container disk from the specified URL and stores it on the provisioned PV. View the status of the importer Pod by running the following command:
```
$ oc get pods
```
Monitor the DataVolume status until it shows Succeeded by running the following command:
```
$ oc describe dv <datavolume-name> (1)
```
1 The name of the DataVolume as specified under dataVolumeTemplates.metadata.name in the virtual machine configuration file. In the example configuration above, this is fedora-dv.
To verify that provisioning is complete and that the VMI has started, try accessing its serial console by running the following command:
```
$ virtctl console <vm-fedora-datavolume>
```

1	Optional: your key or user name, base64 encoded
2	Optional: your secret or password, base64 encoded