Importing virtual machine images with data volumes

Use the Containerized Data Importer (CDI) to import a virtual machine image into a persistent volume claim (PVC) by using a data volume. You can attach a data volume 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. See the operating system documentation for details.

Prerequisites

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 typesHTTPHTTPSHTTP basic authRegistryUpload

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*

✓ Supported operation

□ Unsupported operation

* Requires scratch space

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

CDI now uses the OKD cluster-wide proxy configuration.

About data volumes

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

Importing a virtual machine image into storage by using a data volume

You can import a virtual machine image into storage by using a data volume.

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.

You specify the data source for the image in a VirtualMachine configuration file. When the virtual machine is created, the data volume with the virtual machine image is imported into storage.

Prerequisites

  • 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 or HTTPS endpoint where the image is hosted, along with any authentication credentials needed to access the data source.

  • To import a container disk, you must have a virtual machine image built into a container disk and stored in a container registry, along with any authentication credentials needed to access the data source.

  • If the virtual machine must communicate with servers that use self-signed certificates or certificates not signed by the system CA bundle, you must create a config map in the same namespace as the data volume.

Procedure

  1. If your data source requires authentication, create a Secret manifest, specifying the data source credentials, and save it as endpoint-secret.yaml:

    1. apiVersion: v1
    2. kind: Secret
    3. metadata:
    4. name: endpoint-secret (1)
    5. labels:
    6. app: containerized-data-importer
    7. type: Opaque
    8. data:
    9. accessKeyId: "" (2)
    10. secretKey: "" (3)
    1Specify the name of the Secret.
    2Specify the Base64-encoded key ID or user name.
    3Specify the Base64-encoded secret key or password.
  2. Apply the Secret manifest:

    1. $ oc apply -f endpoint-secret.yaml
  3. Edit the VirtualMachine manifest, specifying the data source for the virtual machine image you want to import, and save it as vm-fedora-datavolume.yaml:

    Details

    1. apiVersion: kubevirt.io/v1
    2. kind: VirtualMachine
    3. metadata:
    4. creationTimestamp: null
    5. labels:
    6. kubevirt.io/vm: vm-fedora-datavolume
    7. name: vm-fedora-datavolume (1)
    8. spec:
    9. dataVolumeTemplates:
    10. - metadata:
    11. creationTimestamp: null
    12. name: fedora-dv (2)
    13. spec:
    14. storage:
    15. resources:
    16. requests:
    17. storage: 10Gi
    18. storageClassName: local
    19. source:
    20. http: (3)
    21. url: "https://mirror.arizona.edu/fedora/linux/releases/35/Cloud/x86_64/images/Fedora-Cloud-Base-35-1.2.x86_64.qcow2" (4)
    22. secretRef: endpoint-secret (5)
    23. certConfigMap: "" (6)
    24. status: {}
    25. running: true
    26. template:
    27. metadata:
    28. creationTimestamp: null
    29. labels:
    30. kubevirt.io/vm: vm-fedora-datavolume
    31. spec:
    32. domain:
    33. devices:
    34. disks:
    35. - disk:
    36. bus: virtio
    37. name: datavolumedisk1
    38. machine:
    39. type: ""
    40. resources:
    41. requests:
    42. memory: 1.5Gi
    43. terminationGracePeriodSeconds: 180
    44. volumes:
    45. - dataVolume:
    46. name: fedora-dv
    47. name: datavolumedisk1
    48. status: {}
    1Specify the name of the virtual machine.
    2Specify the name of the data volume.
    3Specify http for an HTTP or HTTPS endpoint. Specify registry for a container disk image imported from a registry.
    4Specify the URL or registry endpoint of the virtual machine image you want to import. This example references a virtual machine image at an HTTPS endpoint. An example of a container registry endpoint is url: “docker://kubevirt/fedora-cloud-container-disk-demo:latest”.
    5Specify the Secret name if you created a Secret for the data source.
    6Optional: Specify a CA certificate config map.
  4. Create the virtual machine:

    1. $ oc create -f vm-fedora-datavolume.yaml

    The oc create command creates the data volume and the virtual machine. 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 virtual machine.

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

Verification

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

    1. $ oc get pods
  2. Monitor the data volume until its status is Succeeded by running the following command:

    1. $ oc describe dv fedora-dv (1)
    1Specify the data volume name that you defined in the VirtualMachine manifest.
  3. Verify that provisioning is complete and that the virtual machine has started by accessing its serial console:

    1. $ virtctl console vm-fedora-datavolume

Additional resources