diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md index f8c0092d7b5e8..7c339c57b4c83 100644 --- a/content/en/docs/concepts/architecture/nodes.md +++ b/content/en/docs/concepts/architecture/nodes.md @@ -392,6 +392,49 @@ Failed pod objects will be preserved until explicitly deleted or [cleaned up by This is a change of behavior compared to abrupt node termination. {{< /note >}} +## Swap memory management {#swap-memory} + +{{< feature-state state="alpha" for_k8s_version="v1.22" >}} + +Prior to Kubernetes 1.22, nodes did not support the use of swap memory, and a +kubelet would by default fail to start if swap was detected on a node. In 1.22 +onwards, swap memory support can be enabled on a per-node basis. + +To enable swap on a node, the `NodeSwap` feature gate must be enabled on +the kubelet, and the `--fail-swap-on` command line flag or `failSwapOn` +[configuration setting](/docs/reference/config-api/kubelet-config.v1beta1/#kubelet-config-k8s-io-v1beta1-KubeletConfiguration) +must be set to false. + +A user can also optionally configure `memorySwap.swapBehavior` in order to +specify how a node will use swap memory. For example, + +```yaml +memorySwap: + swapBehavior: LimitedSwap +``` + +The available configuration options for `swapBehavior` are: + +- `LimitedSwap`: Kubernetes workloads are limited in how much swap they can + use. Workloads on the node not managed by Kubernetes can still swap. +- `UnlimitedSwap`: Kubernetes workloads can use as much swap memory as they + request, up to the system limit. + +If configuration for `memorySwap` is not specified and the feature gate is +enabled, by default the kubelet will apply the same behaviour as the +`LimitedSwap` setting. + +The behaviour of the `LimitedSwap` setting depends if the node is running with +v1 or v2 of control groups (also known as "cgroups"): + +- **cgroupsv1:** Kubernetes workloads can use any combination of memory and + swap, up to the pod's memory limit, if set. +- **cgroupsv2:** Kubernetes workloads cannot use swap memory. + +For more information, and to assist with testing and provide feedback, please +see [KEP-2400](https://github.com/kubernetes/enhancements/issues/2400) and its +[design proposal](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/2400-node-swap/README.md). + ## {{% heading "whatsnext" %}} * Learn about the [components](/docs/concepts/overview/components/#node-components) that make up a node. diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index 13d6e0f596e3a..e5cfe0699efec 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -146,6 +146,7 @@ different Kubernetes components. | `MixedProtocolLBService` | `false` | Alpha | 1.20 | | | `NetworkPolicyEndPort` | `false` | Alpha | 1.21 | 1.21 | | `NetworkPolicyEndPort` | `true` | Beta | 1.22 | | +| `NodeSwap` | `false` | Alpha | 1.22 | | | `NonPreemptingPriority` | `false` | Alpha | 1.15 | 1.18 | | `NonPreemptingPriority` | `true` | Beta | 1.19 | | | `PodDeletionCost` | `false` | Alpha | 1.21 | 1.21 | @@ -783,6 +784,9 @@ Each feature gate is designed for enabling/disabling a specific feature: - `NodeDisruptionExclusion`: Enable use of the Node label `node.kubernetes.io/exclude-disruption` which prevents nodes from being evacuated during zone failures. - `NodeLease`: Enable the new Lease API to report node heartbeats, which could be used as a node health signal. +- `NodeSwap`: Enable the kubelet to allocate swap memory for Kubernetes workloads on a node. + Must be used with `KubeletConfiguration.failSwapOn` set to false. + For more details, please see [swap memory](/docs/concepts/architecture/nodes/#swap-memory) - `NonPreemptingPriority`: Enable `preemptionPolicy` field for PriorityClass and Pod. - `PVCProtection`: Enable the prevention of a PersistentVolumeClaim (PVC) from being deleted when it is still used by any Pod.