KEP-2570: Add documentation for MemoryQoS with cgroups v2 for 1.36 by QiWang19 · Pull Request #54417 · kubernetes/website

QiWang19 · 2026-02-12T17:45:43Z

Description

This is a placeholder PR for the documentation of MemoryQoS v1.36, which is targeting Alpha v3 for the 1.36 release.

k/e KEP: kubernetes/enhancements#5879
k/e issue: kubernetes/enhancements#2570

Issue

Closes: #

k8s-ci-robot · 2026-02-12T17:45:53Z

Welcome @QiWang19!

It looks like this is your first PR to kubernetes/website 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/website has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2026-02-12T17:45:59Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

Details

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

netlify · 2026-02-12T17:55:07Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`deeff10`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/69c4ae819b6b7f0008691fe2
😎 Deploy Preview	https://deploy-preview-54417--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.

kernel-kun · 2026-03-20T08:52:53Z

Hello @QiWang19 👋, v1.36 Docs Team here again!

Please take a look at Documenting for a release - PR Ready for Review to get your PR ready for review before Tuesday 31st March 2026.

Please let us know once your PR is fully Ready for Review -- meaning all documentation updates are complete and it's awaiting reviewer feedback -- so we can update our tracking.

Thank you!

Signed-off-by: Qi Wang <qiwan@redhat.com>

QiWang19 · 2026-03-27T21:53:42Z

@sohankunkerkar @ndixita could you review?

sohankunkerkar · 2026-03-30T20:39:14Z

content/en/docs/concepts/workloads/pods/pod-qos.md

+- Linux with cgroup v2
+- Kernel version 5.9 or higher for safe memory.high throttling. If the MemoryQoS feature gate is enabled on an older kernel, the kubelet logs a warning because of a known kernel livelock bug when using `memory.high` throttling on older kernels.
+
+Memory QoS requires cgroup v2. When enabled on kernels older than 5.9, kubelet logs a warning


This looks duplicated. You might need to remove these lines

sohankunkerkar · 2026-03-30T20:40:01Z

content/en/docs/concepts/workloads/pods/pod-qos.md

+  - Burstable pods (soft reservation): `memory.low` is set to memory requests, the kernel preferentially retains this memory but may reclaim it under extreme pressure.
+  - BestEffort pods: no memory protection is set.
+
+If memory limits are set in the container,this means that the system needs to limit container memory usage; Memory QoS uses `memory.high` to throttle workloads


Suggested change

If memory limits are set in the container,this means that the system needs to limit container memory usage; Memory QoS uses `memory.high` to throttle workloads

If memory limits are set in the container, this means that the system needs to limit container memory usage; Memory QoS uses `memory.high` to throttle workloads

Also, this piece applies regardless of memoryReservationPolicy. Should be moved before "### Configuring Memory QoS" or into its own subsection (e.g., "### Memory Throttling") since throttling is independent of reservation policy.

sohankunkerkar · 2026-03-30T20:43:35Z

content/en/docs/concepts/configuration/manage-resources-containers.md

+controlled by `memoryThrottlingFactor`, and reservation is controlled by
+`memoryReservationPolicy` (default `None`, optional `TieredReservation`).
+Kubelet logs a warning on kernels older than 5.9 because `memory.high` throttling
+can trigger a kernel livelock bug on older kernels.


Suggested change

can trigger a kernel livelock bug on older kernels.

can trigger a kernel livelock bug.

sohankunkerkar · 2026-03-30T20:44:45Z

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

-cgroup v2 memory controller.
+cgroup v2 memory controller. This feature allows kubelet to set `memory.high`
+for throttling and configure tiered memory protection, when `memoryReservationPolicy` kubelet
+configuration set to `TieredReservation`, `memory.min` / `memory.low` for memory protection are enabled.


Suggested change

configuration set to `TieredReservation`, `memory.min` / `memory.low` for memory protection are enabled.

configuration is set to `TieredReservation`, `memory.min` / `memory.low` for memory protection are enabled.

sohankunkerkar · 2026-03-30T20:46:49Z

content/en/docs/concepts/configuration/manage-resources-containers.md

-due to a potential livelock situation a memory hungry can cause.
+There is an alpha feature `MemoryQoS` which adds preemptive memory throttling
+and optional memory reservation on Linux nodes using cgroup v2. Throttling is
+controlled by `memoryThrottlingFactor`, and reservation is controlled by


I think you would need to add a blurb about memoryThrottlingFactor in pod-qos.md as well. Otherwise, Readers will wonder what it does

kernel-kun · 2026-04-02T06:16:28Z

Hello @QiWang19 👋, v1.36 Docs Team here again!

Just checking in as we approach Docs Freeze on Wednesday 8th April 2026 (AoE) / Thursday 9th April 2026, 12:00 UTC.

This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs.

Thank you!

k8s-ci-robot added this to the 1.36 milestone Feb 12, 2026

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 12, 2026

k8s-ci-robot added the language/en Issues or PRs related to English language label Feb 12, 2026

k8s-ci-robot requested review from nate-double-u and salaxander February 12, 2026 17:45

k8s-ci-robot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Feb 12, 2026

QiWang19 mentioned this pull request Feb 12, 2026

Support memory qos with cgroups v2 kubernetes/enhancements#2570

Open

12 tasks

Add documentation for MemoryQoS with cgroups v2 for 1.36

deeff10

Signed-off-by: Qi Wang <qiwan@redhat.com>

QiWang19 force-pushed the 2570-doc-placeholder branch from 1d1387d to deeff10 Compare March 26, 2026 03:56

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Mar 26, 2026

QiWang19 marked this pull request as ready for review March 27, 2026 14:37

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Mar 27, 2026

k8s-ci-robot requested review from SayakMukhopadhyay and windsonsea March 27, 2026 14:37

QiWang19 changed the title ~~Add documentation for MemoryQoS with cgroups v2 for 1.36~~ KEP-2570: Add documentation for MemoryQoS with cgroups v2 for 1.36 Mar 27, 2026

sohankunkerkar reviewed Mar 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

KEP-2570: Add documentation for MemoryQoS with cgroups v2 for 1.36#54417

KEP-2570: Add documentation for MemoryQoS with cgroups v2 for 1.36#54417
QiWang19 wants to merge 1 commit intokubernetes:dev-1.36from
QiWang19:2570-doc-placeholder

QiWang19 commented Feb 12, 2026

Uh oh!

k8s-ci-robot commented Feb 12, 2026

Uh oh!

k8s-ci-robot commented Feb 12, 2026

Uh oh!

netlify bot commented Feb 12, 2026 •

edited

Loading

Uh oh!

kernel-kun commented Mar 20, 2026

Uh oh!

QiWang19 commented Mar 27, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Uh oh!

kernel-kun commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	If memory limits are set in the container,this means that the system needs to limit container memory usage; Memory QoS uses `memory.high` to throttle workloads
	If memory limits are set in the container, this means that the system needs to limit container memory usage; Memory QoS uses `memory.high` to throttle workloads

	can trigger a kernel livelock bug on older kernels.
	can trigger a kernel livelock bug.

	configuration set to `TieredReservation`, `memory.min` / `memory.low` for memory protection are enabled.
	configuration is set to `TieredReservation`, `memory.min` / `memory.low` for memory protection are enabled.

Conversation

QiWang19 commented Feb 12, 2026

Description

Issue

Uh oh!

k8s-ci-robot commented Feb 12, 2026

Uh oh!

k8s-ci-robot commented Feb 12, 2026

Uh oh!

netlify bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

kernel-kun commented Mar 20, 2026

Uh oh!

QiWang19 commented Mar 27, 2026

Uh oh!

sohankunkerkar Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sohankunkerkar Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sohankunkerkar Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sohankunkerkar Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sohankunkerkar Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

sohankunkerkar Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

kernel-kun commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify bot commented Feb 12, 2026 •

edited

Loading