[virtualization] Use USB Redirection for KubeVirt VMs on ACP

[jing2uo]

Summary

• Add English and Chinese KB articles for KubeVirt USB Redirection on ACP.
• Document prerequisites, minimal RBAC, VM configuration, client workflow, guest verification, limitations, and troubleshooting.
• Remove environment-specific cluster names, internal API addresses, personal paths, and one-off validation VM details from the original draft.

Validation

• Ran git diff --cached --check before commit.
• Verified the virtualmachineinstances/usbredir.subresources.kubevirt.io RBAC check syntax against the ACP KubeVirt workload API.
• Docs-only change; build not run.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guides on USB Redirection for KubeVirt virtual machines available in English and Chinese. Includes setup prerequisites, RBAC configuration, enabling client passthrough, device redirection steps, guest verification, limitations, and troubleshooting guidance.

[coderabbitai]

Walkthrough

Two new documentation files are added — one in English and one in Chinese — providing a complete how-to guide for KubeVirt USB Redirection (client passthrough via virtctl usbredir) on ACP 4.4. Both files cover the same content: overview, prerequisites, RBAC, VM configuration, client-side redirection, guest verification, limitations, troubleshooting, and references.

Changes

KubeVirt USB Redirection How-To Guide (EN + ZH)

Layer / File(s)	Summary
Front matter, overview, and prerequisites docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md, docs/zh/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md	Document metadata (kind/products/version), use-case comparison table between USB host passthrough and USB Redirection, end-to-end traffic path, and cluster-side plus client-side prerequisites including KubeVirt version, supported architectures, required client tools, and connectivity expectations.
Least-privilege RBAC setup and verification docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md, docs/zh/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md	Role and RoleBinding granting get/create on the virtualmachineinstances/usbredir subresource, with a kubectl auth can-i command and expected output for verifying permissions.
Enabling clientPassthrough on a VM and validating QEMU slots docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md, docs/zh/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md	Steps to add clientPassthrough: {} under spec.template.spec.domain.devices, patch an existing VM, restart via virtctl restart, confirm the VMI field, and use virsh dumpxml to validate virt-usbredir-0 through virt-usbredir-3 slot creation.
Client-side USB redirection and guest-side verification docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md, docs/zh/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md	virtctl usbredir invocations using vendor/product IDs or bus/device addresses, session lifetime and disconnect behavior, guest-side lsusb/lsblk/blkid verification steps, and storage safety guidance against simultaneous mounting on client and guest.
Limitations, troubleshooting, and references docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md, docs/zh/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md	Slot/session constraints, device suitability warnings, USB storage corruption risk, six troubleshooting subsections (missing clientPassthrough, VMI not running, missing usbredirect, libusb/permission errors, no free slot, post-disconnect storage binding failure) with commands, and external reference links.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, a USB plug finds its way,
Through KubeVirt tunnels, it travels today,
virtctl usbredir calls across the wire,
QEMU slots lit up, four slots to admire,
The rabbit has written the guide — hip hooray! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding documentation for USB Redirection functionality for KubeVirt VMs on ACP, which matches the changeset content.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch kb/2026-06/use-usb-redirection-kubevirt-vms

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md (1)

56-56: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Clarify Windows client validation guidance.

Line 56 states "Validate the Windows client path separately before using it as a supported delivery workflow," but it is ambiguous what "validate the Windows client path" means. Does it mean:

• Verify that usbredirect is in PATH?
• Test the client setup in your Windows environment?
• Validate vendor/product ID access on Windows?

Consider rephrasing to be more explicit about what needs to be validated and how.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md` at line 56,
The phrase "Validate the Windows client path" on line 56 is ambiguous and
unclear about what specifically needs to be validated. Replace this vague
instruction with explicit guidance that clarifies the actual validation steps
required for Windows clients. Specify what should be validated, such as ensuring
usbredirect is available in PATH, verifying the UsbDk installation is correct,
or testing the client setup in the Windows environment. Make the sentence more
concrete and actionable by replacing the ambiguous phrase with specific
validation requirements or testing procedures that readers should follow.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md`:
- Line 56: The phrase "Validate the Windows client path" on line 56 is ambiguous
and unclear about what specifically needs to be validated. Replace this vague
instruction with explicit guidance that clarifies the actual validation steps
required for Windows clients. Specify what should be validated, such as ensuring
usbredirect is available in PATH, verifying the UsbDk installation is correct,
or testing the client setup in the Windows environment. Make the sentence more
concrete and actionable by replacing the ambiguous phrase with specific
validation requirements or testing procedures that readers should follow.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9f94c494-12e2-48f0-bb38-9eb64b25ed8b

📥 Commits

Reviewing files that changed from the base of the PR and between e20db9e and d0fb256.

📒 Files selected for processing (2)

• docs/en/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md
• docs/zh/solutions/Use_USB_Redirection_for_KubeVirt_VMs_on_ACP.md