Kubernetes Node Swap: How Memory Management Works

Updated on Oct 22, 2026

10 min read

Kubernetes node swap lets Linux worker nodes use configured swap space while the kubelet applies a policy for whether container workloads may use it. Platform engineers considering swap need to distinguish host configuration from Pod resource accounting: swap can absorb some inactive memory, but it is slower than RAM and does not give the scheduler more physical memory. This guide explains the controls, eligibility rules, and operational checks behind Kubernetes NodeSwap.

Why Kubernetes Node Swap Is Being Discussed

Containerized services do not all use memory in the same way. Some keep most of their working set active, while others have bursts or infrequently used pages that can be moved out of RAM. Operators may consider swap to make a node more tolerant of those peaks or to use memory capacity more flexibly, especially when a workload can accept additional latency.

That trade-off is now explicit in Kubernetes configuration rather than being only an operating-system decision. The Kubernetes project documents node swap as part of its node and kubelet configuration guidance. The feature is useful to understand even when a cluster keeps swap disabled: it clarifies how the kubelet, Linux kernel, and container resource policy interact.

What Is Kubernetes Node Swap?

Swap is disk-backed space that Linux can use to hold memory pages that are not currently resident in RAM. A page fault brings a swapped page back into memory, which can add substantial latency compared with accessing RAM. Swap is therefore a pressure-management mechanism, not equivalent to more physical memory.

Kubernetes NodeSwap is the kubelet’s policy for operating on a Linux node where the administrator has already configured swap. The Kubernetes node documentation describes swap management, while the kubelet configuration reference defines failSwapOn and memorySwap.swapBehavior.

The default behavior, NoSwap, prevents workloads from using swap. LimitedSwap permits bounded swap use according to the workload policy; its limit is proportionate to the container’s memory request. The Node memory swap enhancement proposal describes the design, including the focus on Burstable Pods and Linux cgroup v2. Enabling swap on the host alone does not opt every Pod into using it.

What Problem Does It Solve?

Without swap, a node has to keep active workload pages in RAM or reclaim memory through other means. Under pressure, Linux can reclaim cache, and Kubernetes can evict Pods according to node-pressure behavior. If the host cannot reclaim enough memory, an out-of-memory condition can terminate processes. These mechanisms protect a system from exhausting memory, but can disrupt workloads.

Swap offers another place for eligible, less-active pages. That can help a node ride through a short-lived increase in memory demand, but it does not prevent the causes of that increase. If a workload continuously needs more memory than the node can provide, swapping can turn a capacity shortage into sustained storage I/O, slow page faults, and poor application latency.

It also does not change Kubernetes scheduling math. Pod memory requests and limits still describe memory resources; swap is not advertised as additional schedulable RAM. Operators should continue to size nodes and workloads for their expected resident working sets. For the distinction between changing a Pod’s allocation and changing node behavior, see Kubernetes in-place Pod resizing.

How Node Swap Works

The operating system administrator first enables and configures swap on the Linux node. The kubelet then decides whether to start when swap exists and, separately, whether container workloads may use it. The configuration reference describes failSwapOn as defaulting to true, so a node with swap enabled needs an intentional kubelet policy rather than relying on an implicit default.

With failSwapOn: false, the kubelet can start while host swap is enabled. This setting alone is not permission for Pods to use swap. memorySwap.swapBehavior controls workload access: NoSwap is the default, and LimitedSwap applies a bounded policy. In the NodeSwap design, limited swap is for Burstable QoS Pods; Guaranteed and BestEffort Pods do not receive swap under that policy.

On cgroup v2 Linux nodes, the kernel exposes separate memory and swap controls for workload cgroups. Kubernetes and the container runtime translate the kubelet’s policy into those controls. The Linux cgroup v2 documentation describes files such as memory.swap.current and memory.swap.max: one reports current swap use and the other caps it. The Open Container Initiative Runtime Specification describes the Linux resource configuration used at the container-runtime layer; it does not decide Kubernetes Pod eligibility.

Concern	`NoSwap`	`LimitedSwap`
Workload access	Workloads cannot use swap	Eligible workloads can use a bounded amount
Pod eligibility	No workload swap	Burstable QoS Pods in the NodeSwap design
Limit basis	No workload swap allowance	Proportionate to the container’s memory request
Host requirement	Kubelet policy still needs to account for enabled host swap	Linux swap and compatible cgroup v2 support are required
Main trade-off	Avoids swap-related latency for Pods	May soften brief pressure but can add I/O latency

The feature does not create swap space, choose a suitable device, or configure the host’s storage. Nor does it guarantee that a Pod will remain responsive when its pages are moved to swap. Operators must consider node-wide I/O, latency targets, swap capacity, and the behavior of the applications sharing that node.

Components and Key Concepts

Host swap: Linux must have a swap device or file activated before the kubelet can use a swap policy. The operating system owns its size, location, and lifecycle; Kubernetes does not provision it.
failSwapOn: This kubelet setting controls whether swap on the node prevents kubelet startup. Setting it to false permits startup with host swap, but does not by itself allow Pod swap.
memorySwap.swapBehavior: This selects the workload policy. NoSwap is the default. LimitedSwap enables the bounded behavior supported by the node and Kubernetes configuration.
QoS and memory requests: Under the NodeSwap design, only Burstable Pods can use limited swap. Their memory requests inform the limit. Requests still affect scheduling and accounting; they are not a guarantee of fast memory or a reservation of swap.
Cgroup v2: The kernel’s memory.swap.* files expose per-cgroup swap accounting and control. Inspect the cgroup for the workload rather than assuming a single node-level number explains every Pod.
Pressure and eviction: Swap does not replace Kubernetes memory-pressure signals, eviction thresholds, or application monitoring. Compare swap use with memory pressure, latency, restarts, and node I/O. Linux Pressure Stall Information explains how to measure time tasks lose while waiting on resources.

Kubernetes does not define NodeSwap as an RFC-level network or storage protocol. The behavior is implemented across kubelet policy, Linux cgroups, the kernel, and the runtime. For a broader explanation of the kernel controls involved, see Linux cgroups and resource management.

Real-World Use Cases

Swap may be worth testing for batch or background workloads that have occasional memory peaks and can tolerate slower access to infrequently used pages. It can also provide an operational buffer during transient pressure while an autoscaler or operator responds. In both cases, the target is better resilience under a known workload profile, not a higher steady-state throughput claim.

Latency-sensitive services, databases, and workloads with large active working sets need stricter evaluation. If those processes begin paging heavily, response times can degrade even while the node avoids an immediate out-of-memory event. A node with swap can also experience storage contention that affects unrelated workloads.

Use a representative workload in a test pool first. Measure application latency and error rates alongside memory use, swap activity, cgroup limits, and node I/O. Keep a rollback path that restores the prior kubelet policy and host configuration.

Getting Started: Configure and Verify a Test Node

NodeSwap is a Linux node configuration, not an additional package to install. Before changing production nodes, confirm the Kubernetes release, kubelet configuration mechanism, Linux cgroup mode, runtime, and distribution-specific swap setup. Make the change on a disposable or drained test node and follow the node administrator’s maintenance procedure.

First inspect host swap, memory, and cgroup mode:

swapon --show
free -h
cat /proc/swaps
stat -fc %T /sys/fs/cgroup

For cgroup v2, stat should report cgroup2fs for the unified hierarchy. A different result means the node does not expose the cgroup v2 interface used for per-workload limited swap. Check the kernel cgroup documentation and your Kubernetes distribution’s support details before proceeding.

Merge the intended values into the node’s existing KubeletConfiguration; do not replace a managed configuration file wholesale:

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
failSwapOn: false
memorySwap:
  swapBehavior: LimitedSwap

LimitedSwap is an explicit policy choice. Use NoSwap if the goal is only to let kubelet start while host swap remains enabled, or leave failSwapOn at its default and keep host swap disabled. The correct configuration path and restart procedure depend on how the cluster installed and manages kubelet. Apply the change to one test node using that procedure, then verify kubelet health and node readiness:

sudo systemctl status kubelet --no-pager
kubectl get nodes -o wide
kubectl describe node "$NODE"

On systemd-based nodes, inspect kubelet logs if it fails to start or the node does not become Ready:

sudo journalctl -u kubelet --since "15 minutes ago" --no-pager

To verify actual use, inspect the cgroup v2 files for a process in the target Pod. Locate its cgroup using the runtime and /proc/<pid>/cgroup, then read that cgroup’s memory.swap.current and memory.swap.max if available. Compare those values with host swap and application telemetry during a controlled workload test. Node readiness alone does not prove a Pod can use swap or that its latency remains acceptable.

If results show sustained swap activity, rising storage latency, or application impact, revert the test policy and investigate the workload’s memory profile. Depending on the cause, options include tuning the application, adjusting Pod requests and limits, scaling replicas, or adding node capacity. Kubernetes cluster autoscaling and node provisioning covers the node-capacity side of that decision.

Common Misconceptions

“Enabling swap gives Kubernetes more schedulable memory.” It does not. The scheduler continues to place Pods using Kubernetes resource requests and node capacity. Swap changes how eligible memory pages may be backed on a running Linux node.

“failSwapOn: false means every Pod can swap.” This setting permits kubelet startup when host swap exists. The separate memorySwap.swapBehavior policy controls workload use, and NoSwap remains the default.

“Swap prevents out-of-memory events.” Swap can delay pressure in some cases, but a finite device can fill, active pages can still be needed, and the workload can exceed its memory limit. Kubernetes eviction, kernel out-of-memory behavior, and application failure remain possible.

“More swap always improves density.” Paging can increase I/O and latency, and swap is not a substitute for adequate RAM. Measure real workloads before changing placement or capacity assumptions.

Changelog

2026-10-22: Initial publication; kubelet and cgroup behavior checked against Kubernetes and Linux documentation.