docs(gpu-sharing): document NvFractions configuration by davidLif · Pull Request #2052 · kai-scheduler/KAI-Scheduler

davidLif · 2026-08-10T18:38:20Z

Description

Final documentation PR in the GPU-sharing migration stack.

Base: codex/gpu-sharing-oci-chart
Head: codex/gpu-sharing-docs-pr152

This updates the GPU-sharing documentation for:

cluster GPU-sharing modes: Disabled, NonMemoryEnforced, HamiCore, and NvFractions
NvFractions install paths, including the bundled gpu-sharing OCI dependency and externally managed operator setup
runtime class, CDI/NRI, readiness, and admission behavior
user-facing fractional GPU request examples, including NvFractions per-container memory request and limit annotations
troubleshooting for admission, pending pods, and Helm render failures
quickstart links to the GPU-sharing guide

Related Issues

N/A

Checklist

Note: Ensure your PR title follows the Conventional Commits format (e.g., feat(scheduler): add new feature)

Self-reviewed
Added/updated tests (if needed)
Updated documentation (if needed)
Added a changelog fragment via make changelog (or applied the skip-changelog label). Do not edit CHANGELOG.md directly — pending fragments are folded into it at release time.

Breaking Changes

None.

Additional Notes

Validation:

ruby -ryaml -e 'ARGV.each { |f| YAML.load_file(f); puts "ok #{f}" }' docs/gpu-sharing/gpu-memory-mib-annotation.yaml docs/gpu-sharing/nv-fractions-memory.yaml docs/gpu-sharing/nv-fractions-request-limit.yaml
git diff --cached --check
git diff --check

gshaibi · 2026-08-17T08:41:47Z

+```bash
+helm upgrade -i kai-scheduler oci://ghcr.io/kai-scheduler/kai-scheduler/kai-scheduler \
+  -n kai-scheduler --create-namespace \
+  --set global.nvFractions.set=true


What do you think about global.nvFractions.enabled instead of global.nvFractions.set?

It's not really enabled, as you can set nvFractions using global.gpuSharingMode. The global.nvFractions.set sets both global.gpuSharingMode: "NvFractions" and installs the gpu-sharing operator subchart.

gshaibi · 2026-08-17T08:47:45Z

+
+KAI can auto-detect CDI and the CDI NRI plugin from the NVIDIA GPU Operator `ClusterPolicy`. When the `ClusterPolicy` indicates that CDI is enabled and selected as the default device injection path, KAI configures its CDI-aware binder plugins automatically. When NRI is enabled, KAI also enables the admission behavior that avoids injecting the legacy GPU-sharing environment variables.
+
+Use that detection to decide whether fractional GPU pods need a runtime class:


How to use that detection? Is it published somewhere?

It's something the kai operator does automatically.

Got it. In the doc it sounds like an instruction to the user - "Use that detection to..."

gshaibi · 2026-08-17T08:48:28Z

+```bash
+helm upgrade -i kai-scheduler oci://ghcr.io/kai-scheduler/kai-scheduler/kai-scheduler \
+  -n kai-scheduler --create-namespace \
+  --set admission.gpuFractionRuntimeClassName=null


Doesn't it defaults to nvidia in that case?

No. this is for the case "To suppress runtimeClassName injection on fractional GPU pods"

Yes, I understand, but in this case, won't the operator default to nvidia?

gshaibi · 2026-08-17T08:59:40Z

+helm install kai-resource-isolator oci://docker.io/projecthami/kai-resource-isolator \
+  --namespace kai-resource-isolator --create-namespace \
+  --version 1.0.0-chart


The hami/README.md points to a different version, I suggest dropping the installation instruction here and just reference to HAMI's doc.

Another thing - does hami/README.md need updating? (it still points to the deprecated --set global.gpuSharing=true field)

gshaibi · 2026-08-17T09:06:16Z

+
+### Choose an annotation style
+
+Use the annotation style that matches the cluster mode selected by your administrator. In `NvFractions` mode, the legacy `gpu-fraction` and `gpu-memory` annotations are still supported for backwards compatibility, but new memory-based workloads should prefer the per-container NvFractions request annotation.


Just a personal thought - I think it might be easier to users to always request via KAI's annotations and have KAI convert it to the relevant annotations based on the mode.

But I still understand the incentive to have the users request via the mode's specific annotation (for cross-scheduler compatability for example), so I think the current flow is fine.

It is just not consistent between HAMI and NvFractions mode, where we make the conversion for the first, but declare the conversion for NvFractions as still supported for backwards compatibility, hinting it might be deprecated in the future.

The way NvFractions annotations are declared allow for something more expresivness (like the container name) in comparison to the old annotations. One day, we might want to upgrade the other annotations as well to a similar format.

Signed-off-by: davidLif <davidshani12@gmail.com>

Co-authored-by: Guy Shaibi <39763067+gshaibi@users.noreply.github.com> Signed-off-by: davidLif <davidshani12@gmail.com>

Signed-off-by: davidLif <davidshani12@gmail.com>

davidLif added documentation Improvements or additions to documentation skip-changelog labels Aug 10, 2026

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 1dcaec1 to 3c3c165 Compare August 10, 2026 20:08

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 3c3c165 to 9afb286 Compare August 11, 2026 14:03

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 9afb286 to 67fbb5a Compare August 11, 2026 20:25

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 67fbb5a to 6d8c907 Compare August 11, 2026 21:14

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 6d8c907 to 8ddc851 Compare August 11, 2026 21:27

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 8ddc851 to 944ef42 Compare August 11, 2026 22:04

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 944ef42 to fd755ce Compare August 11, 2026 22:13

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from fd755ce to 6136719 Compare August 11, 2026 22:17

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 6136719 to fbafc56 Compare August 13, 2026 11:33

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from fbafc56 to 71a630e Compare August 17, 2026 06:39

gshaibi reviewed Aug 17, 2026

View reviewed changes

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch 2 times, most recently from af33664 to 64bb72d Compare August 17, 2026 10:55

davidLif and others added 4 commits August 17, 2026 14:00

docs(gpu-sharing): document NvFractions configuration

d889626

Signed-off-by: davidLif <davidshani12@gmail.com>

Add more explanations about nvFractions features

7afef57

Signed-off-by: davidLif <davidshani12@gmail.com>

Apply suggestions from code review

3ab998a

Co-authored-by: Guy Shaibi <39763067+gshaibi@users.noreply.github.com> Signed-off-by: davidLif <davidshani12@gmail.com>

Updated hami docs gpu-sharing install reference

9b9fd9a

Signed-off-by: davidLif <davidshani12@gmail.com>

davidLif force-pushed the codex/gpu-sharing-docs-pr152 branch from 64bb72d to 9b9fd9a Compare August 17, 2026 11:01


		KAI can auto-detect CDI and the CDI NRI plugin from the NVIDIA GPU Operator `ClusterPolicy`. When the `ClusterPolicy` indicates that CDI is enabled and selected as the default device injection path, KAI configures its CDI-aware binder plugins automatically. When NRI is enabled, KAI also enables the admission behavior that avoids injecting the legacy GPU-sharing environment variables.

		Use that detection to decide whether fractional GPU pods need a runtime class:


		### Choose an annotation style

		Use the annotation style that matches the cluster mode selected by your administrator. In `NvFractions` mode, the legacy `gpu-fraction` and `gpu-memory` annotations are still supported for backwards compatibility, but new memory-based workloads should prefer the per-container NvFractions request annotation.

Uh oh!

Conversation

davidLif commented Aug 10, 2026

Description

Related Issues

Checklist

Breaking Changes

Additional Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidLif Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

davidLif Aug 17, 2026 •

edited

Loading