Document virtctl image-upload --archive-path option

[harsh-thakare]

Title:
OSDOCS: Document virtctl image-upload --archive-path option for VM disk uploads
Note: If you have a Jira OSDOCS ticket, replace the title with:
[OSDOCS#]: Document virtctl image-upload --archive-path option for VM disk uploads

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

Version(s):
4.22

Issue:
N/A

Link to docs preview:
Add the Netlify preview link from the PR bot comment after the PR is created.

Expected preview pages to verify:

• Virtualization > Getting started > Using the CLI tools > Image upload commands
  Anchor: #image-upload-commands_virt-using-the-cli-tools
• Virtualization > Creating VMs > Advanced > Uploading a virtual machine image by using the CLI
  Anchor: #virt-uploading-image-virtctl_virt-creating-vms-uploading-images
  Published reference pages (for comparison after merge):
• https://docs.redhat.com/en/documentation/openshift_container_platform/4.22/html/virtualization/getting-started#image-upload-commands_virt-using-the-cli-tools
• https://docs.redhat.com/en/documentation/openshift_container_platform/4.22/html/virtualization/creating-vms-advanced#virt-uploading-image-virtctl_virt-creating-vms-uploading-images

QE review:

• QE has approved this change.

Additional information:

Summary

This PR documents the virtctl image-upload --archive-path option, which is available in virtctl image-upload --help but was not previously described in the OpenShift Virtualization documentation.
The update also clarifies when to use --image-path versus --archive-path, including guidance for gzip-compressed disk images such as .img.gz exported with virtctl vmexport.

Motivation

Customers uploading VM disk images with virtctl image-upload can choose between two source flags:

• --image-path: for VM disk images
• --archive-path: for tar archives
  Using --archive-path with a gzip-compressed disk image (for example, disk.img.gz) fails with an HTTP 500 error and CDI log messages such as:

begin untar to /data...
unable to untar files from endpoint
exit status 2

This happens because CDI treats archive uploads as tar extraction (tar -xvC /data), not gzip decompression. A .img.gz file produced by virtctl vmexport download --output=disk.img.gz is a gzip-compressed disk image, not a tar archive, and must be uploaded with --image-path.
Example:
Wrong:

$ virtctl image-upload dv my-dv --size=200Gi --archive-path=disk.img.gz --insecure

Correct:

$ virtctl image-upload dv my-dv --size=200Gi --image-path=disk.img.gz --insecure

Use --archive-path only for tar archives, for example:

$ tar -cvf disk.tar disk.img
$ virtctl image-upload dv my-dv --size=200Gi --archive-path=disk.tar

Changes

modules/virt-image-upload-commands.adoc

• Updated the module abstract to mention tar archive uploads.
• Added two --archive-path command examples to the Image upload commands table.
• Added a NOTE that explains:
  • --image-path is for VM disk images, including .img, .qcow2, .iso, and .img.gz
  • --archive-path is for tar archives only
  • only one of the two flags can be used
  • gzip-compressed disk images must not be uploaded with --archive-path

modules/virt-uploading-image-virtctl.adoc

• Added NOTE bullets in the upload procedure explaining when to use --image-path and --archive-path.
• Clarified that gzip-compressed images such as .img.gz must use --image-path.

Files changed

• modules/virt-image-upload-commands.adoc
• modules/virt-uploading-image-virtctl.adoc

Test plan

• Open the Netlify docs preview from the PR bot comment.
• Verify the Image upload commands table includes the new --archive-path rows.
• Verify the NOTE under Image upload commands renders correctly.
• Verify the NOTE in Uploading a virtual machine image by using the CLI includes the new guidance.
• Confirm the content is accurate against virtctl image-upload --help.

Review request

@openshift/team-documentation please review.

[openshift-ci]

Hi @harsh-thakare. Thanks for your PR.

I'm waiting for a openshift member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[openshift-ci]

@harsh-thakare: The label(s) /label peer-review-needed cannot be applied. These labels are supported: acknowledge-critical-fixes-only, platform/aws, platform/azure, platform/baremetal, platform/google, platform/libvirt, platform/openstack, ga, tide/merge-method-merge, tide/merge-method-rebase, tide/merge-method-squash, px-approved, docs-approved, qe-approved, ux-approved, no-qe, rebase/manual, cluster-config-api-changed, run-integration-tests, verified, ready-for-human-review, approved, backport-risk-assessed, bugzilla/valid-bug, cherry-pick-approved, cloud-experts, cnv, dev-tools, distributed-tracing, ims, jira/skip-dependent-bug-check, jira/valid-bug, merge-review-in-progress, merge-review-needed, mtc, multi-arch, oadp, ok-to-test, rhacs, rhv, sd-docs, serverless, service-mesh, sme-review-done, sme-review-needed, stability-fix-approved, staff-eng-approved, telco. Is this label configured under labels -> additional_labels or labels -> restricted_labels in plugin.yaml?

Details

In response to this:

/label peer-review-needed

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[harsh-thakare]

/ok-to-test

[openshift-ci]

@harsh-thakare: Cannot trigger testing until a trusted user reviews the PR and leaves an /ok-to-test message.

Details

In response to this:

/ok-to-test

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.