Configure Image Upload and VM Export
Virtual Machine Orchestrator (VMO) can expose the Containerized Data Importer (CDI) upload proxy and the KubeVirt export
proxy so that you can upload disk images with virtctl image-upload and export virtual machine disks with
virtctl vmexport. This page explains how to expose these proxies through native Ingress or LoadBalancer Services,
upload an Ubuntu disk image, create a virtual machine from the uploaded disk, and export that disk.
In VMO pack version 4.10.7 and later, the directAccess Traefik route no longer exposes the CDI upload proxy or the
KubeVirt export proxy. Expose both proxies through the Ingress or LoadBalancer configuration on this page. If you use
Direct mode, keep directAccess enabled, because Direct mode still uses it for the VM
dashboard route.
Prerequisites
-
A workload cluster with VMO pack version 4.10.7 or later deployed. Refer to Create a VMO Profile for guidance.
-
Kubectl installed and access to the kubeconfig file for the VMO cluster. Refer to the Kubectl guide to learn how to set up
kubectland get the kubeconfig file. Export its path so that the commands on this page can use it, and run the commands in the same terminal session.export KUBECONFIG=<path-to-kubeconfig>Replace
<path-to-kubeconfig>with the path to the kubeconfig file for the VMO cluster. -
The virtctl command-line tool installed on your workstation.
-
An Ubuntu cloud image on your workstation, such as
ubuntu-24.04-server-cloudimg-amd64.imgfrom Ubuntu Cloud Images. -
To export a virtual machine disk, the following permissions in the
virtual-machinesnamespace.-
create,get, anddeleteonvirtualmachineexports.export.kubevirt.io. -
geton Secrets, because the export token is stored in a Secret. -
geton the source virtual machine, PersistentVolumeClaim, and DataVolume.
-
Choose an Exposure Method
The VMO UI route is separate from the CDI and KubeVirt proxy endpoints. Enabling the VMO UI Ingress does not expose CDI upload or virtual machine export on its own. Configure one of the following methods.
| Method | CDI upload | Virtual machine export |
|---|---|---|
| Native Ingress | CDI Ingress on /v1beta1/upload | KubeVirt Ingress on /api/export.kubevirt.io |
LoadBalancer Services | cdi-uploadproxy-lb Service | virt-exportproxy-lb Service |
virtctl vmexport --port-forward | Not applicable | Local port forward through the Kubernetes API |
None of these methods requires a manual route.
CDI upload works with either method. For virtual machine export, virtctl can download without --port-forward only
when the export proxy is exposed on a hostname, for example through an Ingress behind an AWS load balancer, because
virtctl detects the export host. If the export proxy is exposed on an IP address, such as through an IP-based
LoadBalancer Service, always use --port-forward. The export procedure on this page uses --port-forward, so it
works with either method.
Expose the Proxies with Ingress
-
Log in to Palette.
-
From the left main menu, select Clusters, and then select your VMO cluster.
-
Select the Profile tab. Then, select the Virtual Machine Orchestrator layer and select Values. The values editor appears.
-
Add one of the following overrides to the values. Do not append
/v1beta1/uploadto either CDI URL value, because VMO andvirtctlappend the upload API path.- Traefik
- Nginx
Use Ingress rules on a shared external address. This configuration does not require separate CDI or KubeVirt DNS records.
charts:
virtual-machine-orchestrator:
vmo-manager:
platform:
cdiExternalUploadUrl: "https://<vmo-external-address>"
cdi:
ingress:
enabled: true
className: traefik
hosts:
- host: "<vmo-external-address>"
paths:
- path: /v1beta1/upload
pathType: Prefix
cdiResource:
additionalConfig:
uploadProxyURLOverride: "https://<vmo-external-address>"
kubevirt:
ingress:
enabled: true
ingressClassName: traefik
hosts:
- host: <vmo-external-address>
paths:
- path: /api/export.kubevirt.io
pathType: ImplementationSpecificReplace
<vmo-external-address>with the address or DNS name that clients use to reach your ingress controller.When the ingress class is
traefik, the chart creates theServersTransportobjects and HTTPS Service annotations that Traefik needs. Do not create them manually.Use explicit DNS names and the following controller settings.
charts:
virtual-machine-orchestrator:
vmo-manager:
platform:
cdiExternalUploadUrl: "https://<cdi-upload-dns-name>"
cdi:
ingress:
enabled: true
className: nginx
annotations:
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/proxy-body-size: "0"
nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
hosts:
- host: "<cdi-upload-dns-name>"
paths:
- path: /v1beta1/upload
pathType: Prefix
cdiResource:
additionalConfig:
uploadProxyURLOverride: "https://<cdi-upload-dns-name>"
kubevirt:
ingress:
enabled: true
ingressClassName: nginx
annotations:
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
hosts:
- host: "<vm-export-dns-name>"
paths:
- path: /api/export.kubevirt.io
pathType: ImplementationSpecificReplace
<cdi-upload-dns-name>and<vm-export-dns-name>with the DNS names that clients use to reach your ingress controller.Retain the unlimited request-body setting, the 600-second read and send timeouts, and request buffering turned off. A disk image upload can be large, and a proxy with lower request-size or timeout limits causes the upload to fail.
Set
classNameandingressClassNameexplicitly when the cluster has more than one ingress controller. -
Select Save. Wait for Palette to finish updating the cluster.
When you enable native Ingress, the chart creates the following resources.
| Resource | Namespace |
|---|---|
CDI Ingress cdi-uploadproxy and Service cdi-uploadproxy-ingress | cdi |
KubeVirt Ingress virt-exportproxy and Service virt-exportproxy-ingress | kubevirt |
Expose the Proxies with LoadBalancer Services
As an alternative to Ingress, expose both proxies directly through LoadBalancer Services.
-
Open the values editor of the Virtual Machine Orchestrator layer, as described in steps 1 through 3 of Expose the Proxies with Ingress. Add the following overrides to turn off native Ingress and create the
LoadBalancerServices.charts:
virtual-machine-orchestrator:
cdi:
ingress:
enabled: false
service:
type: LoadBalancer
port: 443
targetPort: 8443
kubevirt:
ingress:
enabled: false
service:
type: LoadBalancer
port: 443
targetPort: 8443Select Save. Wait for Palette to finish updating the cluster.
-
Get the external addresses of the
cdi-uploadproxy-lbService in thecdinamespace and thevirt-exportproxy-lbService in thekubevirtnamespace.kubectl get service cdi-uploadproxy-lb --namespace cdi
kubectl get service virt-exportproxy-lb --namespace kubevirtThe
EXTERNAL-IPcolumn shows the external address of each Service.Example OutputNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
cdi-uploadproxy-lb LoadBalancer 10.100.5.141 192.0.2.93 443:31874/TCP 25h
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
virt-exportproxy-lb LoadBalancer 10.102.131.217 192.0.2.92 443:30698/TCP 25h -
After the CDI Service receives an external address, update the profile a second time. In the values editor of the Virtual Machine Orchestrator layer, add that address for both VMO and CDI. Do not append
/v1beta1/uploadto either value.charts:
virtual-machine-orchestrator:
vmo-manager:
platform:
cdiExternalUploadUrl: "https://<cdi-loadbalancer-address>"
cdi:
cdiResource:
additionalConfig:
uploadProxyURLOverride: "https://<cdi-loadbalancer-address>"Replace
<cdi-loadbalancer-address>with the external address of thecdi-uploadproxy-lbService.Select Save. Wait for Palette to finish updating the cluster.
Verify the External CDI URL
Confirm that CDI advertises the address that you configured.
kubectl get cdiconfig config \
--output jsonpath='{.status.uploadProxyURL}{"\n"}'
The result must be the externally reachable CDI base URL, without /v1beta1/upload. For example, if
<cdi-upload-dns-name> is cdi-upload.example.com, the command returns the following output.
https://cdi-upload.example.com
Upload a Disk Image
-
Confirm the access mode and volume mode that your StorageClass supports. CDI must write the destination volume during upload, so a read-only access mode does not work. For example, the
linstor-lvm-storageStorageClass supports the following combinations.Access mode Volume mode Upload support ReadWriteOncefilesystemSupported ReadWriteOnceblockSupported when the StorageProfile advertises the ReadWriteOnceandBlockpairReadWriteManyfilesystemSupported only when the StorageProfile advertises the ReadWriteManyandFilesystempairReadWriteManyblockSupported only when the StorageProfile advertises the ReadWriteManyandBlockpairReadOnlyManyEither Not supported -
Check the exact combinations that the StorageClass advertises.
kubectl get storageprofile <storage-class-name> \
--output jsonpath='{range .status.claimPropertySets[*]}accessModes={.accessModes}, volumeMode={.volumeMode}{"\n"}{end}'Replace
<storage-class-name>with the name of your StorageClass. Use only a pair that this command prints. The Kubernetes API usesFilesystemandBlock, and the correspondingvirtctlflag values arefilesystemandblock. -
Upload the image. The following example uploads an Ubuntu cloud image to a
10GiDataVolume namedubuntu-imagein thevirtual-machinesnamespace.virtctl image-upload dv ubuntu-image \
--namespace=virtual-machines \
--size=10Gi \
--storage-class=<storage-class-name> \
--access-mode=ReadWriteOnce \
--volume-mode=filesystem \
--image-path="ubuntu-24.04-server-cloudimg-amd64.img" \
--insecure \
--force-bind \
--retry=10 \
--wait-secs=600Replace
<storage-class-name>with the name of your StorageClass. To upload to a block-mode volume, set--volume-mode=block. Use block mode only if the command in step 2 lists theReadWriteOnceandBlockpair.The following example shows the command output without the upload progress bar.
Example OutputPVC virtual-machines/ubuntu-image not found
DataVolume virtual-machines/ubuntu-image created
Waiting for PVC ubuntu-image upload pod to be ready...
Pod now ready
Uploading data to https://192.0.2.93
Uploading data completed successfully, waiting for processing to complete, you can hit ctrl-c without interrupting the progress
Processing completed successfully
Uploading ubuntu-24.04-server-cloudimg-amd64.img completed successfullywarningThe
--insecureflag skips certificate verification and is intended for an endpoint that presents a certificate that the client does not trust. In production, install a certificate that the client trusts and remove--insecure. -
Confirm that the DataVolume completed.
kubectl get datavolume ubuntu-image \
--namespace virtual-machinesThe
PHASEcolumn must showSucceeded.Example OutputNAME PHASE PROGRESS RESTARTS AGE
ubuntu-image Succeeded N/A 115s
Create a Virtual Machine from the Uploaded Disk
Create a halted virtual machine that uses the uploaded disk. The following example creates a virtual machine named
example-vm.
virtctl create vm \
--name=example-vm \
--run-strategy=Halted \
--memory=2Gi \
--infer-preference=false \
--volume-pvc=src:ubuntu-image |
kubectl apply \
--namespace virtual-machines \
--filename -
The command returns the following output.
virtualmachine.kubevirt.io/example-vm created
Confirm that the virtual machine is halted.
kubectl get vm example-vm \
--namespace virtual-machines
The STATUS column must show Stopped.
NAME AGE STATUS READY
example-vm 1s Stopped False
Keep the virtual machine halted while you export the disk. The export cannot mount a ReadWriteOnce disk that a running
virtual machine is using.
Export a Virtual Machine Disk
-
Export the disk with port forwarding. This path requires no external KubeVirt Ingress,
LoadBalancerService, DNS record, or route.virtctl vmexport download example-vm-export \
--vm=example-vm \
--namespace=virtual-machines \
--volume=ubuntu-image \
--format=gzip \
--output=example-vm-disk.img.gz \
--insecure \
--port-forward \
--delete-vme \
--readiness-timeout=10mThe command creates a temporary
VirtualMachineExport, waits for the export service, opens a local port forward, downloads the volume, and deletes the temporary export. The following example shows the command output without the download progress bar.Example OutputVirtualMachineExport 'virtual-machines/example-vm-export' created succesfully
waiting for VM Export example-vm-export status to be ready...
service virt-export-example-vm-export is ready for port-forwarding
Forwarding from 127.0.0.1:61055 -> 8443
Forwarding from [::1]:61055 -> 8443
Port forwarding is ready.
Handling connection for 61055
Download finished succesfully
VirtualMachineExport 'virtual-machines/example-vm-export' deleted succesfully -
Validate the downloaded file.
file example-vm-disk.img.gz
gzip --test example-vm-disk.img.gzThe
filecommand must report gzip-compressed data, andgzip --testprints nothing when the archive is intact. If you download without--port-forward, an HTML document indicates that the request reached an incorrect route or a proxy error page.Example Outputexample-vm-disk.img.gz: gzip compressed data, original size modulo 2^32 2057306112
Troubleshooting
Scenario - Image Upload Cannot Discover the Upload Proxy
Confirm the advertised upload proxy URL.
kubectl get cdiconfig config \
--output jsonpath='{.status.uploadProxyURL}{"\n"}'
If the result is empty or incorrect, set
charts.virtual-machine-orchestrator.cdi.cdiResource.additionalConfig.uploadProxyURLOverride to the exact external
scheme and address. Do not include /v1beta1/upload.
Scenario - Ingress Returns HTTP 500 or 502
-
If you use Traefik, confirm that
classNameandingressClassNameare both set totraefikso that the chart creates the backendServersTransportresources. -
If you use Nginx, confirm that both proxy Ingresses use the
nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"annotation.
Scenario - The Image Upload Times Out
For Nginx, retain the unlimited request-body setting, the 600-second read and send timeouts, and request buffering turned off, as shown in Expose the Proxies with Ingress. Do not send a large upload through a proxy whose request-size or timeout limits are lower.
Scenario - The Export Remains Pending
Confirm that the virtual machine is halted and that no pod mounts the source disk.
kubectl get vm example-vm \
--namespace virtual-machines
kubectl get virtualmachineexport example-vm-export \
--namespace virtual-machines \
--output yaml
In the first command's output, the STATUS column must show Stopped. If it shows Running, stop the virtual machine
with virtctl stop example-vm --namespace virtual-machines. In the second command's output, the status.conditions
list shows why the export is not ready.
Next Steps
Review the Deployment Modes reference to understand how the pack's network topology and TLS settings interact with these proxy endpoints.