From 2099c2a75506f14e519b45dd9cbc2dbd88ea3e2d Mon Sep 17 00:00:00 2001 From: torredil Date: Fri, 25 Feb 2022 00:14:44 +0000 Subject: [PATCH] Update examples documentation Signed-off-by: torredil --- examples/kubernetes/block-volume/README.md | 73 +++++----- .../raw-claim.yaml => manifests/claim.yaml} | 2 +- .../{specs => manifests}/pod.yaml | 0 .../manifests}/storageclass.yaml | 2 +- .../kubernetes/dynamic-provisioning/README.md | 50 ++++--- .../manifests}/claim.yaml | 2 +- .../dynamic-provisioning/manifests/pod.yaml | 17 +++ .../manifests}/storageclass.yaml | 2 +- examples/kubernetes/resizing/README.md | 87 ++++++------ .../kubernetes/resizing/manifests/claim.yaml | 11 ++ .../kubernetes/resizing/manifests/pod.yaml | 17 +++ .../resizing/manifests/storageclass.yaml | 6 + .../kubernetes/resizing/spec/example.yaml | 36 ----- examples/kubernetes/snapshot/README.md | 125 ++++++++++++------ .../manifests/app}/claim.yaml | 0 .../specs => snapshot/manifests/app}/pod.yaml | 0 .../classes/snapshotclass.yaml | 0 .../manifests/classes}/storageclass.yaml | 0 .../snapshot-import/README.md | 0 .../snapshot-import/app/claim.yaml | 0 .../snapshot-import/app/pod.yaml | 0 .../volume-snapshot-content.yaml | 0 .../static-snapshot/volume-snapshot.yaml | 0 .../snapshot-restore/claim.yaml | 0 .../snapshot-restore/pod.yaml | 0 .../snapshot/snapshot.yaml | 0 .../kubernetes/static-provisioning/README.md | 111 +++++++++------- .../static-provisioning/manifests/claim.yaml | 10 ++ .../manifests}/pod.yaml | 0 .../static-provisioning/manifests/pv.yaml | 20 +++ .../static-provisioning/specs/example.yaml | 54 -------- examples/kubernetes/storageclass/README.md | 55 +++++--- .../storageclass/manifests/claim.yaml | 11 ++ .../storageclass/manifests/pod.yaml | 17 +++ .../storageclass/manifests/storageclass.yaml | 16 +++ .../storageclass/specs/example.yaml | 46 ------- examples/kubernetes/windows/README.md | 1 - 37 files changed, 430 insertions(+), 341 deletions(-) rename examples/kubernetes/block-volume/{specs/raw-claim.yaml => manifests/claim.yaml} (90%) rename examples/kubernetes/block-volume/{specs => manifests}/pod.yaml (100%) rename examples/kubernetes/{dynamic-provisioning/specs => block-volume/manifests}/storageclass.yaml (100%) rename examples/kubernetes/{snapshot/specs/app => dynamic-provisioning/manifests}/claim.yaml (89%) create mode 100644 examples/kubernetes/dynamic-provisioning/manifests/pod.yaml rename examples/kubernetes/{snapshot/specs/classes => dynamic-provisioning/manifests}/storageclass.yaml (100%) create mode 100644 examples/kubernetes/resizing/manifests/claim.yaml create mode 100644 examples/kubernetes/resizing/manifests/pod.yaml create mode 100644 examples/kubernetes/resizing/manifests/storageclass.yaml delete mode 100644 examples/kubernetes/resizing/spec/example.yaml rename examples/kubernetes/{dynamic-provisioning/specs => snapshot/manifests/app}/claim.yaml (100%) rename examples/kubernetes/{dynamic-provisioning/specs => snapshot/manifests/app}/pod.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/classes/snapshotclass.yaml (100%) rename examples/kubernetes/{block-volume/specs => snapshot/manifests/classes}/storageclass.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-import/README.md (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-import/app/claim.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-import/app/pod.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-import/static-snapshot/volume-snapshot-content.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-import/static-snapshot/volume-snapshot.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-restore/claim.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot-restore/pod.yaml (100%) rename examples/kubernetes/snapshot/{specs => manifests}/snapshot/snapshot.yaml (100%) create mode 100644 examples/kubernetes/static-provisioning/manifests/claim.yaml rename examples/kubernetes/{snapshot/specs/app => static-provisioning/manifests}/pod.yaml (100%) create mode 100644 examples/kubernetes/static-provisioning/manifests/pv.yaml delete mode 100644 examples/kubernetes/static-provisioning/specs/example.yaml create mode 100644 examples/kubernetes/storageclass/manifests/claim.yaml create mode 100644 examples/kubernetes/storageclass/manifests/pod.yaml create mode 100644 examples/kubernetes/storageclass/manifests/storageclass.yaml delete mode 100644 examples/kubernetes/storageclass/specs/example.yaml diff --git a/examples/kubernetes/block-volume/README.md b/examples/kubernetes/block-volume/README.md index eb77fd216e..985704b886 100644 --- a/examples/kubernetes/block-volume/README.md +++ b/examples/kubernetes/block-volume/README.md @@ -1,39 +1,36 @@ ## Raw Block Volume -This example shows how to consume a dynamically-provisioned EBS volume as a raw block device. - -### Edit [Persistence Volume Claim Spec](./specs/raw-claim.yaml) -Make sure the `volumeMode` is `Block`. - -### Edit [Application Pod](./specs/pod.yaml) -Make sure the pod is consuming the PVC with the defined name and `volumeDevices` is used instead of `volumeMounts`. - -### Deploy the Application -```sh -kubectl apply -f examples/kubernetes/block-volume/specs/storageclass.yaml -kubectl apply -f examples/kubernetes/block-volume/specs/raw-claim.yaml -kubectl apply -f examples/kubernetes/block-volume/specs/pod.yaml -``` - -### Access Block Device -After the objects are created, verify that pod is running: - -```sh -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -app 1/1 Running 0 16m -``` -Verify the device node is mounted inside the container: - -```sh -$ kubectl exec -ti app -- ls -al /dev/xvda -brw-rw---- 1 root disk 202, 23296 Mar 12 04:23 /dev/xvda -``` - -Write to the device using: - -```sh -dd if=/dev/zero of=/dev/xvda bs=1024k count=100 -100+0 records in -100+0 records out -104857600 bytes (105 MB, 100 MiB) copied, 0.0492386 s, 2.1 GB/s -``` + +## Prerequisites + +1. Kubernetes 1.13+ (CSI 1.0). +2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed. + +## Usage + +This example shows you how to create and consume a dynamically-provisioned EBS volume as a raw block device. + +1. Deploy the provided pod on your cluster along with the `StorageClass` and `PersistentVolumeClaim`: + ```sh + $ kubectl apply -f manifests + + pod/app created + persistentvolumeclaim/block-claim created + storageclass.storage.k8s.io/ebs-sc created + ``` + +2. Validate the `PersistentVolumeClaim` is bound to your `PersistentVolume`. + ```sh + $ kubectl get pvc block-claim + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + block-claim Bound pvc-2074bf0a-4726-44f2-bb7a-eb4292d4f40a 10Gi RWO ebs-sc + ``` + +3. Cleanup resources: + ```sh + $ kubectl delete -f manifests + + pod "app" deleted + persistentvolumeclaim "block-claim" deleted + storageclass.storage.k8s.io "ebs-sc" deleted + ``` \ No newline at end of file diff --git a/examples/kubernetes/block-volume/specs/raw-claim.yaml b/examples/kubernetes/block-volume/manifests/claim.yaml similarity index 90% rename from examples/kubernetes/block-volume/specs/raw-claim.yaml rename to examples/kubernetes/block-volume/manifests/claim.yaml index 538f3e3f4f..9ad9b6dbf6 100644 --- a/examples/kubernetes/block-volume/specs/raw-claim.yaml +++ b/examples/kubernetes/block-volume/manifests/claim.yaml @@ -9,4 +9,4 @@ spec: storageClassName: ebs-sc resources: requests: - storage: 10Gi + storage: 4Gi \ No newline at end of file diff --git a/examples/kubernetes/block-volume/specs/pod.yaml b/examples/kubernetes/block-volume/manifests/pod.yaml similarity index 100% rename from examples/kubernetes/block-volume/specs/pod.yaml rename to examples/kubernetes/block-volume/manifests/pod.yaml diff --git a/examples/kubernetes/dynamic-provisioning/specs/storageclass.yaml b/examples/kubernetes/block-volume/manifests/storageclass.yaml similarity index 100% rename from examples/kubernetes/dynamic-provisioning/specs/storageclass.yaml rename to examples/kubernetes/block-volume/manifests/storageclass.yaml index d6e168e1ec..ebadd544a0 100644 --- a/examples/kubernetes/dynamic-provisioning/specs/storageclass.yaml +++ b/examples/kubernetes/block-volume/manifests/storageclass.yaml @@ -1,5 +1,5 @@ -kind: StorageClass apiVersion: storage.k8s.io/v1 +kind: StorageClass metadata: name: ebs-sc provisioner: ebs.csi.aws.com diff --git a/examples/kubernetes/dynamic-provisioning/README.md b/examples/kubernetes/dynamic-provisioning/README.md index afced29391..8884d97651 100644 --- a/examples/kubernetes/dynamic-provisioning/README.md +++ b/examples/kubernetes/dynamic-provisioning/README.md @@ -1,30 +1,44 @@ # Dynamic Volume Provisioning -This example shows how to create a EBS volume and consume it from container dynamically. ## Prerequisites 1. Kubernetes 1.13+ (CSI 1.0). - -2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) is installed. +2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed. ## Usage -1. Create a sample app along with the StorageClass and the PersistentVolumeClaim: -``` -kubectl apply -f specs/ -``` +This example shows you how to dynamically provision an EBS volume in your cluster. + +1. Deploy the provided pod on your cluster along with the `StorageClass` and `PersistentVolumeClaim`: + ```sh + $ kubectl apply -f manifests + + persistentvolumeclaim/ebs-claim created + pod/app created + storageclass.storage.k8s.io/ebs-sc created + ``` -2. Validate the volume was created and `volumeHandle` contains an EBS volumeID: -``` -kubectl describe pv -``` +2. Validate the `PersistentVolumeClaim` is bound to your `PersistentVolume`. + ```sh + $ kubectl get pvc ebs-claim -3. Validate the pod successfully wrote data to the volume: -``` -kubectl exec -it app cat /data/out.txt -``` + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + ebs-claim Bound pvc-9124c6d0-382a-49c5-9494-bcb60f6c0c9c 4Gi RWO ebs-sc 30m + ``` + +3. Validate the pod successfully wrote data to the dynamically provisioned volume: + ```sh + $ kubectl exec app -- cat /data/out.txt + + Tue Feb 22 01:24:44 UTC 2022 + ... + ``` 4. Cleanup resources: -``` -kubectl delete -f specs/ -``` + ```sh + $ kubectl delete -f manifests + + persistentvolumeclaim "ebs-claim" deleted + pod "app" deleted + storageclass.storage.k8s.io "ebs-sc" deleted + ``` diff --git a/examples/kubernetes/snapshot/specs/app/claim.yaml b/examples/kubernetes/dynamic-provisioning/manifests/claim.yaml similarity index 89% rename from examples/kubernetes/snapshot/specs/app/claim.yaml rename to examples/kubernetes/dynamic-provisioning/manifests/claim.yaml index a883baa530..5e6eede717 100644 --- a/examples/kubernetes/snapshot/specs/app/claim.yaml +++ b/examples/kubernetes/dynamic-provisioning/manifests/claim.yaml @@ -8,4 +8,4 @@ spec: storageClassName: ebs-sc resources: requests: - storage: 4Gi + storage: 4Gi \ No newline at end of file diff --git a/examples/kubernetes/dynamic-provisioning/manifests/pod.yaml b/examples/kubernetes/dynamic-provisioning/manifests/pod.yaml new file mode 100644 index 0000000000..4a72260fb4 --- /dev/null +++ b/examples/kubernetes/dynamic-provisioning/manifests/pod.yaml @@ -0,0 +1,17 @@ +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 + persistentVolumeClaim: + claimName: ebs-claim \ No newline at end of file diff --git a/examples/kubernetes/snapshot/specs/classes/storageclass.yaml b/examples/kubernetes/dynamic-provisioning/manifests/storageclass.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/classes/storageclass.yaml rename to examples/kubernetes/dynamic-provisioning/manifests/storageclass.yaml index d6e168e1ec..ebadd544a0 100644 --- a/examples/kubernetes/snapshot/specs/classes/storageclass.yaml +++ b/examples/kubernetes/dynamic-provisioning/manifests/storageclass.yaml @@ -1,5 +1,5 @@ -kind: StorageClass apiVersion: storage.k8s.io/v1 +kind: StorageClass metadata: name: ebs-sc provisioner: ebs.csi.aws.com diff --git a/examples/kubernetes/resizing/README.md b/examples/kubernetes/resizing/README.md index 2469f24632..10e27909d7 100644 --- a/examples/kubernetes/resizing/README.md +++ b/examples/kubernetes/resizing/README.md @@ -1,43 +1,52 @@ ## Volume Resizing -This example shows how to resize EBS persistence volume using volume resizing features. -**Note** -1. CSI volume resizing is still alpha as of Kubernetes 1.15 -2. EBS has a limit of one volume modification every 6 hours. Refer to [EBS documentation](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyVolume.html) for more details. +## Prerequisites + +1. Kubernetes 1.13+ (CSI 1.0). +2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed. ## Usage -1. Add `allowVolumeExpansion: true` in the StorageClass spec in [example manifest](./spec/example.yaml) to enable volume expansion. You can only expand a PVC if its storage class’s allowVolumeExpansion field is set to true - -2. Deploy the example: -```sh -kubectl apply -f specs/ -``` - -3. Verify the volume is created and Pod is running: -```sh -kubectl get pv -kubectl get po app -``` - -4. Expand the volume size by increasing the capacity in PVC's `spec.resources.requests.storage`: -```sh -kubectl edit pvc ebs-claim -``` -Save the result at the end of the edit. - -5. Verify that both the persistence volume and persistence volume claim are resized: -```sh -kubectl get pv -kubectl get pvc -``` -You should see that both should have the new value relfected in the capacity fields. - -6. Verify that the application is continuously running without any interruption: -```sh -kubectl exec -it app cat /data/out.txt -``` - -7. Cleanup resources: -``` -kubectl delete -f specs/ -``` + +In this example, an EBS volume of `4Gi` is resized to `8Gi` using the volume resizing feature. + +1. Deploy the provided pod on your cluster along with the `StorageClass` and `PersistentVolumeClaim`: + ```sh + $ kubectl apply -f manifests + + persistentvolumeclaim/ebs-claim created + pod/app created + storageclass.storage.k8s.io/resize-sc created + ``` + +2. Validate the `PersistentVolumeClaim` is bound to your `PersistentVolume`. + ```sh + $ kubectl get pvc ebs-claim + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + ebs-claim Bound pvc-b0f6d590-f4b3-4329-a118-49cd09f6993c 4Gi RWO resize-sc 28s + ``` + +3. Expand the volume size by increasing the `capacity` specification in the `PersistentVolumeClaim`. + ```sh + $ export KUBE_EDITOR="nano" && kubectl edit pvc ebs-claim + ``` + +4. Verify that both the persistence volume and persistence volume claim have been appropriately resized: + ```sh + $ kubectl get pv && kubectl get pvc + + NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS + pvc-b0f6d590-f4b3-4329-a118-49cd09f6993c 8Gi RWO Delete Bound default/ebs-claim resize-sc + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + ebs-claim Bound pvc-b0f6d590-f4b3-4329-a118-49cd09f6993c 8Gi RWO resize-sc 23m + ``` + +5. Cleanup resources: + ```sh + $ kubectl delete -f manifests + + persistentvolumeclaim "ebs-claim" deleted + pod "app" deleted + storageclass.storage.k8s.io "resize-sc" deleted + ``` diff --git a/examples/kubernetes/resizing/manifests/claim.yaml b/examples/kubernetes/resizing/manifests/claim.yaml new file mode 100644 index 0000000000..4225cf2cd7 --- /dev/null +++ b/examples/kubernetes/resizing/manifests/claim.yaml @@ -0,0 +1,11 @@ +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: ebs-claim +spec: + accessModes: + - ReadWriteOnce + storageClassName: resize-sc + resources: + requests: + storage: 4Gi \ No newline at end of file diff --git a/examples/kubernetes/resizing/manifests/pod.yaml b/examples/kubernetes/resizing/manifests/pod.yaml new file mode 100644 index 0000000000..d35fd7d234 --- /dev/null +++ b/examples/kubernetes/resizing/manifests/pod.yaml @@ -0,0 +1,17 @@ +apiVersion: v1 +kind: Pod +metadata: + name: app +spec: + containers: + - name: app + image: centos + command: ["/bin/sh"] + args: ["tail -f /dev/null"] + volumeMounts: + - name: persistent-storage + mountPath: /data + volumes: + - name: persistent-storage + persistentVolumeClaim: + claimName: ebs-claim \ No newline at end of file diff --git a/examples/kubernetes/resizing/manifests/storageclass.yaml b/examples/kubernetes/resizing/manifests/storageclass.yaml new file mode 100644 index 0000000000..c1318759c4 --- /dev/null +++ b/examples/kubernetes/resizing/manifests/storageclass.yaml @@ -0,0 +1,6 @@ +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: resize-sc +provisioner: ebs.csi.aws.com +allowVolumeExpansion: true \ No newline at end of file diff --git a/examples/kubernetes/resizing/spec/example.yaml b/examples/kubernetes/resizing/spec/example.yaml deleted file mode 100644 index a3b73637cd..0000000000 --- a/examples/kubernetes/resizing/spec/example.yaml +++ /dev/null @@ -1,36 +0,0 @@ -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: resize-sc -provisioner: ebs.csi.aws.com -allowVolumeExpansion: true ---- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: ebs-claim -spec: - accessModes: - - ReadWriteOnce - storageClassName: resize-sc - resources: - requests: - storage: 4Gi ---- -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 - persistentVolumeClaim: - claimName: ebs-claim diff --git a/examples/kubernetes/snapshot/README.md b/examples/kubernetes/snapshot/README.md index 4ae0ad9e19..ea7fdb880f 100644 --- a/examples/kubernetes/snapshot/README.md +++ b/examples/kubernetes/snapshot/README.md @@ -1,70 +1,111 @@ # Volume Snapshots -## Overview - -This driver implements basic volume snapshotting functionality using the [external snapshotter](https://github.com/kubernetes-csi/external-snapshotter) sidecar and creates snapshots of EBS volumes using the `VolumeSnapshot` custom resources. - ## Prerequisites 1. Kubernetes 1.13+ (CSI 1.0). +2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed. +3. The [external snapshotter](https://github.com/kubernetes-csi/external-snapshotter) installed. +4. The `VolumeSnapshotDataSource` is set in `--feature-gates=` in the `kube-apiserver` specification. This feature is enabled by default from Kubernetes v1.17+. -1. The `VolumeSnapshotDataSource` must be set in `--feature-gates=` in the `kube-apiserver`. This feature is enabled by default from Kubernetes v1.17+. +## Usage -1. Install Snapshot Beta CRDs, Common Snapshot Controller, & CSI Driver (with alpha features) per CSI Snapshotter [Doc](https://github.com/kubernetes-csi/external-snapshotter#usage) +This example shows you how to create a snapshot and restore an EBS `PersistentVolume`. +### Create Snapshot +1. Create the `StorageClass` and `VolumeSnapshotClass`: + ```sh + $ kubectl apply -f manifests/classes/ + volumesnapshotclass.snapshot.storage.k8s.io/csi-aws-vsc created + storageclass.storage.k8s.io/ebs-sc created + ``` -### Usage +2. Deploy the provided pod on your cluster along with the `PersistentVolumeClaim`: + ```sh + $ kubectl apply -f manifests/app/ -1. Create the `StorageClass` and `VolumeSnapshotClass`: -``` -kubectl apply -f specs/classes/ -``` + persistentvolumeclaim/ebs-claim created + pod/app created + ``` -2. Create a sample app and the `PersistentVolumeClaim`: -``` -kubectl apply -f specs/app/ -``` +3. Validate the `PersistentVolumeClaim` is bound to your `PersistentVolume`. + ```sh + $ kubectl get pvc ebs-claim -3. Validate the volume was created and `volumeHandle` contains an EBS volumeID: -``` -kubectl describe pv -``` + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + ebs-claim Bound pvc-c2e5476c-d9f5-4a49-bbb2-9dfdb27db4c8 4Gi RWO ebs-sc 43s + ``` 4. Validate the pod successfully wrote data to the volume, taking note of the timestamp of the first entry: -``` -kubectl exec -it app cat /data/out.txt -``` + ```sh + $ kubectl exec app -- cat /data/out.txt + + Thu Feb 24 04:07:57 UTC 2022 + ... + ``` 5. Create a `VolumeSnapshot` referencing the `PersistentVolumeClaim` name: -``` -kubectl apply -f specs/snapshot/ -``` + ```sh + $ kubectl apply -f manifests/snapshot/ + + volumesnapshot.snapshot.storage.k8s.io/ebs-volume-snapshot created + ``` 6. Wait for the `Ready To Use: true` attribute of the `VolumeSnapshot`: -``` -kubectl describe volumesnapshot.snapshot.storage.k8s.io ebs-volume-snapshot -``` + ```sh + $ kubectl describe volumesnapshot.snapshot.storage.k8s.io ebs-volume-snapshot + + ... + Status: + Bound Volume Snapshot Content Name: snapcontent-333215f5-ab85-42b8-b4fc-27a6cba0cc19 + Creation Time: 2022-02-24T04:09:51Z + Ready To Use: true + Restore Size: 4Gi + ``` 7. Delete the existing app: -``` -kubectl delete -f specs/app/ -``` + ```sh + $ kubectl delete -f manifests/app/ + + persistentvolumeclaim "ebs-claim" deleted + pod "app" deleted + ``` +### Restore Volume 8. Restore a volume from the snapshot with a `PersistentVolumeClaim` referencing the `VolumeSnapshot` in its `dataSource`: -``` -kubectl apply -f specs/snapshot-restore/ -``` + ```sh + $ kubectl apply -f manifests/snapshot-restore/ + + persistentvolumeclaim/ebs-snapshot-restored-claim created + pod/app created + ``` 9. Validate the new pod has the restored data by comparing the timestamp of the first entry to that of in step 4: -``` -kubectl exec -it app cat /data/out.txt -``` + ```sh + $ kubectl exec app -- cat /data/out.txt + + Thu Feb 24 04:07:57 UTC 2022 + ... + ``` 10. Cleanup resources: -``` -kubectl delete -f specs/snapshot-restore -kubectl delete -f specs/snapshot -kubectl delete -f specs/classes -``` + ```sh + $ kubectl delete -f manifests/snapshot-restore + + persistentvolumeclaim "ebs-snapshot-restored-claim" deleted + pod "app" deleted + ``` + + ```sh + $ kubectl delete -f manifests/snapshot + + volumesnapshot.snapshot.storage.k8s.io "ebs-volume-snapshot" deleted + ``` + + ```sh + $ kubectl delete -f manifests/classes + + volumesnapshotclass.snapshot.storage.k8s.io "csi-aws-vsc" deleted + storageclass.storage.k8s.io "ebs-sc" deleted + ``` diff --git a/examples/kubernetes/dynamic-provisioning/specs/claim.yaml b/examples/kubernetes/snapshot/manifests/app/claim.yaml similarity index 100% rename from examples/kubernetes/dynamic-provisioning/specs/claim.yaml rename to examples/kubernetes/snapshot/manifests/app/claim.yaml diff --git a/examples/kubernetes/dynamic-provisioning/specs/pod.yaml b/examples/kubernetes/snapshot/manifests/app/pod.yaml similarity index 100% rename from examples/kubernetes/dynamic-provisioning/specs/pod.yaml rename to examples/kubernetes/snapshot/manifests/app/pod.yaml diff --git a/examples/kubernetes/snapshot/specs/classes/snapshotclass.yaml b/examples/kubernetes/snapshot/manifests/classes/snapshotclass.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/classes/snapshotclass.yaml rename to examples/kubernetes/snapshot/manifests/classes/snapshotclass.yaml diff --git a/examples/kubernetes/block-volume/specs/storageclass.yaml b/examples/kubernetes/snapshot/manifests/classes/storageclass.yaml similarity index 100% rename from examples/kubernetes/block-volume/specs/storageclass.yaml rename to examples/kubernetes/snapshot/manifests/classes/storageclass.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot-import/README.md b/examples/kubernetes/snapshot/manifests/snapshot-import/README.md similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-import/README.md rename to examples/kubernetes/snapshot/manifests/snapshot-import/README.md diff --git a/examples/kubernetes/snapshot/specs/snapshot-import/app/claim.yaml b/examples/kubernetes/snapshot/manifests/snapshot-import/app/claim.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-import/app/claim.yaml rename to examples/kubernetes/snapshot/manifests/snapshot-import/app/claim.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot-import/app/pod.yaml b/examples/kubernetes/snapshot/manifests/snapshot-import/app/pod.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-import/app/pod.yaml rename to examples/kubernetes/snapshot/manifests/snapshot-import/app/pod.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot-import/static-snapshot/volume-snapshot-content.yaml b/examples/kubernetes/snapshot/manifests/snapshot-import/static-snapshot/volume-snapshot-content.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-import/static-snapshot/volume-snapshot-content.yaml rename to examples/kubernetes/snapshot/manifests/snapshot-import/static-snapshot/volume-snapshot-content.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot-import/static-snapshot/volume-snapshot.yaml b/examples/kubernetes/snapshot/manifests/snapshot-import/static-snapshot/volume-snapshot.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-import/static-snapshot/volume-snapshot.yaml rename to examples/kubernetes/snapshot/manifests/snapshot-import/static-snapshot/volume-snapshot.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot-restore/claim.yaml b/examples/kubernetes/snapshot/manifests/snapshot-restore/claim.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-restore/claim.yaml rename to examples/kubernetes/snapshot/manifests/snapshot-restore/claim.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot-restore/pod.yaml b/examples/kubernetes/snapshot/manifests/snapshot-restore/pod.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot-restore/pod.yaml rename to examples/kubernetes/snapshot/manifests/snapshot-restore/pod.yaml diff --git a/examples/kubernetes/snapshot/specs/snapshot/snapshot.yaml b/examples/kubernetes/snapshot/manifests/snapshot/snapshot.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/snapshot/snapshot.yaml rename to examples/kubernetes/snapshot/manifests/snapshot/snapshot.yaml diff --git a/examples/kubernetes/static-provisioning/README.md b/examples/kubernetes/static-provisioning/README.md index 2ca00aa615..08634679d1 100644 --- a/examples/kubernetes/static-provisioning/README.md +++ b/examples/kubernetes/static-provisioning/README.md @@ -1,51 +1,70 @@ # Static Provisioning -This example shows how to create and consume persistent volume from exising EBS using static provisioning. + +## Prerequisites + +1. Kubernetes 1.13+ (CSI 1.0). +2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed. +3. Created an [Amazon EBS volume](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ebs-volume-types.html). ## Usage -1. Edit the PersistentVolume spec in [example manifest](./specs/example.yaml). Update `volumeHandle` with EBS volume ID that you are going to use, and update the `fsType` with the filesystem type of the volume. In this example, I have a pre-created EBS volume in us-east-1c availability zone and it is formatted with xfs filesystem. - -``` -apiVersion: v1 -kind: PersistentVolume -metadata: - name: test-pv -spec: - capacity: - storage: 50Gi - volumeMode: Filesystem - accessModes: - - ReadWriteOnce - csi: - driver: ebs.csi.aws.com - volumeHandle: {volumeId} - fsType: xfs - nodeAffinity: - required: - nodeSelectorTerms: - - matchExpressions: - - key: topology.ebs.csi.aws.com/zone - operator: In - values: - - us-east-1c -``` -Note that node affinity is used here since EBS volume is created in us-east-1c, hence only node in the same AZ can consume this persistent volume. - -2. Deploy the example: -```sh -kubectl apply -f specs/ -``` - -3. Verify application pod is running: -```sh -kubectl describe po app -``` - -4. Validate the pod successfully wrote data to the volume: -```sh -kubectl exec -it app cat /data/out.txt -``` + +This example shows you how to create and consume a `PersistentVolume` from an existing EBS volume with static provisioning. + +1. Edit the `PersistentVolume` manifest in [pv.yaml](./manifests/pv.yaml) to include your `volumeHandle` EBS volume ID and `nodeSelectorTerms` zone value. + + ``` + apiVersion: v1 + kind: PersistentVolume + metadata: + name: test-pv + spec: + accessModes: + - ReadWriteOnce + capacity: + storage: 5Gi + csi: + driver: ebs.csi.aws.com + volumeHandle: {EBS volume ID} + nodeAffinity: + required: + nodeSelectorTerms: + - matchExpressions: + - key: topology.ebs.csi.aws.com/zone + operator: In + values: + - {availability zone} + ``` + +2. Deploy the provided pod on your cluster along with the `PersistentVolume` and `PersistentVolumeClaim`: + ```sh + $ kubectl apply -f manifests + + persistentvolumeclaim/ebs-claim created + pod/app created + persistentvolume/test-pv created + ``` + +3. Validate the `PersistentVolumeClaim` is bound to your `PersistentVolume`. + ```sh + $ kubectl get pvc ebs-claim + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + ebs-claim Bound pvc-119a0c81-f45a-4bec-a116-c36cc428cc57 5Gi RWO gp2 53s + ``` + +4. Validate the pod successfully wrote data to the statically provisioned volume: + ```sh + $ kubectl exec app -- cat /data/out.txt + + Tue Feb 22 20:51:37 UTC 2022 + ... + ``` 5. Cleanup resources: -```sh -kubectl delete -f specs/ -``` + ```sh + $ kubectl delete -f manifests + + persistentvolumeclaim "ebs-claim" deleted + pod "app" deleted + persistentvolume "test-pv" deleted + ``` diff --git a/examples/kubernetes/static-provisioning/manifests/claim.yaml b/examples/kubernetes/static-provisioning/manifests/claim.yaml new file mode 100644 index 0000000000..ae94fa6fb9 --- /dev/null +++ b/examples/kubernetes/static-provisioning/manifests/claim.yaml @@ -0,0 +1,10 @@ +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: ebs-claim +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 5Gi \ No newline at end of file diff --git a/examples/kubernetes/snapshot/specs/app/pod.yaml b/examples/kubernetes/static-provisioning/manifests/pod.yaml similarity index 100% rename from examples/kubernetes/snapshot/specs/app/pod.yaml rename to examples/kubernetes/static-provisioning/manifests/pod.yaml diff --git a/examples/kubernetes/static-provisioning/manifests/pv.yaml b/examples/kubernetes/static-provisioning/manifests/pv.yaml new file mode 100644 index 0000000000..1aaa039965 --- /dev/null +++ b/examples/kubernetes/static-provisioning/manifests/pv.yaml @@ -0,0 +1,20 @@ +apiVersion: v1 +kind: PersistentVolume +metadata: + name: test-pv +spec: + accessModes: + - ReadWriteOnce + capacity: + storage: 5Gi + csi: + driver: ebs.csi.aws.com + volumeHandle: vol-03c604538dd7d2f41 + nodeAffinity: + required: + nodeSelectorTerms: + - matchExpressions: + - key: topology.ebs.csi.aws.com/zone + operator: In + values: + - us-east-2c \ No newline at end of file diff --git a/examples/kubernetes/static-provisioning/specs/example.yaml b/examples/kubernetes/static-provisioning/specs/example.yaml deleted file mode 100644 index 49ab85984b..0000000000 --- a/examples/kubernetes/static-provisioning/specs/example.yaml +++ /dev/null @@ -1,54 +0,0 @@ -apiVersion: v1 -kind: PersistentVolume -metadata: - name: test-pv -spec: - capacity: - storage: 50Gi - volumeMode: Filesystem - accessModes: - - ReadWriteOnce - storageClassName: "" - csi: - driver: ebs.csi.aws.com - volumeHandle: vol-05786ec9ec9526b67 - fsType: xfs - nodeAffinity: - required: - nodeSelectorTerms: - - matchExpressions: - - key: topology.ebs.csi.aws.com/zone - operator: In - values: - - us-east-1c ---- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: ebs-claim -spec: - accessModes: - - ReadWriteOnce - storageClassName: "" - resources: - requests: - storage: 50Gi ---- -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 - persistentVolumeClaim: - claimName: ebs-claim diff --git a/examples/kubernetes/storageclass/README.md b/examples/kubernetes/storageclass/README.md index 8d4a1bf183..2576e69a6c 100644 --- a/examples/kubernetes/storageclass/README.md +++ b/examples/kubernetes/storageclass/README.md @@ -1,25 +1,46 @@ # Configuring StorageClass -This example shows how to configure Kubernetes storageclass to provision EBS volumes with various configuration parameters. EBS CSI driver is compatiable with in-tree EBS plugin on StorageClass parameters. For the full list of in-tree EBS plugin parameters, please refer to Kubernetes documentation of [StorageClass Parameter](https://kubernetes.io/docs/concepts/storage/storage-classes/#aws-ebs). + +## Prerequisites + +1. Kubernetes 1.13+ (CSI 1.0). +2. The [aws-ebs-csi-driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) installed. ## Usage -1. Edit the StorageClass spec in [example manifest](./specs/example.yaml) and update storageclass parameters to desired value. In this example, a `io1` EBS volume will be created and formatted to `xfs` filesystem with encryption enabled using the default KMS key. -2. Deploy the example: -```sh -kubectl apply -f specs/ -``` +This example shows you how to write to a dynamically provisioned EBS volume with a specified configuration in the `StorageClass` resource. + +1. Modify the `StorageClass` resource in [`storageclass.yaml`](./manifests/storageclass.yaml) as desired. For a list of supported parameters consult the Kubernetes documentation on [Storage Classes](https://kubernetes.io/docs/concepts/storage/storage-classes/#aws-ebs). + +2. Deploy the provided pod on your cluster along with the `StorageClass` and `PersistentVolumeClaim`: + ```sh + $ kubectl apply -f manifests -3. Verify the volume is created: -```sh -kubectl describe pv -``` + persistentvolumeclaim/ebs-claim created + pod/app created + storageclass.storage.k8s.io/ebs-sc created + ``` -4. Validate the pod successfully wrote data to the volume: -```sh -kubectl exec -it app cat /data/out.txt -``` +3. Validate the `PersistentVolumeClaim` is bound to your `PersistentVolume`. + ```sh + $ kubectl get pvc ebs-claim + + NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE + ebs-claim Bound pvc-1fb712f2-632d-4b63-92e4-3b773d698ae1 4Gi RWO ebs-sc 17s + ``` + +4. Validate the pod successfully wrote data to the dynamically provisioned volume: + ```sh + $ kubectl exec app -- cat /data/out.txt + + Wed Feb 23 19:56:12 UTC 2022 + ... + ``` 5. Cleanup resources: -```sh -kubectl delete -f specs/ -``` + ```sh + $ kubectl delete -f manifests + + persistentvolumeclaim "ebs-claim" deleted + pod "app" deleted + storageclass.storage.k8s.io "ebs-sc" deleted + ``` \ No newline at end of file diff --git a/examples/kubernetes/storageclass/manifests/claim.yaml b/examples/kubernetes/storageclass/manifests/claim.yaml new file mode 100644 index 0000000000..5e6eede717 --- /dev/null +++ b/examples/kubernetes/storageclass/manifests/claim.yaml @@ -0,0 +1,11 @@ +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: ebs-claim +spec: + accessModes: + - ReadWriteOnce + storageClassName: ebs-sc + resources: + requests: + storage: 4Gi \ No newline at end of file diff --git a/examples/kubernetes/storageclass/manifests/pod.yaml b/examples/kubernetes/storageclass/manifests/pod.yaml new file mode 100644 index 0000000000..4a72260fb4 --- /dev/null +++ b/examples/kubernetes/storageclass/manifests/pod.yaml @@ -0,0 +1,17 @@ +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 + persistentVolumeClaim: + claimName: ebs-claim \ No newline at end of file diff --git a/examples/kubernetes/storageclass/manifests/storageclass.yaml b/examples/kubernetes/storageclass/manifests/storageclass.yaml new file mode 100644 index 0000000000..50cf0cd1cb --- /dev/null +++ b/examples/kubernetes/storageclass/manifests/storageclass.yaml @@ -0,0 +1,16 @@ +apiVersion: storage.k8s.io/v1 +kind: StorageClass +metadata: + name: ebs-sc +provisioner: ebs.csi.aws.com +volumeBindingMode: WaitForFirstConsumer +parameters: + csi.storage.k8s.io/fstype: xfs + type: io1 + iopsPerGB: "50" + encrypted: "true" +allowedTopologies: +- matchLabelExpressions: + - key: topology.ebs.csi.aws.com/zone + values: + - us-east-2c \ No newline at end of file diff --git a/examples/kubernetes/storageclass/specs/example.yaml b/examples/kubernetes/storageclass/specs/example.yaml deleted file mode 100644 index 7d4470f015..0000000000 --- a/examples/kubernetes/storageclass/specs/example.yaml +++ /dev/null @@ -1,46 +0,0 @@ -kind: StorageClass -apiVersion: storage.k8s.io/v1 -metadata: - name: ebs-sc -provisioner: ebs.csi.aws.com -volumeBindingMode: WaitForFirstConsumer -parameters: - csi.storage.k8s.io/fstype: xfs - type: io1 - iopsPerGB: "50" - encrypted: "true" -allowedTopologies: -- matchLabelExpressions: - - key: topology.ebs.csi.aws.com/zone - values: - - us-east-1a ---- -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: ebs-claim -spec: - accessModes: - - ReadWriteOnce - storageClassName: ebs-sc - resources: - requests: - storage: 4Gi ---- -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 - persistentVolumeClaim: - claimName: ebs-claim diff --git a/examples/kubernetes/windows/README.md b/examples/kubernetes/windows/README.md index f300176c15..9ee40e6ae4 100644 --- a/examples/kubernetes/windows/README.md +++ b/examples/kubernetes/windows/README.md @@ -2,7 +2,6 @@ This example shows how to create a EBS volume and consume it from a Windows container dynamically. - ## Prerequisites 1. A 1.18+ Windows node. Windows support has only been tested on 1.18 EKS Windows nodes. https://docs.aws.amazon.com/eks/latest/userguide/windows-support.html