BZ1769845 - Add storage mgmnt table and ephemeral storage docs

_topic_map.yml

@@ -703,6 +703,9 @@ Name: Storage
 Dir: storage
 Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated,openshift-online
 Topics:
+- Name: Understanding ephemeral storage
+  File: understanding-ephemeral-storage
+  Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated,openshift-online
 - Name: Understanding persistent storage
   File: understanding-persistent-storage
   Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated,openshift-online

modules/data-storage-management.adoc

@@ -0,0 +1,41 @@
+// Module included in the following assemblies:
+//
+// * storage/optimizing-storage.adoc
+
+[id="data-storage-management_{context}"]
+= Data storage management
+
+The following table summarizes the main directories that {product-title} components write data to.
+
+.Main directories for storing {product-title} data
+[options="header,footer"]
+|===
+|Directory|Notes|Sizing|Expected growth
+
+|*_/var/lib/etcd_*
+|Used for etcd storage when storing the database.
+|Less than 20 GB.
+
+Database can grow up to 8 GB.
+|Will grow slowly with the environment. Only storing metadata.
+
+Additional 20-25 GB for every additional 8 GB of memory.
+
+|*_/var/lib/containers_*
+|This is the mount point for the CRI-O runtime. Storage used for active container runtimes, including pods, and storage of local images. Not used for registry storage.
+|50 GB for a node with 16 GB memory. Note that this sizing should not be used to determine minimum cluster requirements.
+
+Additional 20-25 GB for every additional 8 GB of memory.
+|Growth is limited by capacity for running containers.
+
+|*_/var/lib/kubelet_*
+|Ephemeral volume storage for pods. This includes anything external that is mounted into a container at runtime. Includes environment variables, kube secrets, and data volumes not backed by persistent volumes.
+|Varies
+|Minimal if pods requiring storage are using persistent volumes. If using ephemeral storage, this can grow quickly.
+
+|*_/var/log_*
+|Log files for all components.
+|10 to 30 GB.
+|Log files can grow quickly; size can be managed by growing disks or by using log rotate.
+
+|===

modules/feature-gate-features.adoc

@@ -32,6 +32,3 @@ The following features are affected by FeatureGates:
 
 You can enable these features by editing the Feature Gate Custom Resource.
 Turning on these features cannot be undone and prevents the ability to upgrade your cluster.
-
-The `LocalStorageCapacityIsolation` cannot be enabled.
-

modules/storage-ephemeral-storage-manage.adoc

@@ -0,0 +1,8 @@
+// Module included in the following assemblies:
+//
+// storage/understanding-persistent-storage.adoc[leveloffset=+1]
+
+[id=storage-ephemeral-storage-manage_{context}]
+= Ephemeral storage management
+
+Cluster administrators can manage ephemeral storage within a project by setting quotas that define the limit ranges and number of requests for ephemeral storage across all pods in a non-terminal state. Developers can also set requests and limits on this compute resource at the pod and container level.

modules/storage-ephemeral-storage-monitoring.adoc

@@ -0,0 +1,24 @@
+// Module included in the following assemblies:
+//
+// storage/understanding-persistent-storage.adoc[leveloffset=+1]
+
+[id=storage-ephemeral-storage-monitoring_{context}]
+= Monitoring ephemeral storage
+
+You can use `/bin/df` as a tool to monitor ephemeral storage usage on the volume where ephemeral container data is located, which is `/var/lib/kubelet` and `/var/lib/containers`. The available space for only `/var/lib/kubelet` is shown when you use the `df` command if `/var/lib/containers` is placed on a separate disk by the cluster administrator.
+
+To show the human-readable values of used and available space in `/var/lib`, enter the following command:
+
+[source,terminal]
+----
+$ df -h /var/lib
+----
+
+The output shows the ephemeral storage usage in `/var/lib`:
+
+.Example output
+[source,terminal]
+----
+Filesystem  Size  Used Avail Use% Mounted on
+/dev/sda1    69G   32G   34G  49% /
+----

modules/storage-ephemeral-storage-overview.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// storage/understanding-persistent-storage.adoc[leveloffset=+1]
+
+[id=storage-ephemeral-storage-overview_{context}]
+= Overview
+
+In addition to persistent storage, pods and containers can require
+ephemeral or transient local storage for their operation. The lifetime
+of this ephemeral storage does not extend beyond the life of the
+individual pod, and this ephemeral storage cannot be shared across
+pods.
+
+Pods use ephemeral local storage for scratch space, caching, and logs. Issues related to
+the lack of local storage accounting and isolation include the following:
+
+* Pods do not know how much local storage is available to them.
+* Pods cannot request guaranteed local storage.
+* Local storage is a best effort resource.
+* Pods can be evicted due to other pods filling the local storage,
+after which new pods are not admitted until sufficient storage
+has been reclaimed.
+
+Unlike persistent volumes, ephemeral storage is unstructured and
+the space is shared between all pods running on a
+node, in addition to other uses by the system, the container runtime,
+and {product-title}. The ephemeral storage framework allows pods to
+specify their transient local storage needs. It also allows {product-title} to
+schedule pods where appropriate, and to protect the node against excessive
+use of local storage.
+
+While the ephemeral storage framework allows administrators and
+developers to better manage this local storage, it does not provide
+any promises related to I/O throughput and latency.

modules/storage-ephemeral-storage-types.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// storage/understanding-persistent-storage.adoc[leveloffset=+1]
+
+[id=storage-ephemeral-storage-types{context}]
+= Types of ephemeral storage
+
+Ephemeral local storage is always made available in the primary
+partition. There are two basic ways of creating the primary
+partition: root and runtime.
+
+[discrete]
+== Root
+
+This partition holds the kubelet root directory, `/var/lib/kubelet/` by
+default, and `/var/log/` directory. This partition can be shared between user
+pods, the OS, and Kubernetes system daemons. This partition can be consumed by pods
+through `EmptyDir` volumes, container logs, image layers, and container-writable
+layers. Kubelet manages shared access and isolation of this partition. This
+partition is ephemeral, and applications cannot expect any performance SLAs,
+such as disk IOPS, from this partition.
+
+[discrete]
+== Runtime
+
+This is an optional partition that runtimes can use for overlay
+file systems. {product-title} attempts to identify and provide
+shared access along with isolation to this partition. Container image
+layers and writable layers are stored here. If the runtime partition
+exists, the `root` partition does not hold any image layer or other writable storage.

scalability_and_performance/optimizing-storage.adoc

@@ -26,3 +26,5 @@ are working in an efficient manner.
 include::modules/available-persistent-storage-options.adoc[leveloffset=+1]
 
 include::modules/recommended-configurable-storage-technology.adoc[leveloffset=+1]
+
+include::modules/data-storage-management.adoc[leveloffset=+1]

storage/understanding-ephemeral-storage.adoc

@@ -0,0 +1,13 @@
+[id="understanding-ephemeral-storage"]
+= Understanding ephemeral storage
+include::modules/common-attributes.adoc[]
+:context: understanding-ephemeral-storage
+toc::[]
+
+include::modules/storage-ephemeral-storage-overview.adoc[leveloffset=+1]
+
+include::modules/storage-ephemeral-storage-types.adoc[leveloffset=+1]
+
+include::modules/storage-ephemeral-storage-manage.adoc[leveloffset=+1]
+
+include::modules/storage-ephemeral-storage-monitoring.adoc[leveloffset=+1]