Improve swap management concept

- Mention Linux swap behavior
- Mention Windows swap behavior
- Hyperlink to the tutorial for setup advice

Author: lmktfy

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

@@ -15,53 +15,17 @@ It also helps prevent Pods from being terminated during memory pressure spikes,
 shields nodes from system-level memory spikes that might compromise its stability,
 allows for more flexible memory management on the node, and much more.
 
-<!-- body -->
-
-## How to use it?
-
-### Prerequisites
-
-- Swap must be enabled and provisioned on the node.
-- The node must run a Linux operating system.
-- The node must use cgroup v2. Kubernetes does not support swap on cgroup v1 nodes.
+To learn about configuring swap in your cluster, read
+[Configuring swap memory on Kubernetes nodes](/docs/tutorials/cluster-management/provision-swap-memory/).
 
-## Enabling swap for Kubernetes Workloads
-
-To allow Kubernetes workloads to use swap,
-you must disable the kubelet's default behavior of failing when swap is detected,
-and specify memory-swap behavior as `LimitedSwap`:
-
-**Update kubelet configuration:**
- ```yaml
- # this fragment goes into the kubelet's configuration file
- failSwapOn: false
- memorySwap:
-     swapBehavior: LimitedSwap
-```
-
-The available choices for `swapBehavior` are:
-- `NoSwap` (default): Kubernetes workloads cannot use swap. However, processes
-  outside of Kubernetes' scope, like system daemons (such as kubelet itself!) can utilize swap.
-  This behavior is beneficial for protecting the node from system-level memory spikes,
-  but it does not safeguard the workloads themselves from such spikes.
-- `LimitedSwap`: Kubernetes workloads can utilize swap memory.
-  The amount of swap available to a Pod is determined automatically.
-  For more details, see the [section below](#how-is-the-swap-limit-being-determined-with-limitedswap).
-
-If configuration for `memorySwap` is not specified,
-by default the kubelet will apply the same behaviour as the `NoSwap` setting.
-
-Bear in mind that the following pods would be excluded from swap access
-(see more info in the [section below](#how-is-the-swap-limit-being-determined-with-limitedswap)):
-- Pods that are not classified as Burstable QoS.
-- Pods of High-priority.
-- Containers with memory limit that equals to memory request.
+<!-- body -->
 
-{{< note >}}
+## Operating system support
 
-Kubernetes only supports swap for Linux nodes.
-
-{{< /note >}}
+* Linux nodes support swap; you need to configure each node to enable it.
+  By default, the kubelet will **not** start on a Linux node that has swap enabled.
+* Windows nodes require swap space.
+  By default, the kubelet does **not** start on a Windows node that has swap disabled.
 
 ## How does it work?
 
@@ -79,6 +43,31 @@ Swap configuration on a node is exposed to a cluster admin via the
 As a cluster administrator, you can specify the node's behaviour in the
 presence of swap memory by setting `memorySwap.swapBehavior`.
 
+### Swap behaviors
+
+You need to pick a [swap behavior](/docs/reference/node/swap-behavior/) to
+use. Different nodes in your cluster can use different swap behaviors.
+
+The swap behaviors you can choose for Linux nodes are:
+
+`NoSwap` (default)
+: Workloads running as Pods on this node do not and cannot use swap.
+
+`LimitedSwap`
+: Kubernetes workloads can utilize swap memory.
+
+{{< note >}}
+If you choose the NoSwap behavior, and you configure the kubelet to tolerate
+swap space (`failSwapOn: false`), then your workloads don't use any swap.
+
+However, processes outside of Kubernetes-managed containers, such as systemi
+services (and even the kubelet itself!) **can** utilize swap.
+{{< /note >}}
+
+You can read [configuring swap memory on Kubernetes nodes](/docs/tutorials/cluster-management/provision-swap-memory/) to learn about enabling swap for your cluster.
+
+### Container runtime integration
+
 The kubelet uses the container runtime API, and directs the container runtime to
 apply specific configuration (for example, in the cgroup v2 case, `memory.swap.max`) in a manner that will
 enable the desired swap configuration for a container. For runtimes that use control groups, or cgroups,
@@ -357,7 +346,7 @@ For modern performance needs, a device such as a Solid State Drive (SSD) is prob
 as its low-latency electronic access minimizes the slowdown.
 
 
-## Swap Behavior Details
+## Swap behavior details
 
 ### How is the swap limit being determined with LimitedSwap?
 
@@ -398,6 +387,8 @@ Containers configured in this manner will not have access to swap memory.
 
 ## {{% heading "whatsnext" %}}
 
+- To learn about managing swap on Linux nodes, read
+  [configuring swap memory on Kubernetes nodes](/docs/tutorials/configuration/provision-swap-memory/).
 - You can check out a [blog post about Kubernetes and swap](/blog/2025/03/25/swap-linux-improvements/)
-- For more information, please see the original KEP, [KEP-2400](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2400-node-swap),
+- For background information, please see the original KEP, [KEP-2400](https://github.com/kubernetes/enhancements/tree/master/keps/sig-node/2400-node-swap),
 and its [design](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2400-node-swap/README.md).

content/en/docs/reference/node/_index.md

@@ -17,6 +17,8 @@ This section contains the following reference topics about nodes:
 
 * [Node `.status` information](/docs/reference/node/node-status/)
 
+* [Linux Node Swap Behaviors](/docs/reference/node/swap-behavior/)
+
 * [Seccomp information](/docs/reference/node/seccomp/)
 
 You can also read node reference details from elsewhere in the

content/en/docs/reference/node/swap-behavior.md

@@ -0,0 +1,22 @@
+---
+content_type: "reference"
+title: Linux Node Swap Behaviors
+weight: 110
+---
+
+To allow Kubernetes workloads to use swap, on a Linux node,
+you must disable the kubelet's default behavior of failing when swap is detected,
+and specify memory-swap behavior as `LimitedSwap`:
+
+The available choices for swap behavior are:
+
+`NoSwap`
+: (default) Workloads running as Pods on this node do not and cannot use swap. However, processes
+  outside of Kubernetes' scope, such as system daemons (including the kubelet itself!) **can** utilize swap.
+  This behavior is beneficial for protecting the node from system-level memory spikes,
+  but it does not safeguard the workloads themselves from such spikes.
+
+`LimitedSwap`
+: Kubernetes workloads can utilize swap memory. The amount of swap available to a Pod is determined automatically.
+
+To learn more, read [swap memory management](/docs/concepts/cluster-administration/swap-memory-management/).

content/en/docs/tutorials/cluster-management/provision-swap-memory.md

@@ -119,7 +119,14 @@ In a similar way, using systemd allows your server to leave swap active until ku
 
 ### Set up kubelet configuration
 
-After enabling swap on the node, kubelet needs to be configured in the following way:
+After enabling swap on the node, kubelet needs to be configured to use it.
+You need to select a [swap behavior](/docs/reference/node/swap-behavior/)
+for this node. You'll configure _LimitedSwap_ behavior for this tutorial.
+
+Find and edit the kubelet configuration file, and:
+
+- set `failSwapOn` to false
+- set `memorySwap.swapBehavior` to LimitedSwap
 
 ```yaml
  # this fragment goes into the kubelet's configuration file
@@ -129,3 +136,10 @@ After enabling swap on the node, kubelet needs to be configured in the following
 ```
 
 In order for these configurations to take effect, kubelet needs to be restarted. 
+Typically you do that by running:
+```shell
+systemctl restart kubelet.service
+```
+
+You should find that the kubelet is now healthy, and that you can run Pods
+that use swap memory as needed.