Merge pull request #42225 from mburke5678/swap-docs-follow-up

Follow-up Add documentation for NodeSwap tech preview feature

Author: mburke5678

modules/nodes-nodes-swap-memory.adoc

@@ -1,34 +1,53 @@
 :_content-type: PROCEDURE
 [id="nodes-nodes-swap-memory_{context}"]
 
-= Managing swap memory on nodes
+= Enabling swap memory use on nodes
 
-:FeatureName: Configuring swap memory usage on nodes
+:FeatureName: Enabling swap memory use 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.
+You can enable swap memory use for {product-title} workloads on a per-node basis. 
 
 [WARNING]
 ====
 Enabling swap memory can negatively impact workload performance and out-of-resource handling. Do not enable swap memory on master nodes.
 ====
 
+To enable swap memory, create a `kubeletconfig` custom resource (CR) to set the `swapbehavior` parameter. You can set limited or unlimited swap memory:
+
+* Limited: Use the `LimitedSwap` value to limit how much swap memory workloads can use. Any workloads on the node that are not managed by {product-title} can still use swap memory. The `LimitedSwap` behavior depends on whether the node is running with Linux control groups link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/index.html[version 1 (cgroups v1)] or link:https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html[version 2 (cgroups v2)]:
+** cgroups v1: {product-title} workloads can use any combination of memory and swap, up to the pod's memory limit, if set.
+** cgroups v2: {product-title} workloads cannot use swap memory.
+
+* Unlimited: Use the `UnlimitedSwap` value to allow workloads to use as much swap memory as they request, up to the system limit.
+
+Because the kubelet will not start in the presence of swap memory without this configuration, you must enable swap memory in {product-title} before enabling swap memory on the nodes. If there is no swap memory present on a node, enabling swap memory in {product-title} has no effect.
+
 .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`).
+
+* You have enabled the `TechPreviewNoUpgrade` feature set on the cluster (see _Nodes -> Enabling features using feature gates_).
++
+[NOTE]
+====
+Enabling the `TechPreviewNoUpgrade` feature set cannot be undone and prevents upgrades. These feature sets are not recommended on production clusters.
+====
+
+* If cgroups v2 is enabled on a node, you must enable swap accounting on the node, by setting the `swapaccount=1` kernel argument.
 
 .Procedure
 
-. Apply a custom kubelet label to the machine config pool where swap is enabled.
+. Apply a custom label to the machine config pool where you want to allow swap memory.
 +
 [source,terminal]
 ----
 $ oc label machineconfigpool worker kubelet-swap=enabled
 ----
 
-. Create a custom KubeletConfig to enable swap settings.
+. Create a custom resource (CR) to enable and configure swap settings.
 +
 [source,yaml]
 ----
@@ -45,19 +64,8 @@ spec:
     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.
+<1> Set to `false` to enable swap memory use on the associated nodes. Set to `true` to disable swap memory use. 
+<2> Specify the swap memory behavior. If unspecified, the default is `LimitedSwap`.
+
+. Enable swap memory on the machines. 
+