docs(operations): add containerized GPU workloads guide

[Aleksei Sviridkin (lexfrei)]

What this PR does

Add a new operations guide describing the container variant of cozystack.gpu-operator — the architectural mode for containerized GPU workloads (CUDA pods, ML training, inference) on Linux GPU nodes that already ship the NVIDIA driver and nvidia-container-toolkit via the distro package manager.

The new page lands at content/en/docs/next/operations/gpu-container-workloads.md and rounds out the GPU documentation surface:

• Running VMs with GPU Passthrough — VFIO passthrough of whole GPUs to KubeVirt VMs (default variant).
• GPU Sharing with HAMi — fractional GPU sharing in tenant Kubernetes clusters.
• Running Containerized GPU Workloads — this page. Containerized GPU workloads on management nodes (container variant).

Content covers when to pick the variant (host driver + host toolkit prerequisite), the operator-validator host-driver auto-detect mechanism (/host/usr/bin/nvidia-smi), the Talos caveat with a pointer to the examples/values-native-talos.yaml reference, install steps with Package CR variant: container, a sample CUDA pod for verification, and a three-row variant comparison matrix.

Companion to cozystack/cozystack#2766, which adds the container variant itself.

Release note

docs(operations): add guide for containerized GPU workloads via the gpu-operator `container` variant.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide for running containerized GPU workloads on cluster nodes, including prerequisites, installation steps, verification procedures for operator health and GPU resource allocation, sample CUDA Pod workflow, and comparison of container, default, and vGPU operator variants.

[netlify]

✅ Deploy Preview for cozystack ready!

Name	Link
🔨 Latest commit	b9cae43
🔍 Latest deploy log	https://app.netlify.com/projects/cozystack/deploys/6a229f111d93870008eb329d
😎 Deploy Preview	https://deploy-preview-555--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]

Warning

Review limit reached

@lexfrei, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 33 minutes and 43 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2f8807e7-294c-4f0a-9302-73236ce33545

📥 Commits

Reviewing files that changed from the base of the PR and between 8b83e54 and b9cae43.

📒 Files selected for processing (1)

• content/en/docs/next/operations/gpu-container-workloads.md

📝 Walkthrough

Walkthrough

This PR adds a new operations documentation page explaining how to deploy and use the cozystack.gpu-operator container variant on Cozystack management cluster nodes. The guide covers installation prerequisites, step-by-step setup via a Package CR, verification steps, a CUDA workload example, HAMi-based fractional GPU sharing, and a comparison of operator variants.

Changes

GPU Container Workloads Documentation

Layer / File(s)	Summary
GPU container variant guide content/en/docs/next/operations/gpu-container-workloads.md	New operations guide explains when to use the container variant (host already has NVIDIA driver and nvidia-container-toolkit), installation prerequisites, Package CR setup with warnings against bundles.enabledPackages, health verification, CUDA Pod example, HAMi fractional sharing guidance, and variant comparison table.

Possibly related issues

• cozystack/cozystack#2764: Directly addresses the same cozystack.gpu-operator container variant documentation and configuration guidance referenced in this PR.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A GPU path through containers clear,
With HAMi sharing, fractional cheer!
From driver checks to CUDA Pod flight,
The operations guide shines oh-so bright! ✨

🚥 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 summarizes the main change: adding documentation for containerized GPU workloads, which matches the new guide page created in the pull request.
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 feat/gpu-container-workloads-docs

---

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 adds a new documentation page detailing how to run containerized GPU workloads using the container variant of the cozystack.gpu-operator package. The review feedback suggests specifying the cozy-system namespace in both the kubectl patch command and the Package resource manifest to ensure they are applied to the correct namespace.

[gemini-code-assist]

In Cozystack, the Package resources (including cozystack.cozystack-platform) are typically located in the cozy-system namespace. Running kubectl patch without specifying the namespace will fail if the user's current context is set to another namespace (like default). Adding -n cozy-system ensures the command runs successfully.

Suggested change

	kubectl patch packages.cozystack.io cozystack.cozystack-platform --type=json \
	-p '[{"op": "add", "path": "/spec/components/platform/values/bundles/enabledPackages/-", "value": "cozystack.gpu-operator"}]'
	kubectl patch packages.cozystack.io cozystack.cozystack-platform -n cozy-system --type=json \\
	-p '[{"op": "add", "path": "/spec/components/platform/values/bundles/enabledPackages/-", "value": "cozystack.gpu-operator"}]'

[gemini-code-assist]

The Package resource needs to be created in the cozy-system namespace for the Cozystack operator to detect and reconcile it. Adding namespace: cozy-system to the metadata ensures it is applied to the correct namespace.

Suggested change

	apiVersion: cozystack.io/v1alpha1
	kind: Package
	metadata:
	name: cozystack.gpu-operator
	spec:
	variant: container
	apiVersion: cozystack.io/v1alpha1
	kind: Package
	metadata:
	name: cozystack.gpu-operator
	namespace: cozy-system
	spec:
	variant: container

[coderabbitai]

Actionable comments posted: 0