Kubernetes nodes need enough memory to run application containers, system services, the kubelet, and the container runtime. When memory becomes scarce, workloads may experience memory pressure, containers can be terminated, and the node may become unstable.
Linux swap provides an additional mechanism for managing memory pressure. It allows the operating system to move eligible memory pages from RAM to disk-backed storage, freeing physical memory for other work. However, swap is not a substitute for sufficient RAM, and excessive swapping can increase application latency.
Historically, Kubernetes commonly required swap to be disabled on Linux nodes. Modern Kubernetes releases support configurable swap behavior, allowing administrators to enable swap under defined conditions. The exact behavior depends on the Kubernetes version, kubelet configuration, container runtime, and operating system.
This article explains how node swap works, how to configure it for Kubernetes, how to monitor its effects, and what to consider before enabling it in a production cluster.
What Is Swap in Linux?
Physical RAM provides fast access to data used by running processes. When memory pressure increases, Linux can move certain memory pages to swap space, which may be backed by a disk partition or a swap file.
Moving pages out of RAM can help the operating system keep more workloads running. However, accessing swapped-out pages requires additional I/O. If an application repeatedly needs pages that have been moved to swap, it can experience significant latency.
Swap therefore involves a trade-off between memory availability and performance.
Consider a Kubernetes node with 16 GiB of RAM and 4 GiB of configured swap. The node has 16 GiB of physical memory, but the operating system can also use eligible swap space under appropriate conditions.
This does not mean that Kubernetes should schedule workloads as if the node had 20 GiB of equivalent RAM. RAM and swap have different performance characteristics, and Kubernetes scheduling decisions are still based primarily on the node's advertised memory capacity and workload resource requests.
Why Kubernetes Has Traditionally Restricted Swap
Kubernetes needs predictable resource accounting to schedule workloads and enforce resource limits. Uncontrolled swap usage can make memory behavior harder to reason about.
For example, a container may appear to remain alive during memory pressure because some of its pages have been moved to swap. The application might then respond much more slowly than expected.
This can affect:
- API response times.
- Database latency.
- Background job completion.
- Node stability under memory pressure.
- Performance isolation between workloads.
Historically, the kubelet's default behavior on Linux required swap to be disabled. Modern Kubernetes versions provide configuration options for supporting swap, but enabling it requires deliberate configuration.
The goal is not to make swap universally available to every workload. It is to let administrators choose whether and how swap can be used while preserving resource isolation as far as the platform supports it.
Understand Kubernetes Swap Configuration
The kubelet uses the failSwapOn setting to determine whether it should fail to start when swap is detected.
When swap is enabled at the operating-system level but failSwapOn remains true, the kubelet normally refuses to start.
For supported Kubernetes versions, setting failSwapOn to false allows the kubelet to start with swap enabled. This setting alone does not mean that containers can freely use swap.
The memorySwap configuration controls the kubelet's swap behavior through a policy.
A simplified kubelet configuration looks like this:
failSwapOn: false
memorySwap:
swapBehavior: LimitedSwap
This configuration illustrates a policy that allows supported workloads to use a limited amount of swap. The exact available values and behavior depend on the Kubernetes version and platform.
The commonly documented policies are:
| Setting | Behavior |
|---|
NoSwap | Containers are not permitted to use swap under the configured policy. |
LimitedSwap | Eligible workloads can use a limited amount of swap, subject to Kubernetes and cgroup configuration. |
With NoSwap, enabling swap at the host level does not mean that container workloads are allowed to use it. The node operating system may still use swap for eligible host processes, depending on the system configuration.
With LimitedSwap, container swap behavior depends on the supported cgroup version and resource configuration. Check the official kubelet configuration reference for the Kubernetes release you operate before applying these settings.
Prepare the Linux Node
Before changing Kubernetes configuration, verify that the operating system supports swap and that the node has a suitable swap device or file.
Inspect the current memory and swap state:
free -h
swapon --show
cat /proc/swaps
The output shows physical memory usage and configured swap devices.
If swap is not configured, a Linux administrator can create and activate a swap file where the filesystem and security requirements permit it.
For example, the following commands illustrate creating a 4 GiB swap file on a Linux system that supports this method:
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
These commands require appropriate privileges and should not be copied blindly into a production node configuration. Some filesystems do not support swap files created with fallocate, and additional filesystem-specific steps may be necessary.
For persistence across reboots, configure the swap device or file through the operating system's standard mechanism, such as an appropriate /etc/fstab entry or system-specific configuration.
Before proceeding, verify that the swap file has the correct permissions and that the node's storage policy permits its use.
Configure the Kubelet
The kubelet configuration must match the intended swap policy and the capabilities of the node.
A typical configuration fragment is:
failSwapOn: false
memorySwap:
swapBehavior: LimitedSwap
If the kubelet uses a configuration file, locate the file referenced by its service configuration or command-line arguments.
Do not replace the entire kubelet configuration with this fragment. Merge the relevant settings into the existing configuration so that cluster-specific settings remain intact.
After updating the configuration, restart the kubelet using the operating system's service manager when required by the deployment method.
For example:
sudo systemctl restart kubelet
sudo systemctl status kubelet
The exact service name and restart procedure depend on how Kubernetes was installed and managed. Managed Kubernetes services may not permit direct kubelet configuration changes.
After the restart, inspect kubelet logs and node status to confirm that the node is healthy.
kubectl get nodes
kubectl describe node <node-name>
Replace <node-name> with the actual node name. Confirm that the node becomes Ready and that no configuration errors appear in the kubelet logs.
Understand Swap Behavior Under cgroup v2
Linux cgroup v2 provides memory-related controls that can be used to manage swap for a cgroup.
Relevant interfaces include:
memory.current: Reports memory currently charged to the cgroup.memory.max: Defines the cgroup's hard memory limit.memory.swap.current: Reports swap usage charged to the cgroup.memory.swap.max: Defines the maximum swap usage permitted for the cgroup.
The files are available only when the relevant cgroup v2 controller and hierarchy support them.
For example, inspect the relevant cgroup directory:
cat /sys/fs/cgroup/memory.current
cat /sys/fs/cgroup/memory.max
cat /sys/fs/cgroup/memory.swap.current
cat /sys/fs/cgroup/memory.swap.max
These commands use the root cgroup as an example. Container and Pod settings are normally represented in their own cgroup directories, so inspect the correct path before drawing conclusions about a particular workload.
A numeric value in memory.swap.max represents the maximum swap usage in bytes, while max indicates no finite limit at that cgroup level.
Kubernetes and the container runtime configure these controls according to the supported swap policy. Avoid manually editing cgroup files for running Pods because those changes may conflict with the kubelet's resource management.
Monitor Swap Usage and Application Performance
Enabling swap without monitoring its effects can make resource problems harder to diagnose.
Start with operating-system metrics:
free -h
vmstat 1
free -h provides a summary of memory and swap usage. vmstat 1 reports system activity at one-second intervals, including swap-in and swap-out activity on Linux systems.
In vmstat, the si and so columns represent swap-in and swap-out activity. Sustained activity under load may indicate memory pressure, although the values must be interpreted alongside the workload and other system metrics.
For Kubernetes workloads, monitor:
- Container memory usage and configured limits.
- Pod restarts and out-of-memory termination reasons.
- Node memory pressure conditions.
- Application latency and throughput.
- Swap usage and swap-in or swap-out activity.
- Disk I/O and storage latency.
A container that uses swap may remain operational but respond slowly. Conversely, swap activity alone does not prove that a workload is unhealthy. Look for a relationship between swap activity and user-visible performance.
Common Problems When Enabling Swap
The kubelet refuses to start
The operating system may have active swap while the kubelet is still configured to fail when swap is detected.
Check the kubelet configuration and confirm that the Kubernetes release supports the selected swap policy.
The container cannot use swap
Setting failSwapOn to false does not guarantee that every container can use swap. Verify memorySwap.swapBehavior, the node's cgroup version, and the supported container runtime behavior.
Application latency increases
Swap can reduce immediate memory pressure while increasing access latency. If the application repeatedly accesses swapped-out pages, it may become slower.
Investigate whether the workload needs more RAM, a lower memory footprint, or different resource limits.
The node still experiences memory pressure
Swap does not remove the need for sufficient physical memory. Kubernetes still schedules workloads based on its normal resource model, and host services continue to consume memory.
If the node consistently approaches its memory capacity, adjust workload placement, resource requests, application memory consumption, or node capacity rather than relying entirely on swap.
Best Practices for Production Clusters
- Check version compatibility. Confirm the Kubernetes release, kubelet settings, operating system, and container runtime support the intended policy.
- Use swap deliberately. Define which workloads can use swap and why.
- Preserve memory requests and limits. Swap is not a replacement for accurate resource configuration.
- Monitor latency as well as memory. A workload that remains alive may still be too slow to meet its service-level objectives.
- Test under realistic memory pressure. Measure the effects before enabling the policy across an entire cluster.
- Keep node configurations consistent. Document swap configuration and validate it across node pools.
- Avoid manual cgroup manipulation. Let Kubernetes and the container runtime manage the resource controls.
- Maintain sufficient RAM. Treat swap as a supplementary mechanism, not a substitute for appropriate capacity planning.
Advantages and Disadvantages
| Advantages | Disadvantages |
|---|
| Can provide additional memory flexibility under pressure. | Disk-backed memory is slower than RAM. |
| May help eligible workloads avoid immediate memory-related failure. | Excessive swapping can increase application latency. |
| Provides configurable behavior on supported Kubernetes nodes. | Requires compatible kubelet, runtime, and operating-system configuration. |
| Can support selected workloads with different memory characteristics. | Makes resource behavior and troubleshooting more complex. |
| Can improve resilience in specific memory-pressure scenarios. | Does not replace proper capacity planning or memory limits. |
Summary
Kubernetes can support node swap when the Kubernetes release, kubelet, operating system, and container runtime are configured appropriately. The failSwapOn setting controls whether the kubelet starts when swap is detected, while memorySwap.swapBehavior defines the intended container swap policy on supported systems.
Before enabling swap, verify the node configuration, understand the cgroup controls, and establish monitoring for swap usage, memory pressure, and application latency.
The right policy depends on the workload. Swap may provide additional flexibility for selected applications, but it should not be used to compensate for insufficient RAM, inaccurate resource requests, or an application with excessive memory consumption. Test the behavior under realistic load and expand the configuration only when the results support doing so.
Join the conversation! Your thoughts help the community grow.