kubernetes / kubernetes/website

Improve the quality of DRA documentation

Open
#49,899 13 comments 1 reaction 1 assignee Claimed by @shannonxtreme View on GitHub
kind/feature priority/important-longterm sig/docs triage/accepted wg/device-management
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

Description

Currently, our dynamic resource allocation (DRA) documentation is serviceable: https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/

However, given the newness of DRA as a tool in Kubernetes, we should improve the documentation around DRA to bring its quality up. This issue proposes the following updates:

* Concept page (https://kubernetes.io/docs/concepts/scheduling-eviction/dynamic-resource-allocation/)
* Improve the page structure to flow better, like **fundamentals, benefits, use cases, and terminology** > **deeper dive into the technology** > **advanced features like admin access, device status** > **logging and monitoring**.
* Remove mentions of the legacy design of DRA. Present structure parameters as the current and only way of using it.
* Compare with the device plugin method. When should you use which and why?
* Use well-known Kubernetes concepts like PersistentVolumes and Dynamic Volume Provisioning to help users to understand how it works.
* Use personas/user roles to separate the responsibilities for DRA concepts like DeviceClasses, ResourceSlices, drivers, etc.
* Show vendors where to go to learn how to integrate with DRA (KEPs, relevant code, example implementations (if we have any))
* Link to API reference docs and a task page for using it

* Task page (new)
* Basic task of using DRA with just the fundamentals (no advanced use cases)
* Make the concept page a prerequisite read
* Prereq: Install drivers in a cluster
* Use an example scenario to help the reader to follow the information (@sftim suggested LED devices being allocated by colour, for example)
* Set up DeviceClasses
* Set up ResourceClaimTemplates
* Deploy a workload that requests a device using a claim

* Mention DRA and link to it from relevant documentation. For example:
* does DRA change anything about how the scheduler makes decisions? Do https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/#kube-scheduler-implementation and/or https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/ need changes?
* https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/
* https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/

## Next steps

* Discuss what the minimum bar is and how to achieve it
* Draft the content and get it reviewed by the device-management working group + docs owners
* Send a PR
* ???
* Profit! (but not really because it's OSS)

/sig docs
/wg device-management
/priority important-soon
/cc @sftim @johnbelamaric

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.