Skip to content

Commit 162cc29

Browse files
lpettyjolpettyjo
authored
Merge pull request #46145 from lpettyjo/OSDOCS-3693
OSDOCS-3693: Generic Ephemeral Volumes (GA)
2 parents a70196f + 502f8c6 commit 162cc29

8 files changed

+249
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1334,6 +1334,9 @@ Topics:
13341334
File: persistent-storage-csi-ovirt
13351335
- Name: VMware vSphere CSI Driver Operator
13361336
File: persistent-storage-csi-vsphere
1337+
- Name: Generic ephemeral volumes
1338+
File: generic-ephemeral-vols
1339+
Distros: openshift-enterprise,openshift-origin,openshift-online
13371340
- Name: Expanding persistent volumes
13381341
File: expanding-persistent-volumes
13391342
Distros: openshift-enterprise,openshift-origin

‎modules/storage-ephemeral-vols-lifecycle.adoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/generic-ephemeral-vols.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="generic-ephemeral-vols-lifecycle_{context}"]
7+
= Lifecycle and persistent volume claims
8+
9+
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:
10+
11+
12+
* Either immediately, if the storage class uses immediate volume binding.
13+
+
14+
With immediate binding, the scheduler is forced to select a node that has access to the volume after it is available.
15+
16+
* When the pod is tentatively scheduled onto a node (`WaitForFirstConsumervolume` binding mode).
17+
+
18+
This volume binding option is recommended for generic ephemeral volumes because then the scheduler can choose a suitable node for the pod.
19+
20+
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‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/generic-ephemeral-vols.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="generic-ephemeral-vols-overview_{context}"]
7+
= Overview
8+
9+
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.
10+
11+
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.
12+
13+
Generic ephemeral volumes have the following features:
14+
15+
* Storage can be local or network-attached.
16+
17+
* Volumes can have a fixed size that pods are not able to exceed.
18+
19+
* Volumes might have some initial data, depending on the driver and parameters.
20+
21+
* Typical operations on volumes are supported, assuming that the driver supports them, including snapshotting, cloning, resizing, and storage capacity tracking.
22+
23+
[NOTE]
24+
====
25+
Generic ephemeral volumes do not support offline snapshots and resize.
26+
27+
Due to this limitation, the following Container Storage Interface (CSI) drivers do not support the following features for generic ephemeral volumes:
28+
29+
* Azure Disk CSI driver does not support resize.
30+
31+
* Cinder CSI driver does not support snapshot.
32+
====

‎modules/storage-ephemeral-vols-procedure.adoc‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/generic-ephemeral-vols.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="generic-ephemeral-vols-procedure_{context}"]
7+
= Creating generic ephemeral volumes
8+
9+
.Procedure
10+
11+
. Create the `pod` object definition and save it to a file.
12+
13+
. Include the generic ephemeral volume information in the file.
14+
+
15+
.my-example-pod-with-generic-vols.yaml
16+
[source, yaml]
17+
----
18+
kind: Pod
19+
apiVersion: v1
20+
metadata:
21+
name: my-app
22+
spec:
23+
containers:
24+
- name: my-frontend
25+
image: busybox:1.28
26+
volumeMounts:
27+
- mountPath: "/mnt/storage"
28+
name: data
29+
command: [ "sleep", "1000000" ]
30+
volumes:
31+
- name: data <1>
32+
ephemeral:
33+
volumeClaimTemplate:
34+
metadata:
35+
labels:
36+
type: my-app-ephvol
37+
spec:
38+
accessModes: [ "ReadWriteOnce" ]
39+
storageClassName: "gp2-csi"
40+
resources:
41+
requests:
42+
storage: 1Gi
43+
44+
----
45+
<1> Generic ephemeral volume claim

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/generic-ephemeral-vols.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="generic-ephemeral-vols-pvc-naming_{context}"]
7+
= Persistent volume claim naming
8+
9+
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.
10+
11+
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".
12+
13+
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.
14+
15+
[IMPORTANT]
16+
====
17+
Be careful when naming pods and volumes inside the same namespace so that naming conflicts do not occur.
18+
====

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

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/generic-ephemeral-vols.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="generic-ephemeral-vols-scc-bug_{context}"]
7+
= Creating a custom SCC to allow use of generic ephemeral volumes
8+
9+
The default security context constraint (SCC) might cause a cluster deployment using generic ephemeral volumes to remain in the pending state.
10+
11+
To work around this issue, you can create a custom SCC.
12+
13+
.Procedure
14+
15+
. Copy the restricted SCC by running the following command:
16+
+
17+
[source, terminal]
18+
----
19+
$ oc get scc restricted -o yaml > ephemeral_restricted_scc.yaml
20+
----
21+
22+
. Modify the SCC YAML file as follows:
23+
+
24+
* Remove the generated metadata.
25+
* Change the name of the SCC.
26+
* Under the `volumes` section, add an `ephemeral` value.
27+
+
28+
.ephemera_restricted_scc.yaml
29+
[source, yaml]
30+
----
31+
allowHostDirVolumePlugin: false
32+
allowHostIPC: false
33+
allowHostNetwork: false
34+
allowHostPID: false
35+
allowHostPorts: false
36+
allowPrivilegeEscalation: true
37+
allowPrivilegedContainer: false
38+
allowedCapabilities: null
39+
apiVersion: security.openshift.io/v1
40+
defaultAddCapabilities: null
41+
fsGroup:
42+
type: MustRunAs
43+
groups: []
44+
kind: SecurityContextConstraints
45+
metadata:
46+
name: ephemeral-restricted <1>
47+
priority: null
48+
readOnlyRootFilesystem: false
49+
requiredDropCapabilities:
50+
- KILL
51+
- MKNOD
52+
- SETUID
53+
- SETGID
54+
runAsUser:
55+
type: MustRunAsRange
56+
seLinuxContext:
57+
type: MustRunAs
58+
supplementalGroups:
59+
type: RunAsAny
60+
users: []
61+
volumes:
62+
- configMap
63+
- downwardAPI
64+
- emptyDir
65+
- persistentVolumeClaim
66+
- projected
67+
- secret
68+
- ephemeral <2>
69+
----
70+
<1> New SCC name.
71+
<2> Specifies ephemeral volumes.
72+
73+
. Create the new SCC YAML file using the following command:
74+
+
75+
[source, terminal]
76+
----
77+
$ oc create -f ephemeral_restricted_scc.yaml
78+
----
79+
80+
.Next steps
81+
82+
This new SCC can be either assigned to individual projects or groups. For more information, see _Managing security context constraints_.
83+
84+
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.
85+
86+
To assign the new SCC to a specific namespace, use the following command:
87+
88+
[source, terminal]
89+
----
90+
$ oc adm policy add-scc-to-group <scc_name> \ system:serviceaccounts:<serviceaccount_namespace>
91+
----

‎modules/storage-ephemeral-vols-security.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * storage/generic-ephemeral-vols.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="generic-ephemeral-security_{context}"]
7+
= Security
8+
9+
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.
10+
11+
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‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_content-type: ASSEMBLY
2+
[id="generic-ephemeral-volumes"]
3+
= Generic ephemeral volumes
4+
include::_attributes/common-attributes.adoc[]
5+
:context: generic-ephemeral-volumes
6+
7+
toc::[]
8+
9+
include::modules/storage-ephemeral-vols-overview.adoc[leveloffset=+1]
10+
11+
include::modules/storage-ephemeral-vols-lifecycle.adoc[leveloffset=+1]
12+
13+
[role="_additional-resources"]
14+
.Additional resources
15+
16+
* xref:../storage/generic-ephemeral-vols.adoc#generic-ephemeral-vols-procedure_generic-ephemeral-volumes[Creating generic ephemeral volumes]
17+
18+
include::modules/storage-ephemeral-vols-security.adoc[leveloffset=+1]
19+
20+
include::modules/storage-ephemeral-vols-pvc-naming.adoc[leveloffset=+1]
21+
22+
include::modules/storage-ephemeral-vols-scc-bug.adoc[leveloffset=+1]
23+
24+
[role="_additional-resources"]
25+
.Additional resources
26+
27+
* xref:../authentication/managing-security-context-constraints.adoc[Managing security context constraints]
28+
29+
include::modules/storage-ephemeral-vols-procedure.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)