From 017ac5dfbcf77739dde1e8ff7634584eb3c55e6f Mon Sep 17 00:00:00 2001
From: Harshal Thakare <hthakare@redhat.com>
Date: Fri, 10 Jul 2026 09:28:01 +0530
Subject: [PATCH] Document virtctl image-upload --archive-path option

Clarify when to use --image-path versus --archive-path for VM disk
uploads, including guidance for gzip-compressed images exported from
virtctl vmexport.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 modules/virt-image-upload-commands.adoc   | 21 +++++++++++++++++----
 modules/virt-uploading-image-virtctl.adoc |  2 ++
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/modules/virt-image-upload-commands.adoc b/modules/virt-image-upload-commands.adoc
index 9597d1a9d6d8..6d5b7f42cfba 100644
--- a/modules/virt-image-upload-commands.adoc
+++ b/modules/virt-image-upload-commands.adoc
@@ -6,19 +6,32 @@
 = Image upload commands
 
 [role="_abstract"]
-You can use the following `virtctl image-upload` commands to upload a VM image to a data volume.
+You can use the following `virtctl image-upload` commands to upload a VM disk image or tar archive to a data volume.
 
 .Image upload commands
 [width="100%",cols="1a,2a",options="header"]
 |===
 |Command |Description
 |`virtctl image-upload dv <datavolume_name> --image-path=</path/to/image> --no-create`
-|Upload a VM image to a data volume that already exists.
+|Upload a VM disk image to a data volume that already exists.
 
 |`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --image-path=</path/to/image>`
-|Upload a VM image to a new data volume of a specified requested size.
+|Upload a VM disk image to a new data volume of a specified requested size.
 
 |`virtctl image-upload dv <datavolume_name> --datasource --size=<datavolume_size> --image-path=</path/to/image>`
-|Upload a VM image to a new data volume and create an associated `DataSource` object for it.
+|Upload a VM disk image to a new data volume and create an associated `DataSource` object for it.
+
+|`virtctl image-upload dv <datavolume_name> --archive-path=</path/to/archive> --no-create`
+|Upload a tar archive to a data volume that already exists.
+
+|`virtctl image-upload dv <datavolume_name> --size=<datavolume_size> --archive-path=</path/to/archive>`
+|Upload a tar archive to a new data volume of a specified requested size.
 |===
 
+[NOTE]
+====
+* Use `--image-path` to upload VM disk images. Supported formats include `ISO`, `IMG`, `QCOW2`, and gzip-compressed images, such as `.img.gz`. Containerized Data Importer (CDI) automatically decompresses gzip-compressed images during upload.
+* Use `--archive-path` to upload a tar archive that contains one or more files, such as a disk image created with `tar -cvf disk.tar disk.img`. CDI extracts the contents of the archive during upload.
+* Specify either `--image-path` or `--archive-path`. You cannot specify both flags in the same command.
+* Do not use `--archive-path` with gzip-compressed disk images. A gzip-compressed image, such as `disk.img.gz`, is not a tar archive. Upload these images by using `--image-path` instead.
+====
diff --git a/modules/virt-uploading-image-virtctl.adoc b/modules/virt-uploading-image-virtctl.adoc
index 262af63ba606..22b89ec5d194 100644
--- a/modules/virt-uploading-image-virtctl.adoc
+++ b/modules/virt-uploading-image-virtctl.adoc
@@ -36,6 +36,8 @@ $ virtctl image-upload dv <datavolume_name> \
 [NOTE]
 ====
 * If you do not want to create a new data volume, omit the `--size` parameter and include the `--no-create` flag.
+* Use `--image-path` to upload VM disk images, including gzip-compressed images such as `.img.gz`. CDI automatically decompresses gzip-compressed images during upload.
+* Use `--archive-path` only to upload tar archives, such as `disk.tar`. Do not use this flag with gzip-compressed disk images.
 * 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.
 ====