OSDOCS-3693:Generic Ephemeral Vols (GA)

_topic_maps/_topic_map.yml

@@ -1335,6 +1335,9 @@ Topics:
     File: persistent-storage-csi-ovirt
   - Name: VMware vSphere CSI Driver Operator
     File: persistent-storage-csi-vsphere
+- Name: Generic ephemeral volumes
+  File: generic-ephemeral-vols
+  Distros: openshift-enterprise,openshift-origin,openshift-online
 - Name: Expanding persistent volumes
   File: expanding-persistent-volumes
   Distros: openshift-enterprise,openshift-origin

modules/storage-ephemeral-vols-lifecycle.adoc

@@ -0,0 +1,20 @@
+// Module included in the following assemblies:
+//
+// * storage/generic-ephemeral-vols.adoc
+
+:_content-type: CONCEPT
+[id="generic-ephemeral-vols-lifecycle_{context}"]
+= Lifecycle and persistent volume claims
+
+The parameters for a volume claim are allowed inside a volume source of a pod. Labels, annotations, and the whole set of fields for persistent volume claims (PVCs) are supported. When such a pod is created, the ephemeral volume controller then creates an actual PVC object (from the template shown in the _Creating generic ephemeral volumes_ procedure) in the same namespace as the pod, and ensures that the PVC is deleted when the pod is deleted. This triggers volume binding and provisioning in one of two ways:
+
+
+* Either immediately, if the storage class uses immediate volume binding.
++
+With immediate binding, the scheduler is forced to select a node that has access to the volume after it is available.
+
+* When the pod is tentatively scheduled onto a node (`WaitForFirstConsumervolume` binding mode).
++
+This volume binding option is recommended for generic ephemeral volumes because then the scheduler can choose a suitable node for the pod.
+
+In terms of resource ownership, a pod that has generic ephemeral storage is the owner of the PVCs that provide that ephemeral storage. When the pod is deleted, the Kubernetes garbage collector deletes the PVC, which then usually triggers deletion of the volume because the default reclaim policy of storage classes is to delete volumes. You can create quasi-ephemeral local storage by using a storage class with a reclaim policy of retain: the storage outlives the pod, and in this case, you must ensure that volume clean-up happens separately. While these PVCs exist, they can be used like any other PVC. In particular, they can be referenced as data source in volume cloning or snapshotting. The PVC object also holds the current status of the volume.

modules/storage-ephemeral-vols-overview.adoc

@@ -0,0 +1,32 @@
+// Module included in the following assemblies:
+//
+// * storage/generic-ephemeral-vols.adoc
+
+:_content-type: CONCEPT
+[id="generic-ephemeral-vols-overview_{context}"]
+= Overview
+
+Generic ephemeral volumes are a type of ephemeral volume that can be provided by all storage drivers that support persistent volumes and dynamic provisioning. Generic ephemeral volumes are similar to `emptyDir` volumes in that they provide a per-pod directory for scratch data, which is usually empty after provisioning.
+
+Generic ephemeral volumes are specified inline in the pod spec and follow the pod's lifecycle. They are created and deleted along with the pod.
+
+Generic ephemeral volumes have the following features:
+
+* Storage can be local or network-attached.
+
+* Volumes can have a fixed size that pods are not able to exceed.
+
+* Volumes might have some initial data, depending on the driver and parameters.
+
+* Typical operations on volumes are supported, assuming that the driver supports them, including snapshotting, cloning, resizing, and storage capacity tracking.
+
+[NOTE]
+====
+Generic ephemeral volumes do not support offline snapshots and resize.
+
+Due to this limitation, the following Container Storage Interface (CSI) drivers do not support the following features for generic ephemeral volumes:
+
+* Azure Disk CSI driver does not support resize.
+
+* Cinder CSI driver does not support snapshot.
+====

modules/storage-ephemeral-vols-procedure.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * storage/generic-ephemeral-vols.adoc
+
+:_content-type: PROCEDURE
+[id="generic-ephemeral-vols-procedure_{context}"]
+= Creating generic ephemeral volumes
+
+.Procedure
+
+. Create the `pod` object definition and save it to a file.
+
+. Include the generic ephemeral volume information in the file.
++
+.my-example-pod-with-generic-vols.yaml
+[source, yaml]
+----
+kind: Pod
+apiVersion: v1
+metadata:
+  name: my-app
+spec:
+  containers:
+    - name: my-frontend
+      image: busybox:1.28
+      volumeMounts:
+      - mountPath: "/mnt/storage"
+        name: data
+      command: [ "sleep", "1000000" ]
+  volumes:
+    - name: data <1>
+      ephemeral:
+        volumeClaimTemplate:
+          metadata:
+            labels:
+              type: my-app-ephvol
+          spec:
+            accessModes: [ "ReadWriteOnce" ]
+            storageClassName: "gp2-csi"
+            resources:
+              requests:
+                storage: 1Gi
+
+----
+<1> Generic ephemeral volume claim

modules/storage-ephemeral-vols-pvc-naming.adoc

@@ -0,0 +1,18 @@
+// Module included in the following assemblies:
+//
+// * storage/generic-ephemeral-vols.adoc
+
+:_content-type: CONCEPT
+[id="generic-ephemeral-vols-pvc-naming_{context}"]
+= Persistent volume claim naming
+
+Automatically created persistent volume claims (PVCs) are named by a combination of the pod name and the volume name, with a hyphen (-) in the middle. This naming convention also introduces a potential conflict between different pods, and between pods and manually created PVCs.
+
+For example: a pod "pod-a" with volume "scratch" and another pod with name "pod" and volume: "a-scratch" both end up with the same PVC name: "pod-a-scratch".
+
+Such conflicts are detected, and a PVC is only used for an ephemeral volume if it was created for the pod. This check is based on the ownership relationship. An existing PVC is not overwritten or modified, but this does not resolve the conflict because without the right PVC, the pod cannot start.
+
+[IMPORTANT]
+====
+Be careful when naming pods and volumes inside the same namespace so that naming conflicts do not occur.
+====

modules/storage-ephemeral-vols-scc-bug.adoc

@@ -0,0 +1,91 @@
+// Module included in the following assemblies:
+//
+// * storage/generic-ephemeral-vols.adoc
+
+:_content-type: PROCEDURE
+[id="generic-ephemeral-vols-scc-bug_{context}"]
+= Creating a custom SCC to allow use of generic ephemeral volumes
+
+The default security context constraint (SCC) might cause a cluster deployment using generic ephemeral volumes to remain in the pending state.
+
+To work around this issue, you can create a custom SCC.
+
+.Procedure
+
+. Copy the  restricted SCC by running the following command:
++
+[source, terminal]
+----
+$ oc get scc restricted -o yaml > ephemeral_restricted_scc.yaml
+----
+
+. Modify the SCC YAML file as follows:
++
+* Remove the generated metadata.
+* Change the name of the SCC.
+* Under the `volumes` section, add an `ephemeral` value.
++
+.ephemera_restricted_scc.yaml
+[source, yaml]
+----
+allowHostDirVolumePlugin: false
+allowHostIPC: false
+allowHostNetwork: false
+allowHostPID: false
+allowHostPorts: false
+allowPrivilegeEscalation: true
+allowPrivilegedContainer: false
+allowedCapabilities: null
+apiVersion: security.openshift.io/v1
+defaultAddCapabilities: null
+fsGroup:
+ type: MustRunAs
+groups: []
+kind: SecurityContextConstraints
+metadata:
+ name: ephemeral-restricted <1>
+priority: null
+readOnlyRootFilesystem: false
+requiredDropCapabilities:
+- KILL
+- MKNOD
+- SETUID
+- SETGID
+runAsUser:
+ type: MustRunAsRange
+seLinuxContext:
+ type: MustRunAs
+supplementalGroups:
+ type: RunAsAny
+users: []
+volumes:
+- configMap
+- downwardAPI
+- emptyDir
+- persistentVolumeClaim
+- projected
+- secret
+- ephemeral <2>
+----
+<1> New SCC name.
+<2> Specifies ephemeral volumes.
+
+. Create the new SCC YAML file using the following command:
++
+[source, terminal]
+----
+$ oc create -f ephemeral_restricted_scc.yaml
+----
+
+.Next steps
+
+This new SCC can be either assigned to individual projects or groups. For more information, see _Managing security context constraints_.
+
+Also, the newly created SCC can be assigned to a specific namespace, so that only the pods that are in that namespace can have access to this new SCC. This allows users in that namespace to create pods that use generic ephemeral volumes.
+
+To assign the new SCC to a specific namespace, use the following command:
+
+[source, terminal]
+----
+$ oc adm policy add-scc-to-group <scc_name> \ system:serviceaccounts:<serviceaccount_namespace>
+----

modules/storage-ephemeral-vols-security.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * storage/generic-ephemeral-vols.adoc
+
+:_content-type: CONCEPT
+[id="generic-ephemeral-security_{context}"]
+= Security
+
+Enabling the generic ephemeral volume feature allows users to create persistent volume claims (PVCs) indirectly if they can create pods, even if they do not have permission to create PVCs directly. Cluster administrators must be aware of this. If this does not fit their security model, they should use an admission webhook that rejects objects like pods that have a generic ephemeral volume.
+
+The normal namespace quota for PVCs still applies, so even if users are allowed to use this new mechanism, they cannot use it to circumvent other policies.

storage/generic-ephemeral-vols.adoc

@@ -0,0 +1,29 @@
+:_content-type: ASSEMBLY
+[id="generic-ephemeral-volumes"]
+= Generic ephemeral volumes
+include::_attributes/common-attributes.adoc[]
+:context: generic-ephemeral-volumes
+
+toc::[]
+
+include::modules/storage-ephemeral-vols-overview.adoc[leveloffset=+1]
+
+include::modules/storage-ephemeral-vols-lifecycle.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../storage/generic-ephemeral-vols.adoc#generic-ephemeral-vols-procedure_generic-ephemeral-volumes[Creating generic ephemeral volumes]
+
+include::modules/storage-ephemeral-vols-security.adoc[leveloffset=+1]
+
+include::modules/storage-ephemeral-vols-pvc-naming.adoc[leveloffset=+1]
+
+include::modules/storage-ephemeral-vols-scc-bug.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../authentication/managing-security-context-constraints.adoc[Managing security context constraints]
+
+include::modules/storage-ephemeral-vols-procedure.adoc[leveloffset=+1]