docs: add AMD Instinct vGPU design draft (#1707)

[kenji-mido]

What type of PR is this?

/kind documentation

What this PR does / why we need it:

Adds a design document (docs/develop/amd-vgpu.md) for AMD Instinct GPU isolation
(per-pod memory limiting + CU partitioning) on ROCm. It covers the scheduler<->device-plugin protocol
(node/pod annotations), the CU-count -> ROC_GLOBAL_CU_MASK model, and open discussion points.

Submitted as a design draft per the discussion in #1707
(#1707 (comment)).

Which issue(s) this PR fixes:

Relates to #1707

Special notes for your reviewer:

AI assistance disclosure: I used Claude Code to (double) fact-check claims against the HAMi source
(annotation keys, DeviceInfo fields, per-vendor conventions) and to draft wording.
The final text was authored, edited, and reviewed by me, and all technical claims were verified against the codebase.

Does this PR introduce a user-facing change?:

NONE

Summary by CodeRabbit

• Documentation
  • Added a new design document for AMD Instinct vGPU support on Kubernetes pods.
  • Documented fractional GPU sharing via per-pod GPU memory and compute-unit (CU) limits.
  • Explained how allocation details are conveyed between scheduling components and containers.
  • Included current limitations and guidance for required CU mask handling and enforcement.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new design document for AMD Instinct vGPU support in Kubernetes, covering fractional GPU memory allocation, CU partitioning, scheduler-device-plugin annotations, resource mapping, limitations, and plugin layering discussion.

Changes

AMD vGPU Design Documentation

Layer / File(s)	Summary
Protocol, resource mapping, and constraints docs/develop/amd-vgpu.md	Describes per-pod GPU memory and CU semantics, node and pod annotations, CU mask handling, memory environment injection, non-overlap enforcement, limitations, and plugin layering discussion.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• feat: Add AMD Instinct GPU isolation (GPU memory limiting + Computing unit (CU) partitioning) #1707: The document covers the AMD Instinct GPU isolation model using amd.com/gpumem and amd.com/gpucores, matching the issue’s feature scope.

Poem

🐇 I hop through docs with CU bits in tow,
Memory caps and masks in tidy flow.
Annotations dance, the limits align,
One vGPU tale, concise and fine.
Hop hop — AMD dreams glow ✨

🚥 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 matches the change: it adds an AMD Instinct vGPU design draft document.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[gemini-code-assist]

Code Review

This pull request introduces a design proposal document for AMD Instinct vGPU support in HAMi, detailing the motivation, goals, architecture approach, and resource allocation protocol. The review feedback focuses on minor grammatical, punctuation, and formatting improvements to enhance the readability and correctness of the documentation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@docs/develop/amd-vgpu.md`:
- Around line 58-60: Add a language tag to the remaining fenced example blocks
in the AMD vGPU docs so they render cleanly and avoid MD040; update the fenced
snippets around the hami.io/amd-devices-allocated examples to use text fences
consistently, matching the other documentation examples in this file.
- Around line 16-20: The AMD GPU docs section on LD_AUDIT vs LD_PRELOAD needs a
source and tighter scope. Update the explanation in the documented ROCm/HIP area
to cite the upstream issue or release note that describes the LD_PRELOAD
symbol-resolution failure, and explicitly state that this workaround applies
only to the affected ROCm 7.x/HIP releases or the recursive interception failure
mode. Keep the existing NVIDIA LD_PRELOAD note unchanged while making the
ROCm-specific limitation clear in the same paragraph.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a7386b3a-3956-4869-a19b-03764911ff80

📥 Commits

Reviewing files that changed from the base of the PR and between 03eed2e and e2b4412.

📒 Files selected for processing (1)

• docs/develop/amd-vgpu.md

[archlitchi]

thanks @kenji-mido, i've assigned the development of device-plugin to @FouoF, he will finish his part in July, and find a digital-ocean environment to validate, after that, we will release that part on Aug, before the release of v2.10

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
unittests	59.05% <ø> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[archlitchi]

CC @mesutoezdil

[wawa0210]

Bot detected the issue body's language is not English, translate it automatically. 👯👭🏻🧑‍🤝‍🧑👫🧑🏿‍🤝‍🧑🏻👩🏾‍🤝‍👨🏿👬🏿

---

CC @mesutoezdil

[mesutoezdil]

/lgtm

[Shouren]

/lgtm

[hami-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kenji-mido, Shouren

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [Shouren]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[kenji-mido]

thanks @kenji-mido, i've assigned the development of device-plugin to @FouoF, he will finish his part in July, and find a digital-ocean environment to validate, after that, we will release that part on Aug, before the release of v2.10

@archlitchi @FouoF

Could you share the current status of the AMD device-plugin?
I'd like to align the scheduler side (pkg/device/amd) with the revised design in #2067, and I'd also like to think about where I could be of help. Thanks!