Merge pull request #73550 from ShaunaDiaz/OCPBUGS-31055

OCPBUGS#31055: fix table, optimize module ephemeral storage mgmt

Author: ShaunaDiaz

microshift_storage/microshift-storage-migration.adoc

@@ -2,7 +2,7 @@
 [id="microshift-storage-migration"]
 = Storage migration using the Kube Storage Version Migrator
 include::_attributes/attributes-microshift.adoc[]
-:context: microshift-storage-plugin-overview
+:context: microshift-storage-migration
 
 toc::[]
 

modules/storage-ephemeral-storage-manage.adoc

@@ -1,8 +1,8 @@
 // Module included in the following assemblies:
 //
-// storage/understanding-persistent-storage.adoc[leveloffset=+1]
+//* storage/understanding-persistent-storage.adoc
+//* storage/understanding-ephemeral-storage.adoc
 //* microshift_storage/understanding-ephemeral-storage-microshift.adoc
-// storage/understanding-ephemeral-storage.adoc
 
 [id=storage-ephemeral-storage-manage_{context}]
 = Ephemeral storage management
@@ -14,10 +14,28 @@ You can manage local ephemeral storage by specifying requests and limits. Each c
 * `spec.containers[].resources.limits.ephemeral-storage`
 * `spec.containers[].resources.requests.ephemeral-storage`
 
-Limits and requests for ephemeral storage are measured in byte quantities. You can express storage as a plain integer or as a fixed-point number using one of these suffixes: E, P, T, G, M, k. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. For example, the following quantities all represent approximately the same value: 128974848, 129e6, 129M, and 123Mi. The case of the suffixes is significant. If you specify 400m of ephemeral storage, this requests 0.4 bytes, rather than 400 mebibytes (400Mi) or 400 megabytes (400M), which was probably what was intended.
+[id=storage-ephemeral-storage-limits-requests-units_{context}]
+== Ephemeral storage limits and requests units
+Limits and requests for ephemeral storage are measured in byte quantities. You can express storage as a plain integer or as a fixed-point number using one of these suffixes: E, P, T, G, M, k. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.
 
-The following example shows a pod with two containers. Each container requests 2GiB of local ephemeral storage. Each container has a limit of 4GiB of local ephemeral storage. Therefore, the pod has a request of 4GiB of local ephemeral storage, and a limit of 8GiB of local ephemeral storage.
+For example, the following quantities all represent approximately the same value: 128974848, 129e6, 129M, and 123Mi.
 
+[IMPORTANT]
+====
+The suffixes for each byte quantity are case-sensitive. Be sure to use the correct case. Use the case-sensitive "M", such as used in "400M" to set the request at 400 megabytes. Use the case-sensitive "400Mi" to request 400 mebibytes. If you specify "400m" of ephemeral storage, the storage requests is only 0.4 bytes.
+====
+
+[id=storage-ephemeral-storage-requests-limits_{context}]
+== Ephemeral storage requests and limits example
+The following example configuration file shows a pod with two containers:
+
+* Each container requests 2GiB of local ephemeral storage.
+* Each container has a limit of 4GiB of local ephemeral storage.
+* At the pod level, kubelet works out an overall pod storage limit by adding up the limits of all the containers in that pod.
+** In this case, the total storage usage at the pod level is the sum of the disk usage from all containers plus the pod's `emptyDir` volumes.
+** Therefore, the pod has a request of 4GiB of local ephemeral storage, and a limit of 8GiB of local ephemeral storage.
+
+.Example ephemeral storage configuration with quotas and limits
 [source, yaml]
 ----
 apiVersion: v1
@@ -40,17 +58,36 @@ spec:
     image: images.my-company.example/log-aggregator:v6
     resources:
       requests:
-        ephemeral-storage: "2Gi" <1>
+        ephemeral-storage: "2Gi"
+      limits:
+        ephemeral-storage: "4Gi"
     volumeMounts:
     - name: ephemeral
       mountPath: "/tmp"
   volumes:
     - name: ephemeral
       emptyDir: {}
 ----
-<1> Request for local ephemeral storage.
-<2> Limit for local ephemeral storage.
+<1> Container request for local ephemeral storage.
+<2> Container limit for local ephemeral storage.
+
+ifndef::microshift[]
+[id=storage-ephemeral-storage-scheduling-eviction_{context}]
+== Ephemeral storage configuration effects pod scheduling and eviction
+The settings in the pod spec affect both how the scheduler makes a decision about scheduling pods and when kubelet evicts pods.
+
+* First, the scheduler ensures that the sum of the resource requests of the scheduled containers is less than the capacity of the node. In this case, the pod can be assigned to a node only if the node's available ephemeral storage (allocatable resource) is more than 4GiB.
+
+* Second, at the container level, because the first container sets a resource limit, kubelet eviction manager measures the disk usage of this container and evicts the pod if the storage usage of the container exceeds its limit (4GiB). The kubelet eviction manager also marks the pod for eviction if the total usage exceeds the overall pod storage limit (8GiB).
+endif::microshift[]
 
-This setting in the pod spec affects how the scheduler makes a decision on scheduling pods, and also how kubelet evict pods. First of all, the scheduler ensures that the sum of the resource requests of the scheduled containers is less than the capacity of the node. In this case, the pod can be assigned to a node only if its available ephemeral storage (allocatable resource) is more than 4GiB.
+ifdef::microshift[]
+[id=storage-ephemeral-storage-eviction_{context}]
+== Ephemeral storage configuration effects pod eviction
+The settings in the pod spec affect when kubelet evicts pods. At the container level, because the first container sets a resource limit, kubelet eviction manager measures the disk usage of this container and evicts the pod if the storage usage of the container exceeds its limit (4GiB). The kubelet eviction manager also marks the pod for eviction if the total usage exceeds the overall pod storage limit (8GiB).
 
-Secondly, at the container level, since the first container sets resource limit, kubelet eviction manager measures the disk usage of this container and evicts the pod if the storage usage of this container exceeds its limit (4GiB). At the pod level, kubelet works out an overall pod storage limit by adding up the limits of all the containers in that pod. In this case, the total storage usage at the pod level is the sum of the disk usage from all containers plus the pod's `emptyDir` volumes. If this total usage exceeds the overall pod storage limit (4GiB), then the kubelet also marks the pod for eviction.
+[NOTE]
+====
+This policy is strictly for `emptyDir` volumes and is not applied to persistent storage. You can specify the `priorityClass` of pods to exempt the pod from eviction.
+====
+endif::microshift[]