From 2d5f5b1d09373236937849bd80580c5a6ddd312f Mon Sep 17 00:00:00 2001 From: Dimitri Koshkin Date: Tue, 5 Mar 2019 15:27:06 -0500 Subject: [PATCH] Cleanup README and examples --- docs/README.md | 6 +- .../kubernetes/pod-single-volume/README.md | 29 ++++++ .../specs}/claim.yaml | 0 .../specs}/pod.yaml | 0 .../specs}/storageclass.yaml | 0 examples/kubernetes/snapshot/README.md | 97 ++++++++++++------- .../specs/app}/claim.yaml | 0 .../specs/app}/pod.yaml | 0 .../{ => specs/classes}/snapshotclass.yaml | 2 +- .../specs/classes}/storageclass.yaml | 0 .../snapshot-restore/claim.yaml} | 4 +- .../snapshot/specs/snapshot-restore/pod.yaml | 17 ++++ .../{ => specs/snapshot}/snapshot.yaml | 2 +- 13 files changed, 114 insertions(+), 43 deletions(-) create mode 100644 examples/kubernetes/pod-single-volume/README.md rename examples/kubernetes/{snapshot => pod-single-volume/specs}/claim.yaml (100%) rename examples/kubernetes/{snapshot => pod-single-volume/specs}/pod.yaml (100%) rename examples/kubernetes/{snapshot => pod-single-volume/specs}/storageclass.yaml (100%) rename examples/kubernetes/{volume_scheduling => snapshot/specs/app}/claim.yaml (100%) rename examples/kubernetes/{volume_scheduling => snapshot/specs/app}/pod.yaml (100%) rename examples/kubernetes/snapshot/{ => specs/classes}/snapshotclass.yaml (80%) rename examples/kubernetes/{volume_scheduling => snapshot/specs/classes}/storageclass.yaml (100%) rename examples/kubernetes/snapshot/{restore-claim.yaml => specs/snapshot-restore/claim.yaml} (82%) create mode 100644 examples/kubernetes/snapshot/specs/snapshot-restore/pod.yaml rename examples/kubernetes/snapshot/{ => specs/snapshot}/snapshot.yaml (81%) diff --git a/docs/README.md b/docs/README.md index 0d85c7195b..a0bc185608 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,7 +61,7 @@ There are several optional parameters that could be passed into `CreateVolumeReq 2. Enable the flag `--allow-privileged=true` in the manifest entries of kubelet and kube-apiserver. -3. Add `--feature-gates=CSINodeInfo=true,CSIDriverRegistry=true,VolumeSnapshotDataSource=true` in the manifest entries of kubelet and kube-apiserver. This is required to enable topology support of EBS volumes in Kubernetes and restoring volumes from snapshots. +3. Add `--feature-gates=CSINodeInfo=true,CSIDriverRegistry=true,CSIBlockVolume=true,VolumeSnapshotDataSource=true` in the manifest entries for `kube-apiserver` and `--feature-gates=CSINodeInfo=true,CSIDriverRegistry=true,CSIBlockVolume=true` in the `kubelets`. This is required to enable topology support of EBS volumes in Kubernetes, using `volumeMode: Block` and restoring volumes from snapshots. 4. Install the `CSINodeInfo` CRD on the cluster using the instructions provided here: [Enabling CSINodeInfo](https://kubernetes-csi.github.io/docs/csi-node-info-object.html#enabling-csinodeinfo). @@ -95,10 +95,10 @@ kubectl apply -f deploy/kubernetes Now any user can start creating and using EBS volumes with the CSI driver. -6. Apply `examples/kubernetes/volume_scheduling` that uses the recently deployed driver: +6. Apply `examples/kubernetes/pod-single-volume` that uses the recently deployed driver: ``` -kubectl apply -f examples/kubernetes/volume_scheduling +kubectl apply -f examples/kubernetes/pod-single-volume ``` ## Development diff --git a/examples/kubernetes/pod-single-volume/README.md b/examples/kubernetes/pod-single-volume/README.md new file mode 100644 index 0000000000..f626ca07d6 --- /dev/null +++ b/examples/kubernetes/pod-single-volume/README.md @@ -0,0 +1,29 @@ +# Dynamic Volume Provisioning with AWS EBS CSI Driver + +## Prerequisites + +1. Kubernetes 1.13+ (CSI 1.0). + +1. The [aws-ebs-csi-driver driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) is installed. + +## Usage + +1. Create a sample app along with the StorageClass and the PersistentVolumeClaim: +``` +kubectl apply -f specs/ +``` + +2. Validate the volume was created and `volumeHandle` contains an EBS volumeID: +``` +kubectl describe pv +``` + +3. Validate the pod successfully wrote data to the volume: +``` +kubectl exec -it app cat /data/out.txt +``` + +4. Cleanup resources: +``` +kubectl delete -f specs/ +``` \ No newline at end of file diff --git a/examples/kubernetes/snapshot/claim.yaml b/examples/kubernetes/pod-single-volume/specs/claim.yaml similarity index 100% rename from examples/kubernetes/snapshot/claim.yaml rename to examples/kubernetes/pod-single-volume/specs/claim.yaml diff --git a/examples/kubernetes/snapshot/pod.yaml b/examples/kubernetes/pod-single-volume/specs/pod.yaml similarity index 100% rename from examples/kubernetes/snapshot/pod.yaml rename to examples/kubernetes/pod-single-volume/specs/pod.yaml diff --git a/examples/kubernetes/snapshot/storageclass.yaml b/examples/kubernetes/pod-single-volume/specs/storageclass.yaml similarity index 100% rename from examples/kubernetes/snapshot/storageclass.yaml rename to examples/kubernetes/pod-single-volume/specs/storageclass.yaml diff --git a/examples/kubernetes/snapshot/README.md b/examples/kubernetes/snapshot/README.md index 2a607999d3..c2693853ab 100644 --- a/examples/kubernetes/snapshot/README.md +++ b/examples/kubernetes/snapshot/README.md @@ -1,42 +1,67 @@ -# Volume Snapshots with AWS EBS CSI Driver +# Volume Snapshots ## Overview -This driver implements basic volume snapshotting functionality, i.e. it is possible to use it along with the [external -snapshotter](https://github.com/kubernetes-csi/external-snapshotter) sidecar and create snapshots of EBS volumes using -the `VolumeSnapshot` custom resources. +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) is required - -2. The `VolumeSnapshotDataSource` feature gate of Kubernetes API server and controller manager must be turned on. - -## Usage - -This directory contains example YAML files to test the feature. First, see the [deployment example](../../../deploy/kubernetes) and [volume scheduling example](../volume_scheduling) -to set up the external provisioner: - -### Set up - -1. Create the RBAC rules - -2. Start the contoller `StatefulSet` - -3. Start the node `DaemonSet` - -4. Create a `StorageClass` for dynamic provisioning of the AWS CSI volumes - -5. Create a `SnapshotClass` to create `VolumeSnapshot`s using the AWS CSI external controller - -6. Create a `PersistentVolumeClaim` and a pod using it - -### Taking and restoring volume snapshot - -7. Create a `VolumeSnapshot` referencing the `PersistentVolumeClaim`; the snapshot creation may take time to finish: - check the `ReadyToUse` attribute of the `VolumeSnapshot` object to find out when a new `PersistentVolume` can be - created from the snapshot - -8. To restore a volume from a snapshot use a `PersistentVolumeClaim` referencing the `VolumeSnapshot` in its `dataSource`; see the - [Kubernetes Persistent Volumes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#volume-snapshot-and-restore-volume-from-snapshot-support) - and the example [restore claim](./restore-claim.yaml) +1. Kubernetes 1.13+ (CSI 1.0). + +1. The `VolumeSnapshotDataSource` must be set in `--feature-gates=` in the `kube-apiserver`. + +1. The [aws-ebs-csi-driver driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver) is installed. + +### Usage + +1. Create the `StorageClass` and `VolumeSnapshotClass`: +``` +kubectl apply -f specs/classes/ +``` + +2. Create a sample app and the `PersistentVolumeClaim`: +``` +kubectl apply -f specs/app/ +``` + +3. Validate the volume was created and `volumeHandle` contains an EBS volumeID: +``` +kubectl describe pv +``` + +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 + ``` + +5. Create a `VolumeSnapshot` referencing the `PersistentVolumeClaim` name: +``` +kubectl apply -f specs/snapshot/ +``` + +6. Wait for the `Ready To Use: true` attribute of the `VolumeSnapshot`: +``` +kubectl describe volumesnapshot.snapshot.storage.k8s.io ebs-volume-snapshot +``` + +7. Delete the existing app: +``` +kubectl delete -f specs/app/ +``` + +8. Restore a volume from the snapshot with a `PersistentVolumeClaim` referencing the `VolumeSnapshot` in its `dataSource`: +``` +kubectl apply -f specs/snapshot-restore/ +``` + +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 +``` + +10. Cleanup resources: + ``` + kubectl delete -f specs/snapshot-restore + kubectl delete -f specs/snapshot + kubectl delete -f specs/classes + ``` \ No newline at end of file diff --git a/examples/kubernetes/volume_scheduling/claim.yaml b/examples/kubernetes/snapshot/specs/app/claim.yaml similarity index 100% rename from examples/kubernetes/volume_scheduling/claim.yaml rename to examples/kubernetes/snapshot/specs/app/claim.yaml diff --git a/examples/kubernetes/volume_scheduling/pod.yaml b/examples/kubernetes/snapshot/specs/app/pod.yaml similarity index 100% rename from examples/kubernetes/volume_scheduling/pod.yaml rename to examples/kubernetes/snapshot/specs/app/pod.yaml diff --git a/examples/kubernetes/snapshot/snapshotclass.yaml b/examples/kubernetes/snapshot/specs/classes/snapshotclass.yaml similarity index 80% rename from examples/kubernetes/snapshot/snapshotclass.yaml rename to examples/kubernetes/snapshot/specs/classes/snapshotclass.yaml index bc1220078f..259cb5d431 100644 --- a/examples/kubernetes/snapshot/snapshotclass.yaml +++ b/examples/kubernetes/snapshot/specs/classes/snapshotclass.yaml @@ -1,5 +1,5 @@ apiVersion: snapshot.storage.k8s.io/v1alpha1 kind: VolumeSnapshotClass metadata: - name: csi-aws-snapclass + name: csi-aws-vsc snapshotter: ebs.csi.aws.com diff --git a/examples/kubernetes/volume_scheduling/storageclass.yaml b/examples/kubernetes/snapshot/specs/classes/storageclass.yaml similarity index 100% rename from examples/kubernetes/volume_scheduling/storageclass.yaml rename to examples/kubernetes/snapshot/specs/classes/storageclass.yaml diff --git a/examples/kubernetes/snapshot/restore-claim.yaml b/examples/kubernetes/snapshot/specs/snapshot-restore/claim.yaml similarity index 82% rename from examples/kubernetes/snapshot/restore-claim.yaml rename to examples/kubernetes/snapshot/specs/snapshot-restore/claim.yaml index eba2c0646f..7780dc0ea1 100644 --- a/examples/kubernetes/snapshot/restore-claim.yaml +++ b/examples/kubernetes/snapshot/specs/snapshot-restore/claim.yaml @@ -1,14 +1,14 @@ apiVersion: v1 kind: PersistentVolumeClaim metadata: - name: ebs-restore-claim + name: ebs-snapshot-restored-claim spec: accessModes: - ReadWriteOnce storageClassName: ebs-sc resources: requests: - storage: 2Gi + storage: 4Gi dataSource: name: ebs-volume-snapshot kind: VolumeSnapshot diff --git a/examples/kubernetes/snapshot/specs/snapshot-restore/pod.yaml b/examples/kubernetes/snapshot/specs/snapshot-restore/pod.yaml new file mode 100644 index 0000000000..42a6852dbb --- /dev/null +++ b/examples/kubernetes/snapshot/specs/snapshot-restore/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-snapshot-restored-claim diff --git a/examples/kubernetes/snapshot/snapshot.yaml b/examples/kubernetes/snapshot/specs/snapshot/snapshot.yaml similarity index 81% rename from examples/kubernetes/snapshot/snapshot.yaml rename to examples/kubernetes/snapshot/specs/snapshot/snapshot.yaml index 69bf3ef2f4..6df3747916 100644 --- a/examples/kubernetes/snapshot/snapshot.yaml +++ b/examples/kubernetes/snapshot/specs/snapshot/snapshot.yaml @@ -3,7 +3,7 @@ kind: VolumeSnapshot metadata: name: ebs-volume-snapshot spec: - snapshotClassName: csi-aws-snapclass + snapshotClassName: csi-aws-vsc source: name: ebs-claim kind: PersistentVolumeClaim