Uploading a local disk image to a block storage persistent volume claim

You can upload a local disk image into a block persistent volume claim (PVC) by using the virtctl command-line utility.

In this workflow, you create a local block device to use as a persistent volume, associate this block volume with an upload data volume, and use virtctl to upload the local disk image into the PVC.

Prerequisites

• Install virtctl.

• You might need to define a storage class or prepare CDI scratch space for this operation to complete successfully.

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). You can create a data volume as either a standalone resource or by using the dataVolumeTemplate field in the virtual machine (VM) specification.

After a PVC is populated, the data volume that you used to create the PVC is no longer needed. OKD Virtualization enables automatic garbage collection of completed data volumes by default. Standalone data volumes, and data volumes created by using the dataVolumeTemplate resource, are automatically garbage collected after completion.

About block persistent volumes

A block persistent volume (PV) is a PV that is backed by a raw block device. These volumes do not have a file system and can provide performance benefits for virtual machines by reducing overhead.

Raw block volumes are provisioned by specifying volumeMode: Block in the PV and persistent volume claim (PVC) specification.

Creating a local block persistent volume

If you intend to import a virtual machine image into block storage with a data volume, you must have an available local block persistent volume.

Create a local block persistent volume (PV) on a node by populating a file and mounting it as a loop device. You can then reference this loop device in a PV manifest as a Block volume and use it as a block device for a virtual machine image.

Procedure

1. Log in as root to the node on which to create the local PV. This procedure uses node01 for its examples.

2. Create a file and populate it with null characters so that it can be used as a block device. The following example creates a file loop10 with a size of 2Gb (20 100Mb blocks):

   $ dd if=/dev/zero of=<loop10> bs=100M count=20

3. Mount the loop10 file as a loop device.

   $ losetup </dev/loop10>d3 <loop10>  (1) (2)

   1	File path where the loop device is mounted.
   2	The file created in the previous step to be mounted as the loop device.

4. Create a PersistentVolume manifest that references the mounted loop device.

   kind: PersistentVolume
   apiVersion: v1
   metadata:
     name: <local-block-pv10>
     annotations:
   spec:
     local:
       path: </dev/loop10> (1)
     capacity:
       storage: <2Gi>
     volumeMode: Block (2)
     storageClassName: local (3)
     accessModes:
       - ReadWriteOnce
     persistentVolumeReclaimPolicy: Delete
     nodeAffinity:
       required:
         nodeSelectorTerms:
         - matchExpressions:
           - key: kubernetes.io/hostname
             operator: In
             values:
             - <node01> (4)

   1	The path of the loop device on the node.
   2	Specifies it is a block PV.
   3	Optional: Set a storage class for the PV. If you omit it, the cluster default is used.
   4	The node on which the block device was mounted.

5. Create the block PV.

   # oc create -f <local-block-pv10.yaml>(1)

   1	The file name of the persistent volume created in the previous step.

Creating an upload data volume

You can manually create a data volume with an upload data source to use for uploading local disk images.

Procedure

1. Create a data volume configuration that specifies spec: source: upload{}:

   apiVersion: cdi.kubevirt.io/v1beta1
   kind: DataVolume
   metadata:
     name: <upload-datavolume> (1)
   spec:
     source:
         upload: {}
     pvc:
       accessModes:
         - ReadWriteOnce
       resources:
         requests:
           storage: <2Gi> (2)

   1	The name of the data volume.
   2	The size of the data volume. Ensure that this value is greater than or equal to the size of the disk that you upload.

2. Create the data volume by running the following command:

   $ oc create -f <upload-datavolume>.yaml

Uploading a local disk image to a data volume

You can use the virtctl CLI utility to upload a local disk image from a client machine to a data volume (DV) in your cluster. You can use a DV that already exists in your cluster or create a new DV during this procedure.

Prerequisites

• You must have one of the following:

  • A raw virtual machine image file in either ISO or IMG format.

  • A virtual machine image file in QCOW2 format.

• For best results, compress your image file according to the following guidelines before you upload it:

  • Compress a raw image file by using xz or gzip.

    Using a compressed raw image file results in the most efficient upload.

  • Compress a QCOW2 image file by using the method that is recommended for your client:

    • If you use a Linux client, sparsify the QCOW2 file by using the virt-sparsify tool.

    • If you use a Windows client, compress the QCOW2 file by using xz or gzip.

• The kubevirt-virtctl package must be installed on the client machine.

• The client machine must be configured to trust the OKD router’s certificate.

Procedure

1. Identify the following items:

   • The name of the upload data volume that you want to use. If this data volume does not exist, it is created automatically.

   • The size of the data volume, if you want it to be created during the upload procedure. The size must be greater than or equal to the size of the disk image.

   • The file location of the virtual machine disk image that you want to upload.

2. Upload the disk image by running the virtctl image-upload command. Specify the parameters that you identified in the previous step. For example:

   $ virtctl image-upload dv <datavolume_name> \ (1)
   --size=<datavolume_size> \ (2)
   --image-path=</path/to/image> \ (3)

   1	The name of the data volume.
   2	The size of the data volume. For example: —size=500Mi, —size=1G
   3	The file path of the virtual machine disk image.

   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. Be aware that when you use the —insecure flag, the authenticity of the upload endpoint is not verified.

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

   $ oc get dvs

CDI supported operations matrix

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

✓ Supported operation

□ Unsupported operation

* Requires scratch space

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

Additional resources

• Configure preallocation mode to improve write performance for data volume operations.