KEP-4671 Add docs for Workload API and Gang scheduling #53296

macsko · 2025-11-18T11:51:05Z

Description

This PR adds feature gates docs and a new Workload Aware Scheduling tab to the scheduling docs based on KEP-4671.

Issue

netlify · 2025-11-18T11:51:11Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`65f0e63`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-vnext-staging/deploys/691c5dac0ab615000890ac11

macsko · 2025-11-18T11:51:57Z

/cc @dom4ha @sanposhiho @wojtek-t @erictune

netlify · 2025-11-18T12:00:25Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`65f0e63`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/691c5dace990f60008466afd
😎 Deploy Preview	https://deploy-preview-53296--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

erictune

Text looks good.

Should the new concepts page be linked from somewhere?

k8s-ci-robot · 2025-11-18T17:48:06Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: erictune
Once this PR has been reviewed and has the lgtm label, please assign natalisucks for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

content/en/docs/OWNERS

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

lmktfy

Thanks for the PR.

Because Pod is a stable API, you also need to update the Pod documentation. You need to do this work even though the new APIs are only alpha.
Explain that the behavior of Pod depends on whether the reader, a cluster administrator, has or has not enabled the relevant feature gates.

Watch out for putting new documentation in one page. It's tempting to do that because what you are documenting is part of one package of improvements; however, readers learn about different elements of Kubernetes in different pages, and these improvements touch on several of those (not just scheduling).

I would put most of the new content into the Workloads
section of the docs, for example by adding a section about Pod groups, at one of:
• https://kubernetes.io/docs/concepts/workloads/pod-groups/
• https://kubernetes.io/docs/concepts/workloads/pods/groups/

(I prefer the former, personally; PodGroup is an API separate from Pod).

Gang scheduling, however, I would place at
• https://kubernetes.io/docs/concepts/scheduling-eviction/gang-scheduling/

You can also, either for alpha or beta, work with SIG Docs to add a new tutorial. If you do, various other pages can and should link there.

lmktfy · 2025-11-18T17:53:41Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

+weight: 120
+---
+
+This page provides an overview of Workload Aware Scheduling (WAS), a Kubernetes feature


Suggested change

This page provides an overview of Workload Aware Scheduling (WAS), a Kubernetes feature

This page provides an overview of _workload aware scheduling_ (WAS), a Kubernetes feature

lmktfy · 2025-11-18T17:54:11Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

+
+{{< feature-state feature_gate_name="GenericWorkload" >}}
+
+The `Workload` API resource, available from the `scheduling.k8s.io/v1alpha1` API group, allows you to logically group a set of Pods.


Following the style guide, you wouldn't use backticks around Workload. I recommend removing them.

lmktfy · 2025-11-18T18:01:22Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

+  # ...
+```
+
+## Scheduling Policies


We should update the Policies concept page to hyperlink to wherever we end up putting this section.

lmktfy · 2025-11-18T18:01:51Z

content/en/docs/reference/command-line-tools-reference/feature-gates/GangScheduling.md

+---
+
+Enables the GangScheduling plugin in kube-scheduler, which implements "all-or-nothing"
+scheduling algorithm. The Workload API is used to express the requirements.


(nit) Workload could be a hyperlink

lmktfy · 2025-11-18T18:02:22Z

content/en/docs/reference/command-line-tools-reference/feature-gates/GenericWorkload.md

+---
+
+Enables the scheduling.k8s.io/v1alpha1 Workload API to express scheduling requirements
+at the workload level. Pods can now reference a specific Workload PodGroup using the spec.workloadRef field.


(nit) PodGroup and Workload could be hyperlinks.

lmktfy · 2025-11-18T18:03:12Z

content/en/docs/reference/command-line-tools-reference/feature-gates/GenericWorkload.md

+    fromVersion: "1.35"
+---
+
+Enables the scheduling.k8s.io/v1alpha1 Workload API to express scheduling requirements


No it doesn't, surely. You must also enable that API group separately?

lmktfy · 2025-11-18T18:05:14Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

+spec:
+  # controllerRef provides a link to the object that manages this Workload,
+  # such as a Kubernetes Job. This is for tooling and observability.
+  controllerRef:


we may need to explain the difference between "the Job controller" (which is a controller) and "a Job" (which represents a desired and observed state that the Job controller operates on)

lmktfy · 2025-11-18T18:06:03Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

+because no single node has enough capacity for them. The job cannot run,
+but the scheduled Pods waste expensive resources that other applications could use.
+
+Workload Aware Scheduling introduces a mechanism for the scheduler to identify and manage a group of Pods as a single, atomic workload.


Aim to write the documentation mostly as if the feature is already generally available, and then garnish it with caveats about it actually being alpha.

Good documentation is often timeless

lmktfy · 2025-11-18T18:11:29Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

I wouldn't add this file at all.

lmktfy · 2025-11-18T20:16:27Z

/sig scheduling node

lmktfy · 2025-11-18T20:55:28Z

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

+
+## What is Workload Aware Scheduling?
+
+The default Kubernetes scheduler makes decisions for one Pod at a time. This model works sufficiently good for stateless applications,


This isn't exactly true. The default scheduler's behavior, at the time this doc is live, depends on whether you have enabled the GangScheduling feature gate.

v1.35 K8s will, of course, support gang scheduling (as alpha), in-tree.

macsko · 2025-11-20T13:45:56Z

@lmktfy thank you for your valuable review. Just to be on the same page:

Because Pod is a stable API, you also need to update the Pod documentation.

What Pod documentation are you referring to? Are you talking about mentioning WorkloadReference somewhere in the “https://kubernetes.io/docs/concepts/workloads/pods/” section, or somewhere else?

I would put most of the new content into the Workloads section of the docs

So I should split the documentation page into two parts: move the part about the PodGroups to https://kubernetes.io/docs/concepts/workloads/pods-groups/, and the part about Gang Scheduling to https://kubernetes.io/docs/concepts/scheduling-eviction/gang-scheduling/, right? Should I describe the part about (whole) Workload API in the PodGroups docs or somewhere else?

You can also, either for alpha or beta, work with SIG Docs to add a new tutorial.

Good idea, let's do that for the beta.

KEP-4671 Add docs for Workload API and Gang scheduling

65f0e63

k8s-ci-robot added this to the 1.35 milestone Nov 18, 2025

k8s-ci-robot added the language/en Issues or PRs related to English language label Nov 18, 2025

k8s-ci-robot requested review from katcosgrove and shannonxtreme November 18, 2025 11:51

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Nov 18, 2025

macsko mentioned this pull request Nov 18, 2025

Placeholder for KEP4671 #52898

Closed

k8s-ci-robot requested review from dom4ha, erictune, sanposhiho and wojtek-t November 18, 2025 11:51

erictune approved these changes Nov 18, 2025

View reviewed changes

lmktfy reviewed Nov 18, 2025

View reviewed changes

content/en/docs/concepts/scheduling-eviction/workload-aware-scheduling.md

Copy link

Member

lmktfy Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't add this file at all.

k8s-ci-robot added sig/scheduling Categorizes an issue or PR as relevant to SIG Scheduling. sig/node Categorizes an issue or PR as relevant to SIG Node. labels Nov 18, 2025

github-project-automation bot added this to SIG Scheduling and SIG Node: code and documentation PRs Nov 18, 2025

github-project-automation bot moved this to Triage in SIG Node: code and documentation PRs Nov 18, 2025

lmktfy reviewed Nov 18, 2025

View reviewed changes

helayoty moved this to Needs Review in SIG Scheduling Nov 19, 2025

	This page provides an overview of Workload Aware Scheduling (WAS), a Kubernetes feature
	This page provides an overview of _workload aware scheduling_ (WAS), a Kubernetes feature


		{{< feature-state feature_gate_name="GenericWorkload" >}}

		The `Workload` API resource, available from the `scheduling.k8s.io/v1alpha1` API group, allows you to logically group a set of Pods.


		## What is Workload Aware Scheduling?

		The default Kubernetes scheduler makes decisions for one Pod at a time. This model works sufficiently good for stateless applications,

KEP-4671 Add docs for Workload API and Gang scheduling #53296

Are you sure you want to change the base?

KEP-4671 Add docs for Workload API and Gang scheduling #53296

Conversation

macsko commented Nov 18, 2025

Description

Issue

Uh oh!

netlify bot commented Nov 18, 2025

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Uh oh!

macsko commented Nov 18, 2025

Uh oh!

netlify bot commented Nov 18, 2025

✅ Pull request preview available for checking

Uh oh!

erictune left a comment

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Nov 18, 2025

Uh oh!

lmktfy left a comment • 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!

lmktfy Nov 18, 2025 • 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!

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!

lmktfy commented Nov 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

macsko commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lmktfy left a comment •

edited

Loading

lmktfy Nov 18, 2025 •

edited

Loading