Graduate swap to Beta 1

Signed-off-by: Harshal Patil <harpatil@redhat.com>

Author: harche

keps/sig-node/2400-node-swap/README.md

@@ -8,6 +8,9 @@
   - [Goals](#goals)
   - [Non-Goals](#non-goals)
 - [Proposal](#proposal)
+  - [Enable Swap Support only for Burstable QoS Pods](#enable-swap-support-only-for-burstable-qos-pods)
+    - [Example 1 - Configured swap memory on the host is equal to the physical memory](#example-1---configured-swap-memory-on-the-host-is-equal-to-the-physical-memory)
+    - [Example 2 - Configured swap memory on the host is NOT equal to the physical memory](#example-2---configured-swap-memory-on-the-host-is-not-equal-to-the-physical-memory)
   - [User Stories](#user-stories)
     - [Improved Node Stability](#improved-node-stability)
     - [Long-running applications that swap out startup memory](#long-running-applications-that-swap-out-startup-memory)
@@ -30,7 +33,8 @@
   - [Graduation Criteria](#graduation-criteria)
     - [Alpha](#alpha)
     - [Alpha2](#alpha2)
-    - [Beta](#beta)
+    - [Beta 1](#beta-1)
+    - [Beta 2](#beta-2)
     - [GA](#ga)
   - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
   - [Version Skew Strategy](#version-skew-strategy)
@@ -166,6 +170,71 @@ administrators can configure the kubelet such that:
 
 This proposal enables scenarios 1 and 2 above, but not 3.
 
+### Enable Swap Support only for Burstable QoS Pods
+Before enabling swap support through the pod API, it is crucial to build confidence in this feature by carefully assessing its impact on workloads and Kubernetes. As an initial step, we propose enabling swap support for Burstable QoS Pods by automatically calculating the appropriate swap values, rather than allowing users to input these values manually. By doing so, we can ensure a thorough understanding of the feature's performance and stability before considering the manual input of swap values in a subsequent beta release. This cautious approach will ensure the efficient allocation of resources and the smooth integration of swap support into Kubernetes.
+
+Allocate the swap limit equal to the requested memory for each container and adjust the proportion of swap based on the total swap memory available, we can follow these steps:
+
+1. **Calculate the total memory requests of the pod:**
+   - Sum up the memory requests of all containers in the pod. Let's call this value `TotalMemory`.
+
+2. **Determine the swap proportion for each container:**
+   - For each container, divide its memory request by the `TotalMemory`. The result will be the proportion of requested memory for that container within the pod. Let's call this value `RequestedMemoryProportion`.
+
+3. **Calculate the total swap memory available:**
+   - Determine the total swap memory available in the system. If the total swap memory is equal to the total physical memory, you can skip this step. Otherwise, calculate the proportion of available swap memory compared to the total physical memory. Let's call this value `SwapMemoryProportion`.
+
+4. **Calculate the swap limit for each container:**
+   - Multiply the `RequestedMemoryProportion` of a container by its memory request and then multiply the result by the `SwapMemoryProportion`. The result will be the adjusted swap limit for that specific container within the pod.
+
+#### Example 1 - Configured swap memory on the host is equal to the physical memory
+Suppose we have a Burstable QoS pod with two containers:
+
+- Container A: Memory request 2 GB
+- Container B: Memory request 1 GB
+
+Let's assume the total physical memory is 4 GB and the total swap memory available is also 4 GB.
+
+Step 1: Calculate the total memory requests of the pod: 2 GB + 1 GB = 3 GB
+
+Step 2: Determine the requested memory proportion for each container:
+- Container A: (2 GB) / (3 GB) = 2/3
+- Container B: (1 GB) / (3 GB) = 1/3
+
+Step 3: Calculate the total swap memory available: Since the total swap memory (4 GB) is equal to the total physical memory (4 GB), the `SwapMemoryProportion` will be 1.
+
+Step 4: Calculate the swap limit for each container:
+- Container A: (2/3) * 2 GB * 1 = 4/3 GB ≈ 1.33 GB
+- Container B: (1/3) * 1 GB * 1 = 1/3 GB ≈ 0.33 GB
+
+In this example, Container A would have a swap limit of 1.33 GB, and Container B would have a swap limit of 0.33 GB.
+
+This approach allocates swap limits based on each container's memory request and adjusts the proportion based on the total swap memory available in the system. It ensures that each container gets a fair share of the swap space and helps maintain resource allocation efficiency.
+
+#### Example 2 - Configured swap memory on the host is NOT equal to the physical memory
+
+If the total physical memory is 4 GB and the total swap memory available is 2 GB, we can adjust the example 1 using the same approach:
+
+Suppose we have a Burstable QoS pod with two containers:
+
+- Container A: Memory request 2 GB
+- Container B: Memory request 1 GB
+
+Step 1: Calculate the total memory requests of the pod: 2 GB + 1 GB = 3 GB
+
+Step 2: Determine the requested memory proportion for each container:
+- Container A: (2 GB) / (3 GB) = 2/3
+- Container B: (1 GB) / (3 GB) = 1/3
+
+Step 3: Calculate the total swap memory available: Since the total swap memory (2 GB) is not equal to the total physical memory (4 GB), the `SwapMemoryProportion` will be 2 GB / 4 GB = 1/2.
+
+Step 4: Calculate the swap limit for each container:
+- Container A: (2/3) * 2 GB * (1/2) = 4/6 GB ≈ 0.67 GB
+- Container B: (1/3) * 1 GB * (1/2) = 1/6 GB ≈ 0.17 GB
+
+In this example, with 2 GB of total swap memory available, Container A would have a swap limit of 0.67 GB, and Container B would have a swap limit of 0.17 GB.
+
+
 ### User Stories
 
 #### Improved Node Stability
@@ -300,6 +369,8 @@ and/or workloads in a number of different scenarios.
 Since swap provisioning is out of scope of this proposal, this enhancement
 poses low risk to Kubernetes clusters that will not enable swap.
 
+Enabling swap on a system without encryption poses a security risk, as critical information, such as Kubernetes secrets, may be swapped out to the disk. If an unauthorized individual gains access to the disk, they could potentially obtain these secrets. To mitigate this risk, it is recommended to use encrypted swap. However, handling encrypted swap is not within the scope of kubelet; rather, it is a general Linux configuration concern and should be addressed at that level. Nevertheless, it is essential to provide documentation that warns users of this potential issue, ensuring they are aware of the potential security implications and can take appropriate steps to safeguard their system.
+
 ## Design Details
 
 We summarize the implementation plan as following:
@@ -494,7 +565,7 @@ For alpha2 [Current stage]:
   for configuring eviction.
 - Verify new system-reserved settings for swap memory.
 
-For beta [Future]:
+For beta 1 [Future]:
 
 - Add e2e tests that verify pod-level control of swap utilization.
 - Add e2e tests that verify swap performance with pods using a tmpfs.
@@ -536,20 +607,24 @@ Here are specific improvements to be made:
   swap limit for workloads.
 - Investigate eviction behavior with swap enabled.
 
-
-#### Beta
-
-- Add support for controlling swap consumption at the pod level [via cgroups].
-- Handle usage of swap during container restart boundaries for writes to tmpfs
-  (which may require pod cgroup change beyond what container runtime will do at
-  container cgroup boundary).
+#### Beta 1
+- Enable Swap Support using Burstable QoS Pods only. 
 - Add swap memory to the Kubelet stats api.
 - Determine a set of metrics for node QoS in order to evaluate the performance
   of nodes with and without swap enabled.
 - Better understand relationship of swap with memory QoS in cgroup v2
   (particularly `memory.high` usage).
-- Collect feedback from test user cases.
+- Make sure node e2e jobs that use swap are healthy
+- Publish a Kubernetes doc page encouring user to use encrypted swap if they wish to enable this feature.
 - Improve coverage for appropriate scenarios in testgrid.
+- Collect feedback from test user cases.
+- Handle usage of swap during container restart boundaries for writes to tmpfs
+  (which may require pod cgroup change beyond what container runtime will do at
+  container cgroup boundary).
+
+#### Beta 2
+- Add support for controlling swap consumption at the container level [via cgroups] in Pod API in [container resources](https://github.com/kubernetes/kubernetes/blob/94a15929cf13354fdf3747cb266d511154f8c97b/staging/src/k8s.io/api/core/v1/types.go#L2443). More specifically add a new [ResourceName](https://github.com/kubernetes/kubernetes/blob/94a15929cf13354fdf3747cb266d511154f8c97b/staging/src/k8s.io/api/core/v1/types.go#L5522) `swap`. This will make sure we stay consistent with other resources like `cpu`, `memory` etc.
+
 
 [via cgroups]: #restrict-swap-usage-at-the-cgroup-level