[docs] Add vGPU setup guide for GPU sharing between VMs

[lexfrei]

What this PR does

Adds a practical guide for running VMs with NVIDIA vGPU on Cozystack to the existing GPU passthrough page.

The guide covers the SR-IOV vGPU path used by current data-centre GPUs (L4, L40, L40S, B100) on the vGPU 20.x driver branch. The mediated-devices path used by older GPUs (Pascal–Ampere) is explicitly out of scope and the reader is pointed at upstream NVIDIA docs.

Steps documented:

• Build the proprietary vGPU Manager container image from github.com/NVIDIA/gpu-driver-container (the older gitlab.com/nvidia/container-images/driver is archived).
• Deploy GPU Operator with the vgpu variant via Package CR (depends on [gpu-operator] Update to v26.3.1 and add experimental vGPU variant cozystack#2323).
• Assign vGPU profiles to SR-IOV VFs (current_vgpu_type sysfs), with a periodic profile-loader DaemonSet skeleton and an explicit experimental warning.
• Configure DLS licensing via ClientConfigToken (the legacy NLS / ServerAddress= / ServerPort=7070 flow no longer applies).
• Patch the KubeVirt CR with permittedHostDevices.pciHostDevices (after vGPU: SRIOV support kubevirt/kubevirt#16890; first stable KubeVirt release with the patch is targeted at v1.9.0).
• Sample VirtualMachine (raw kubevirt.io/v1) using a CDI DataVolume so the rootfs has room for in-VM driver install, with a cloudInitNoCloud disk that drops the licensing token, gridd.conf, an SSH key, and the build dependencies.
• vGPU profile reference table for L40S with the Q/A/B suffix taxonomy.
• Warning about the 2.4 GiB containerDisk root overflow during in-VM driver install (we observed SIGBUS from a write into an mmap of a file the kernel could no longer extend; the new example sidesteps it via DataVolume).
• Talos is explicitly noted as not recommended for vGPU; passthrough on Talos is unaffected.

Release note

NONE

[netlify]

✅ Deploy Preview for cozystack ready!

Name	Link
🔨 Latest commit	4aaabe3
🔍 Latest deploy log	https://app.netlify.com/projects/cozystack/deploys/69f342cc00c09300076d1f2d
😎 Deploy Preview	https://deploy-preview-467--cozystack.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7aa47ec4-301c-4e56-8f23-74afce92ea71

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Documentation replaces the previous GPU-sharing overview with a focused vGPU (mediated device) guide covering prerequisites, NVIDIA vGPU licensing, GPU Operator vgpu variant, vGPU Manager image build, NVIDIA License Server wiring, KubeVirt mediated device config, VM examples, and vGPU profile details (≤50 words).

Changes

Cohort / File(s)

Summary

GPU vGPU Documentation content/en/docs/v1/virtualization/gpu.md

Rewrote GPU sharing section into a full vGPU (mdev) guide: new prerequisites and licensing notes; instructions to build/publish vGPU Manager driver container; GPU Operator variant: vgpu installation and node labeling; NVIDIA License Server Secret/ConfigMap example and Package wiring; KubeVirt mediatedDevices configuration; VM example requesting nvidia.com/<profile> and verification; added L40S vGPU profiles table; clarified open-source vGPU wording.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 I hopped through docs with glee today,
Tucked mdev notes and profiles away,
Built driver images, licenses in tow,
VMs now share GPUs—watch them go! 🎉

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a comprehensive vGPU setup guide for GPU sharing between virtual machines, which aligns with the expanded documentation covering vGPU Manager deployment, licensing, KubeVirt configuration, and VM examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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 docs/gpu-vgpu-setup

---

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 and usage tips.}

[gemini-code-assist]

Code Review

This pull request provides comprehensive documentation for configuring NVIDIA vGPU sharing for virtual machines, including prerequisites, image building, operator installation, and licensing setup. The review feedback suggests clarifying the FeatureType parameter in the licensing configuration and updating the example command prompt to maintain consistency with the platform's virtual machine naming conventions.

[gemini-code-assist]

It is helpful to clarify what the FeatureType value represents to assist users in customizing their configuration. In the NVIDIA Grid configuration, 1 corresponds to the "NVIDIA vGPU" (vPC/vWS) feature, while 2 is for "NVIDIA Virtual Compute Server" (vCS).

Suggested change

	FeatureType=1
	FeatureType=1 # 1 for vGPU

[gemini-code-assist]

For consistency with the GPU passthrough example (line 194) and Cozystack's default naming convention for virtual machine instances, the hostname in the command prompt should include the virtual-machine- prefix. Since the VM name is defined as gpu-vgpu on line 352, the resulting instance name is virtual-machine-gpu-vgpu.

Suggested change

	ubuntu@gpu-vgpu:~$ nvidia-smi
	ubuntu@virtual-machine-gpu-vgpu:~$ nvidia-smi

[coderabbitai]

🧹 Nitpick comments (1)

content/en/docs/v1/virtualization/gpu.md (1)

360-385: Name the manifest file explicitly before the apply command.

kubectl apply -f vmi-vgpu.yaml appears without first labeling the YAML block as vmi-vgpu.yaml (unlike the earlier passthrough example). Adding a filename label right above the manifest would remove ambiguity for copy/paste users.

✏️ Suggested doc tweak

 ### 5. Create a Virtual Machine with vGPU

+**vmi-vgpu.yaml**:
+
 ```yaml
 apiVersion: apps.cozystack.io/v1alpha1
 appVersion: '*'
 kind: VirtualMachine
 ...

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @content/en/docs/v1/virtualization/gpu.md around lines 360 - 385, Add an
explicit filename label above the YAML manifest block so users know the file
name to save before running kubectl; specifically, annotate the VirtualMachine
manifest block with "vmi-vgpu.yaml" (the same name used in the kubectl apply -f
vmi-vgpu.yaml command) by placing the filename line immediately before the

invocation.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@content/en/docs/v1/virtualization/gpu.md`:
- Around line 360-385: Add an explicit filename label above the YAML manifest
block so users know the file name to save before running kubectl; specifically,
annotate the VirtualMachine manifest block with "vmi-vgpu.yaml" (the same name
used in the kubectl apply -f vmi-vgpu.yaml command) by placing the filename line
immediately before the ```yaml fence, ensuring consistency between the manifest
and the kubectl apply invocation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 150cd704-7d01-4c3d-86f5-81294e0a31b5

📥 Commits

Reviewing files that changed from the base of the PR and between 624a38c and 468dd7b.

📒 Files selected for processing (1)

• content/en/docs/v1/virtualization/gpu.md

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

content/en/docs/v1/virtualization/gpu.md (1)

279-288: Make the imagePullSecrets snippet fully qualified to prevent misplacement.

At Line 279, the snippet is context-trimmed and can be pasted under the wrong key. Please show the full values path to avoid broken Package configuration.

Proposed doc patch

-    ```yaml
-    gpu-operator:
-      vgpuManager:
-        repository: registry.example.com/nvidia
-        version: "550.90.05"
-        imagePullSecrets:
-        - name: nvidia-registry-secret
-    ```
+    ```yaml
+    components:
+      gpu-operator:
+        values:
+          gpu-operator:
+            vgpuManager:
+              repository: registry.example.com/nvidia
+              version: "550.90.05"
+              imagePullSecrets:
+              - name: nvidia-registry-secret
+    ```

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@content/en/docs/v1/virtualization/gpu.md` around lines 279 - 288, The snippet
for imagePullSecrets is too context-trimmed and can be pasted under the wrong
key; update the example so it shows the full values path (wrap the existing
gpu-operator.vgpuManager block under components -> gpu-operator -> values ->
gpu-operator -> vgpuManager) so users see the complete hierarchy and the
imagePullSecrets entry (refer to symbols: components, gpu-operator, values,
gpu-operator, vgpuManager, imagePullSecrets) and replace the trimmed snippet
with this fully-qualified version.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@content/en/docs/v1/virtualization/gpu.md`:
- Around line 358-391: Add an explicit readiness check for the
VirtualMachineInstance before calling "virtctl console": after applying
vmi-vgpu.yaml (kubectl apply -f vmi-vgpu.yaml) add a step that waits for the VMI
to become Ready (e.g., using "kubectl get vmi -n tenant-example -w" or "kubectl
wait --for=condition=Ready vmi/gpu-vgpu -n tenant-example") so the subsequent
"virtctl console virtual-machine-gpu-vgpu" call won't fail intermittently.

---

Nitpick comments:
In `@content/en/docs/v1/virtualization/gpu.md`:
- Around line 279-288: The snippet for imagePullSecrets is too context-trimmed
and can be pasted under the wrong key; update the example so it shows the full
values path (wrap the existing gpu-operator.vgpuManager block under components
-> gpu-operator -> values -> gpu-operator -> vgpuManager) so users see the
complete hierarchy and the imagePullSecrets entry (refer to symbols: components,
gpu-operator, values, gpu-operator, vgpuManager, imagePullSecrets) and replace
the trimmed snippet with this fully-qualified version.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7d6caa76-d2a5-4856-97eb-524345257f6b

📥 Commits

Reviewing files that changed from the base of the PR and between 468dd7b and 492f318.

📒 Files selected for processing (1)

• content/en/docs/v1/virtualization/gpu.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add an explicit VM readiness check before opening console.

After Line 384, jumping directly to virtctl console can fail intermittently if the VM/VMI is not ready yet. Add a wait/check step to keep the flow deterministic.

Proposed doc patch

 ```bash
 kubectl apply -f vmi-vgpu.yaml

+Wait until the VM instance is ready:
+
+bash +kubectl get vmi -n tenant-example -w +
+
Once the VM is running, log in and verify the vGPU is available:

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @content/en/docs/v1/virtualization/gpu.md around lines 358 - 391, Add an
explicit readiness check for the VirtualMachineInstance before calling "virtctl
console": after applying vmi-vgpu.yaml (kubectl apply -f vmi-vgpu.yaml) add a
step that waits for the VMI to become Ready (e.g., using "kubectl get vmi -n
tenant-example -w" or "kubectl wait --for=condition=Ready vmi/gpu-vgpu -n
tenant-example") so the subsequent "virtctl console virtual-machine-gpu-vgpu"
call won't fail intermittently.

</details>

<!-- fingerprinting:phantom:triton:hawk:8b73ebdb-e38a-4b41-bcc3-3277f8a35b52 -->

<!-- This is an auto-generated comment by CodeRabbit -->