kubernetes / kubernetes/website
Improve the quality of DRA documentation
- 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
Assessment
This issue has not been assessed yet.