Merge pull request #41755 from ehashman/swap-docs

Add documentation for NodeSwap tech preview feature

Author: mburke5678

modules/nodes-nodes-swap-memory.adoc

@@ -0,0 +1,63 @@
+:_content-type: PROCEDURE
+[id="nodes-nodes-swap-memory_{context}"]
+
+= Managing swap memory on nodes
+
+:FeatureName: Configuring swap memory usage on nodes
+include::snippets/technology-preview.adoc[]
+
+In {product-title}, you can configure nodes to use swap memory. By default, the Kubelet will not start in the presence of swap memory without further configuration.
+
+[WARNING]
+====
+Enabling swap memory can negatively impact workload performance and out-of-resource handling. Do not enable swap memory on master nodes.
+====
+
+.Prerequisites
+* You have a running {product-title} cluster that uses version 4.10 or later.
+* You are logged in to the cluster as a user with administrative privileges.
+* Tech Preview features are enabled on the cluster.
+* On cgroups v2, nodes must have swap accounting enabled (kernel argument `swapaccount=1`).
+
+.Procedure
+
+. Apply a custom kubelet label to the machine config pool where swap is enabled.
++
+[source,terminal]
+----
+$ oc label machineconfigpool worker kubelet-swap=enabled
+----
+
+. Create a custom KubeletConfig to enable swap settings.
++
+[source,yaml]
+----
+apiVersion: machineconfiguration.openshift.io/v1
+kind: KubeletConfig
+metadata:
+  name: swap-config
+spec:
+  machineConfigPoolSelector:
+    matchLabels:
+      kubelet-swap: enabled
+  kubeletConfig:
+    failSwapOn: false <1>
+    memorySwap:
+      swapBehavior: LimitedSwap <2>
+----
+<1> Ensures Kubelet will start in the presence of swap on a system.
+<2> Specifies swap behavior for the kubelet. If unspecified, defaults to `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.
+  The behaviour of the `LimitedSwap` setting depends if the node is running
+  with v1 or v2 of control groups (also known as "cgroups"):
+** **cgroups v1:** Kubernetes workloads can use any combination of memory and
+  swap, up to the pod's memory limit, if set.
+** **cgroups v2:** Kubernetes workloads cannot use swap memory.
+* `UnlimitedSwap`: Kubernetes workloads can use as much swap memory as they
+  request, up to the system limit.
+
+. Enable swap memory on the machines. Kubelets will not start in the presence of swap memory without the above configuration, so if swap memory is enabled on an already running cluster, the custom Kubelet configurations must be provided first. If there is no swap memory present on a system, this configuration will not change any default behaviours.

nodes/nodes/nodes-nodes-working.adoc

@@ -39,3 +39,4 @@ ifdef::openshift-webscale[]
 include::modules/nodes-nodes-rtkernel-arguments.adoc[leveloffset=+1]
 endif::openshift-webscale[]
 include::modules/nodes-nodes-cgroups-2.adoc[leveloffset=+1]
+include::modules/nodes-nodes-swap-memory.adoc[leveloffset=+1]