Rename demo examples and add per-example documentation by willie-yao · Pull Request #170 · kubernetes-sigs/dra-example-driver

willie-yao · 2026-04-24T17:36:14Z

Fixes #144

This PR renames demos and keeps documentation for each demo in the yaml file itself. The main README is modified to run through the first 3 examples and a separate README under /demo gives an overview of the rest of the demos. Also the default number of GPUs was changed to 2 to more accurately reflect real world scenarios, with the trade-off of having to clean up after running each demo.

willie-yao · 2026-04-24T17:48:16Z

/assign @nojnhuh

nojnhuh · 2026-04-24T18:19:34Z

@alaypatel07 Do the DRA scalability tests use any of these demo manifests? Or just the driver itself and the tests define their own Pods, ResourceClaims, etc.?

alaypatel07 · 2026-04-24T18:24:54Z

The tests define their own pods.

nojnhuh · 2026-04-24T18:16:08Z

+# This demo shows the DRA admin access feature with DRA_ADMIN_ACCESS
+# environment variable.
+#
+# Key requirements:


I'm wondering if it makes sense to organize these examples by "profile"? i.e. demo/admin-access.yaml -> demo/gpu/admin-access.yaml

As we add more profiles, that would help users know how to install the driver to run this particular example. On the other hand, more generic features like admin access could work with any profile, so it might become harder to find than in a flat list like this.

Let's not change that right now, but something to consider later.

nojnhuh · 2026-04-24T18:34:16Z

+# Expected: The container has DRA_ADMIN_ACCESS=true and GPU_DEVICE env vars
+# for all available GPUs. Check with:
+#   kubectl logs -n admin-access pod0 -c ctr0 | grep DRA_ADMIN_ACCESS
+#   kubectl logs -n admin-access pod0 -c ctr0 | grep GPU_DEVICE


Definitely not something we need to do now, but it would be awesome if we could make comments like this drive the e2e tests as well as serve as human-readable documentation. Then we wouldn't need to update the test logic at all when adding an example.

nojnhuh · 2026-04-24T18:38:27Z

+#   - 1 ResourceClaimTemplate (multiple-gpus-admin)
+#   - 1 Pod (pod0) with 1 container
+#
+# GPUs required: all available (uses allocationMode: All)


Could we organize this in a new section titled something like "driver requirements" and also include the profile required? Right now only the "gpu" profile is implemented but we'll be adding more.

I see you added then removed the profile requirement. Was that intentional?

If we still want to include that, we can fold this "GPUs required" note under the "Driver requirements" section.

Whoops I thought it was redundant and forgot that you mentioned it in the comment! I'll add it back

nojnhuh · 2026-04-24T18:39:44Z

+#   - 1 ResourceClaimTemplate (multiple-gpus-admin)
+#   - 1 Pod (pod0) with 1 container
+#
+# GPUs required: all available (uses allocationMode: All)


Could we add a new section for cluster requirements? For example, Kubernetes version and feature gates. I'll go through and comment on each example. This one needs Kubernetes 1.34+ and the DRAAdminAccess feature.

nojnhuh · 2026-04-24T18:42:37Z

-# One pod, one container
-# Uses CEL expression selectors instead of matching on a DeviceClass
-# Selects a GPU with a specific model and at least 4Gi of memory
+# Example: CEL Expression Selectors


This one requires Kubernetes 1.34+, no additional features.

nojnhuh · 2026-04-24T19:11:51Z

Unrelated to this PR: I forgot about this script when reviewing #153 and now it's no longer called. Could you check to make sure these are all tested and port anything missing as part of #171?

Actually I don't think this was ever part of the e2e script and is only referenced in the README, so nothing to do here for #171.

nojnhuh · 2026-04-24T19:25:45Z

-gpu-test4   pod0   0/1     Pending             0          2s
-gpu-test5   pod0   0/4     Pending             0          2s
-...
+Clean up before the next example:


If we bump the default to 8 devices, then we wouldn't need to clean up in between each example. I've found it valuable before to have multiple examples running side-by-side at the same time to understand what's different between them. ResourceClaim status in particular is one of the more interesting parts that only exists at runtime and not in any of the manifests.

nojnhuh · 2026-04-27T18:56:50Z

-kind: List
-metadata:
-  resourceVersion: ""
+```bash


Can we try to keep the README changes scoped to only renaming the examples? I'm happy to incorporate drive-by improvements, but let's at least keep those in separate commits.

nojnhuh

I think this is good to go aside from renaming one more example.

nojnhuh · 2026-04-28T17:11:30Z

I think it's time to remove this since it uses the old names. It would be nice if each example had a README with its own Mermaid diagram or something. Not worth blocking this PR though IMO. I opened #176 to track that separately.

nojnhuh · 2026-04-28T17:12:28Z

+kubectl apply --filename=demo/basic-resourceclaimtemplate.yaml \
+  --filename=demo/basic-multiple-requests.yaml \
+  --filename=demo/basic-shared-claim-across-containers.yaml \
+  --filename=demo/shared-claim-across-pods.yaml \


I think it makes sense to make this a basic- one too.

nojnhuh · 2026-04-28T17:16:34Z

Actually I don't think this was ever part of the e2e script and is only referenced in the README, so nothing to do here for #171.

…entation Signed-off-by: William Yao <william2000yao@gmail.com>

nojnhuh

/lgtm
/approve

Thanks!

k8s-ci-robot · 2026-04-28T17:56:09Z

LGTM label has been added.

Details

Git tree hash: 3639fe2f601d766acf1db61d38e49cbc4768cf35

k8s-ci-robot · 2026-04-28T17:56:11Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: nojnhuh, willie-yao

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~~ [nojnhuh]

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

github-project-automation Bot added this to Dynamic Resource Allocation Apr 24, 2026

github-project-automation Bot moved this to 🆕 New in Dynamic Resource Allocation Apr 24, 2026

k8s-ci-robot requested a review from elezar April 24, 2026 17:36

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Apr 24, 2026

k8s-ci-robot requested a review from klueska April 24, 2026 17:36

k8s-ci-robot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Apr 24, 2026

willie-yao force-pushed the improve-docs branch from 71df894 to 4ceb0ec Compare April 24, 2026 17:43

k8s-ci-robot assigned nojnhuh Apr 24, 2026

nojnhuh reviewed Apr 24, 2026

View reviewed changes

pohly moved this from 🆕 New to 🏗 In progress in Dynamic Resource Allocation Apr 27, 2026

willie-yao force-pushed the improve-docs branch from 1b800b1 to db6ebeb Compare April 27, 2026 18:14

nojnhuh reviewed Apr 27, 2026

View reviewed changes

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Apr 27, 2026

nojnhuh mentioned this pull request Apr 28, 2026

Add diagrams for demo examples #176

Open

nojnhuh reviewed Apr 28, 2026

View reviewed changes

Rename demo examples with descriptive names and add per-example docum…

95ed732

…entation Signed-off-by: William Yao <william2000yao@gmail.com>

willie-yao force-pushed the improve-docs branch from 8b3282e to 95ed732 Compare April 28, 2026 17:40

nojnhuh approved these changes Apr 28, 2026

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 28, 2026

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 28, 2026

k8s-ci-robot merged commit a2ad0ff into kubernetes-sigs:main Apr 28, 2026
6 checks passed

pohly moved this from 🏗 In progress to ✅ Done in Dynamic Resource Allocation Apr 29, 2026

Conversation

willie-yao commented Apr 24, 2026

Uh oh!

willie-yao commented Apr 24, 2026

Uh oh!

nojnhuh commented Apr 24, 2026

Uh oh!

alaypatel07 commented Apr 24, 2026

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nojnhuh left a comment

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!

nojnhuh left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Apr 28, 2026

Uh oh!

k8s-ci-robot commented Apr 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants