Documentation for Swap memory management #51303

iholder101 · 2025-06-19T11:21:39Z

Description

Add documentation for KEP-2400 NodeSwap GA.

Basically, this PR does 2 things:

Creates a new dedicated swap memory management documentation under content/en/docs/concepts/cluster-administration/swap-memory-management.md. This documentation is heavily based on the contents of the latest blog-post about swap memory: https://kubernetes.io/blog/2025/03/25/swap-linux-improvements/. While the content is very similar, there are minor updates.
Removes the old very minimal swap documentation that existed under content/en/docs/concepts/architecture/nodes.md.

This documentation should contain everything the user needs to know for swap GA.

Issue

Fixes #51153

Signed-off-by: Itamar Holder <iholder@redhat.com>

k8s-ci-robot · 2025-06-19T11:21:45Z

[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 divya-mohan0209 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

netlify · 2025-06-19T11:30:52Z

✅ Pull request preview available for checking

Built without sensitive environment variables

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

iholder101 · 2025-06-19T11:33:08Z

/cc @ajaysundark

iholder101 · 2025-06-19T11:34:22Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+
+<!-- body -->
+
+## In which cases swap can be valuable?


@lmktfy I was hesitating to whether this fits to documentation.
What do you think? If it is I can gladly fill this section up.

How about saving the Q&A for a blog article (which can be evergreen)?

lmktfy

Thank you for working on this - it's really needed.

Here's quite a lot of feedback.

lmktfy · 2025-06-19T11:46:29Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+
+<!-- overview -->
+
+Swap is a fundamental and an invaluable Linux feature.


Watch out for implying that Windows doesn't support paging. It's not that backwards!

lmktfy · 2025-06-19T11:46:50Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+memory by swapping out unused data,
+shielding nodes from system-level memory spikes,
+preventing Pods from crashing when they hit their memory limits,
+and [much more](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2400-node-swap/README.md#user-stories).


Avoid hyperlinking to KEPs from the running text of docs.

lmktfy · 2025-06-19T11:47:03Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+As a result, the node special interest group within the Kubernetes project
+has invested significant effort into supporting swap on Linux nodes.


Suggested change

As a result, the node special interest group within the Kubernetes project

has invested significant effort into supporting swap on Linux nodes.

True, but not right for our docs.

lmktfy · 2025-06-19T11:47:41Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+
+<!-- body -->
+
+## In which cases swap can be valuable?


How about saving the Q&A for a blog article (which can be evergreen)?

lmktfy · 2025-06-19T11:48:18Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+{{< note >}}
+
+If configuration for `memorySwap` is not specified,
+by default the kubelet will apply the same behaviour as the `NoSwap` setting.
+
+{{< /note >}}
+
+{{< note >}}
+
+On Linux nodes, Kubernetes only supports running with swap enabled for hosts that use cgroup v2.
+On cgroup v1 systems, all Kubernetes workloads are not allowed to use swap memory.
+
+{{< /note >}}


Avoid consecutive notes.

The main note to add is that Kubernetes only supports configurable swap for Linux nodes; Windows nodes just have it unconditionally.

lmktfy · 2025-06-19T11:58:20Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+priority to system critical daemons. See the relevant section in the
+[recommended practices](#good-practice-for-using-swap-in-a-kubernetes-cluster) section below.
+
+### Memory-backed volumes


I recommend adding a page (or stub) that is like https://kubernetes.io/docs/concepts/security/windows-security/ but for Linux. That page should hyperlink here.

https://kubernetes.io/docs/concepts/security/secrets-good-practices/ should link here

lmktfy · 2025-06-19T11:59:11Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+  * If the `noswap` option is not supported, kubelet will emit a warning log entry,
+    then continue its execution.
+
+It is deeply encouraged to encrypt the swap space.


Put this in a caution block, at the start of the Risks and caveats section, and then hyperlink to this section. It's really important.

lmktfy · 2025-06-19T12:00:42Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+### Use of a dedicated disk for swap
+
+It is recommended to use a separate, encrypted disk for the swap partition.
+If swap resides on a partition or the root filesystem, workloads may interfere
+with system processes that need to write to disk.
+When they share the same disk, processes can overwhelm swap,
+disrupting the I/O of kubelet, container runtime, and systemd, which would impact other workloads.
+Since swap space is located on a disk, it is crucial to ensure the disk is fast enough for the intended use cases.
+Alternatively, one can configure I/O priorities between different mapped areas of a single backing device.


I'd tweak this. Using a dedicated device is one option, but it's not universally a good practice.

I suppose we should caution people to avoid rotational swap.

lmktfy · 2025-06-19T12:01:14Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+## Looking ahead
+
+Swap was intentionally scoped as a minimal feature for the initial release,
+which can and should be incrementally extended in the future.
+
+In the near future, additional features are planned to further improve swap capabilities,
+including better eviction mechanisms, extended API support, increased customizability,
+better debug abilities and more!
+
+Our future plans will depend on user feedback and the community's needs.
+Therefore, we encourage you to try out the current implementation and share your experiences with us.


We explicitly avoid statements about the future

lmktfy · 2025-06-19T12:01:39Z

content/en/docs/concepts/cluster-administration/swap-memory-management.md

+## How can I learn more?
+
+You can check out the latest [blog-post about swap](/content/en/blog/_posts/2025-03-25-swap-fresh-improvements.md).
+
+For more information, please see [KEP-2400](https://github.com/kubernetes/enhancements/issues/4128) and its
+[design proposal](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2400-node-swap/README.md).
+
+## How do I get involved?
+
+Your feedback is always welcome! SIG Node [meets regularly](https://github.com/kubernetes/community/tree/master/sig-node#meetings)
+and [can be reached](https://github.com/kubernetes/community/tree/master/sig-node#contact)
+via [Slack](https://slack.k8s.io/) (channel **#sig-node**), or the SIG's
+[mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-node). A Slack
+channel dedicated to swap is also available at **#sig-node-swap**.
+
+Feel free to reach out to me, Itamar Holder (**@iholder101** on Slack and GitHub)
+if you'd like to help or ask further questions.


Suggested change

## How can I learn more?

You can check out the latest [blog-post about swap](/content/en/blog/_posts/2025-03-25-swap-fresh-improvements.md).

For more information, please see [KEP-2400](https://github.com/kubernetes/enhancements/issues/4128) and its

[design proposal](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2400-node-swap/README.md).

## How do I get involved?

Your feedback is always welcome! SIG Node [meets regularly](https://github.com/kubernetes/community/tree/master/sig-node#meetings)

and [can be reached](https://github.com/kubernetes/community/tree/master/sig-node#contact)

via [Slack](https://slack.k8s.io/) (channel **#sig-node**), or the SIG's

[mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-node). A Slack

channel dedicated to swap is also available at **#sig-node-swap**.

Feel free to reach out to me, Itamar Holder (**@iholder101** on Slack and GitHub)

if you'd like to help or ask further questions.

Use a whatsnext section (search docs for whatsnext to see how we do this).

iholder101 added 2 commits June 19, 2025 14:11

Documentation for Swap memory management

d0b9ea8

Signed-off-by: Itamar Holder <iholder@redhat.com>

Remove old swap docs from 'nodes' page

9885427

Signed-off-by: Itamar Holder <iholder@redhat.com>

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jun 19, 2025

k8s-ci-robot requested review from dchen1107 and lmktfy June 19, 2025 11:21

k8s-ci-robot added language/en Issues or PRs related to English language size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Jun 19, 2025

k8s-ci-robot requested a review from ajaysundark June 19, 2025 11:33

iholder101 commented Jun 19, 2025

View reviewed changes

lmktfy reviewed Jun 19, 2025

View reviewed changes


		<!-- overview -->

		Swap is a fundamental and an invaluable Linux feature.

		As a result, the node special interest group within the Kubernetes project
		has invested significant effort into supporting swap on Linux nodes.

Documentation for Swap memory management #51303

Are you sure you want to change the base?

Documentation for Swap memory management #51303

Conversation

iholder101 commented Jun 19, 2025

Description

Issue

Uh oh!

k8s-ci-robot commented Jun 19, 2025

Uh oh!

netlify bot commented Jun 19, 2025

✅ Pull request preview available for checking

Uh oh!

iholder101 commented Jun 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmktfy 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!

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!