From 710aaa552be7fa7d6f5084243c070dc823ea4cdd Mon Sep 17 00:00:00 2001 From: Bob Furu Date: Tue, 11 Aug 2020 17:14:02 -0400 Subject: [PATCH] BZ1769845 - Add storage mgmnt table and ephemeral storage docs --- _topic_map.yml | 3 ++ modules/data-storage-management.adoc | 41 +++++++++++++++++++ modules/feature-gate-features.adoc | 3 -- modules/storage-ephemeral-storage-manage.adoc | 8 ++++ .../storage-ephemeral-storage-monitoring.adoc | 24 +++++++++++ .../storage-ephemeral-storage-overview.adoc | 34 +++++++++++++++ modules/storage-ephemeral-storage-types.adoc | 30 ++++++++++++++ .../optimizing-storage.adoc | 2 + storage/understanding-ephemeral-storage.adoc | 13 ++++++ 9 files changed, 155 insertions(+), 3 deletions(-) create mode 100644 modules/data-storage-management.adoc create mode 100644 modules/storage-ephemeral-storage-manage.adoc create mode 100644 modules/storage-ephemeral-storage-monitoring.adoc create mode 100644 modules/storage-ephemeral-storage-overview.adoc create mode 100644 modules/storage-ephemeral-storage-types.adoc create mode 100644 storage/understanding-ephemeral-storage.adoc diff --git a/_topic_map.yml b/_topic_map.yml index cacb32fde6..fb547f0f4e 100644 --- a/_topic_map.yml +++ b/_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 diff --git a/modules/data-storage-management.adoc b/modules/data-storage-management.adoc new file mode 100644 index 0000000000..5093c5df74 --- /dev/null +++ b/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. + +|=== diff --git a/modules/feature-gate-features.adoc b/modules/feature-gate-features.adoc index e0ee1857f2..271434204e 100644 --- a/modules/feature-gate-features.adoc +++ b/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. - diff --git a/modules/storage-ephemeral-storage-manage.adoc b/modules/storage-ephemeral-storage-manage.adoc new file mode 100644 index 0000000000..ff1f1c50e2 --- /dev/null +++ b/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. diff --git a/modules/storage-ephemeral-storage-monitoring.adoc b/modules/storage-ephemeral-storage-monitoring.adoc new file mode 100644 index 0000000000..9036740ea4 --- /dev/null +++ b/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% / +---- diff --git a/modules/storage-ephemeral-storage-overview.adoc b/modules/storage-ephemeral-storage-overview.adoc new file mode 100644 index 0000000000..c894496390 --- /dev/null +++ b/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. diff --git a/modules/storage-ephemeral-storage-types.adoc b/modules/storage-ephemeral-storage-types.adoc new file mode 100644 index 0000000000..b677e702e6 --- /dev/null +++ b/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. diff --git a/scalability_and_performance/optimizing-storage.adoc b/scalability_and_performance/optimizing-storage.adoc index ae0f7e347d..e4a67f251a 100644 --- a/scalability_and_performance/optimizing-storage.adoc +++ b/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] diff --git a/storage/understanding-ephemeral-storage.adoc b/storage/understanding-ephemeral-storage.adoc new file mode 100644 index 0000000000..192dee0f0a --- /dev/null +++ b/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]