Merge pull request #2310 from AndrewSirenko/ephemeral-example

Add EBS-backed Ephemeral Volume example to documentation

examples/kubernetes/README.md

@@ -4,6 +4,7 @@
 * [Dynamic Provisioning](dynamic-provisioning)
 * [StorageClass Parameters](storageclass)
 * [Block Volume](block-volume)
+* [Generic Ephemeral Volume](ephemeral-volume)
 * [Volume Snapshot](snapshot)
 * [Volume Resizing](resizing)
-* [Windows Volumes](windows)
+* [Windows Volumes](windows)

examples/kubernetes/ephemeral-volume/README.md

@@ -0,0 +1,53 @@
+# EBS-backed Generic Ephemeral Volume
+
+## Prerequisites
+
+1. Kubernetes 1.23+
+2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed.
+
+## Usage
+
+This example shows you how to use EBS-backed [generic ephemeral volumes](https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/#generic-ephemeral-volumes) in your cluster to have Kubernetes ensure volumes are created and deleted alongside their Pods. See [Kubernetes documentation on generic ephemeral volume lifecycle and PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/ephemeral-volumes/#lifecycle-and-persistentvolumeclaim) for more information.
+
+1. Deploy the provided pod on your cluster along with the `StorageClass`. Note that we do not create a `PersistentVolumeClaim`:
+    ```sh
+    $ kubectl apply -f manifests
+
+    pod/app created
+    storageclass.storage.k8s.io/ebs-ephemeral-demo created
+    ```
+
+2. Validate the `PersistentVolumeClaim` Kubernetes created on your behalf is bound to a `PersistentVolume`.
+    ```sh
+    $ kubectl get pvc app-persistent-storage
+
+    NAME        STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   
+    ebs-claim   Bound    pvc-9124c6d0-382a-49c5-9494-bcb60f6c0c9c   1Gi        RWO            ebs-ephemeral-demo 
+    ```
+
+3. Validate the pod successfully wrote data to the volume:
+    ```sh
+    $ kubectl exec app -- cat /data/out.txt
+
+    Fri Jan 24 17:15:42 UTC 2025
+    ...
+    ```
+
+4. Cleanup resources:
+    ```sh
+    $ kubectl delete -f manifests
+
+    pod "app" deleted
+    storageclass.storage.k8s.io "ebs-ephemeral-demo" deleted
+    ```
+
+5. Validate that Kubernetes deleted the `PersistentVolumeClaim` and released the `PersistentVolume` on your behalf:
+    ```sh
+    $ kubectl get pvc app-persistent-storage
+
+    Error from server (NotFound): persistentvolumeclaims "app-persistent-storage" not found
+
+    $ kubectl get pv <PV_NAME>
+   
+    Error from server (NotFound): persistentvolumes "pvc-9124c6d0-382a-49c5-9494-bcb60f6c0c9c" not found
+    ```

examples/kubernetes/ephemeral-volume/manifests/pod.yaml

@@ -0,0 +1,37 @@
+# Copyright 2024 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an 'AS IS' BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+kind: Pod
+metadata:
+  name: app
+spec:
+  containers:
+    - name: app
+      image: centos
+      command: ["/bin/sh"]
+      args: ["-c", "while true; do echo $(date -u) >> /data/out.txt; sleep 5; done"]
+      volumeMounts:
+        - name: persistent-storage
+          mountPath: /data
+  volumes:
+    - name: persistent-storage
+      ephemeral:
+        volumeClaimTemplate:
+          spec:
+            accessModes: [ "ReadWriteOnce" ]
+            storageClassName: ebs-ephemeral-demo
+            resources:
+              requests:
+                storage: 1Gi

examples/kubernetes/ephemeral-volume/manifests/storageclass.yaml

@@ -0,0 +1,22 @@
+# Copyright 2025 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the 'License');
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an 'AS IS' BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: ebs-ephemeral-demo
+provisioner: ebs.csi.aws.com
+allowVolumeExpansion: true
+reclaimPolicy: Delete
+volumeBindingMode: WaitForFirstConsumer