From 6f2416850bbb62a2b2067f027550441fd98a3d90 Mon Sep 17 00:00:00 2001 From: Dev Lakhia Date: Mon, 4 Dec 2023 21:34:38 +0000 Subject: [PATCH 1/4] Adding docs for S3 Express use case --- docs/install.md | 3 + .../kubernetes/static_provisioning/README.md | 3 +- .../s3_express_specify_az.yaml | 57 +++++++++++++++++++ .../static_provisioning.yaml | 2 +- 4 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 examples/kubernetes/static_provisioning/s3_express_specify_az.yaml diff --git a/docs/install.md b/docs/install.md index 23e14c84..3dc74a12 100644 --- a/docs/install.md +++ b/docs/install.md @@ -115,6 +115,9 @@ Review the [configuration values](https://github.com/awslabs/mountpoint-s3-csi-d kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-mountpoint-s3-csi-driver ``` +### Driver example +Follow the [README for examples](https://github.com/awslabs/mountpoint-s3-csi-driver/tree/main/examples/kubernetes/static_provisioning) on using the driver. + ### Uninstalling the driver Uninstall the self-managed Mountpoint for Amazon S3 CSI Driver with either Helm or Kustomize, depending on your installation method. If you are using the driver as an EKS add-on, see the [EKS documentation](https://docs.aws.amazon.com/eks/latest/userguide/managing-add-ons.html). diff --git a/examples/kubernetes/static_provisioning/README.md b/examples/kubernetes/static_provisioning/README.md index e8e201d1..e613a496 100644 --- a/examples/kubernetes/static_provisioning/README.md +++ b/examples/kubernetes/static_provisioning/README.md @@ -4,10 +4,11 @@ This example shows how to make a static provisioned Mountpoint for S3 persistent ## Examples in this folder - `static_provisioning.yaml` - spawning a pod which creates a file with name as the current date/time - `non_root.yaml` - same as above, but the pod is spawned as non-root (uid `1000`, gid `2000`) +- `s3_express_specify_az.yaml` - same as above, but this uses [S3 Express](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html) bucket and shows how to specify the availability zone (AZ) of the [pod assignment](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) ## Configure ### Edit [Persistent Volume](https://github.com/awslabs/mountpoint-s3-csi-driver/blob/main/examples/kubernetes/static_provisioning/static_provisioning.yaml) -> Note: This example assumes your S3 bucket has already been created. If you need to create a bucket, follow the [S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html). +> Note: This example assumes your S3 bucket has already been created. If you need to create a bucket, follow the [S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) for a regular bucket and [S3 One Zone documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-bucket-create.html) for an S3 Express bucket (aka a Directory bucket). - Bucket name (required): `PersistentVolume -> csi -> volumeAttributes -> bucketName` - Bucket region (if bucket and cluster are in different regions): `PersistentVolume -> csi -> mountOptions` - [Mountpoint configurations](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md) can be added in the `mountOptions` of the Persistent Volume spec. diff --git a/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml b/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml new file mode 100644 index 00000000..5ff77179 --- /dev/null +++ b/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml @@ -0,0 +1,57 @@ +apiVersion: v1 +kind: PersistentVolume +metadata: + name: s3-pv +spec: + capacity: + storage: 1200Gi # ignored, required + accessModes: + - ReadWriteMany # supported options: ReadWriteMany / ReadOnlyMany + mountOptions: + - allow-delete + - region us-west-2 + csi: + driver: s3.csi.aws.com # required + volumeHandle: s3-csi-driver-volume + volumeAttributes: + bucketName: s3-csi-driver--usw2-az1--x-s3 +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: s3-claim +spec: + accessModes: + - ReadWriteMany # supported options: ReadWriteMany / ReadOnlyMany + storageClassName: "" # required for static provisioning + resources: + requests: + storage: 1200Gi # ignored, required + volumeName: s3-pv +--- +apiVersion: v1 +kind: Pod +metadata: + name: s3-app +spec: + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: topology.kubernetes.io/zone + operator: In + values: + - us-west-2a # specify az where bucket lives + containers: + - name: app + image: centos + command: ["/bin/sh"] + args: ["-c", "echo 'Hello from the container!' >> /data/$(date -u).txt; tail -f /dev/null"] + volumeMounts: + - name: persistent-storage + mountPath: /data + volumes: + - name: persistent-storage + persistentVolumeClaim: + claimName: s3-claim diff --git a/examples/kubernetes/static_provisioning/static_provisioning.yaml b/examples/kubernetes/static_provisioning/static_provisioning.yaml index c1d298a3..c8d501ee 100644 --- a/examples/kubernetes/static_provisioning/static_provisioning.yaml +++ b/examples/kubernetes/static_provisioning/static_provisioning.yaml @@ -9,7 +9,7 @@ spec: - ReadWriteMany # supported options: ReadWriteMany / ReadOnlyMany mountOptions: - allow-delete - - region eu-west-1 + - region us-west-2 csi: driver: s3.csi.aws.com # required volumeHandle: s3-csi-driver-volume From 57bab39b7b6819f6a863711744bff2ce2d40cc86 Mon Sep 17 00:00:00 2001 From: Dev Lakhia <144840981+dlakhaws@users.noreply.github.com> Date: Tue, 5 Dec 2023 07:46:53 -0500 Subject: [PATCH 2/4] Update examples/kubernetes/static_provisioning/README.md Co-authored-by: James Bornholt --- examples/kubernetes/static_provisioning/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/kubernetes/static_provisioning/README.md b/examples/kubernetes/static_provisioning/README.md index e613a496..e169d023 100644 --- a/examples/kubernetes/static_provisioning/README.md +++ b/examples/kubernetes/static_provisioning/README.md @@ -4,7 +4,7 @@ This example shows how to make a static provisioned Mountpoint for S3 persistent ## Examples in this folder - `static_provisioning.yaml` - spawning a pod which creates a file with name as the current date/time - `non_root.yaml` - same as above, but the pod is spawned as non-root (uid `1000`, gid `2000`) -- `s3_express_specify_az.yaml` - same as above, but this uses [S3 Express](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html) bucket and shows how to specify the availability zone (AZ) of the [pod assignment](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) +- `s3_express_specify_az.yaml` - same as above, but this uses a [S3 Express One Zone](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html) directory bucket and shows how to specify the availability zone (AZ) of the [pod assignment](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) to co-locate the pod with the bucket for lower latency access ## Configure ### Edit [Persistent Volume](https://github.com/awslabs/mountpoint-s3-csi-driver/blob/main/examples/kubernetes/static_provisioning/static_provisioning.yaml) From 473ab0db8c6b962a735b888c5105e7c186800818 Mon Sep 17 00:00:00 2001 From: Dev Lakhia <144840981+dlakhaws@users.noreply.github.com> Date: Tue, 5 Dec 2023 07:47:24 -0500 Subject: [PATCH 3/4] Update examples/kubernetes/static_provisioning/README.md Co-authored-by: James Bornholt --- examples/kubernetes/static_provisioning/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/kubernetes/static_provisioning/README.md b/examples/kubernetes/static_provisioning/README.md index e169d023..a82172e7 100644 --- a/examples/kubernetes/static_provisioning/README.md +++ b/examples/kubernetes/static_provisioning/README.md @@ -8,7 +8,7 @@ This example shows how to make a static provisioned Mountpoint for S3 persistent ## Configure ### Edit [Persistent Volume](https://github.com/awslabs/mountpoint-s3-csi-driver/blob/main/examples/kubernetes/static_provisioning/static_provisioning.yaml) -> Note: This example assumes your S3 bucket has already been created. If you need to create a bucket, follow the [S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) for a regular bucket and [S3 One Zone documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-bucket-create.html) for an S3 Express bucket (aka a Directory bucket). +> Note: This example assumes your S3 bucket has already been created. If you need to create a bucket, follow the [S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) for a general purpose bucket or the [S3 Express One Zone documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-bucket-create.html) for a directory bucket. - Bucket name (required): `PersistentVolume -> csi -> volumeAttributes -> bucketName` - Bucket region (if bucket and cluster are in different regions): `PersistentVolume -> csi -> mountOptions` - [Mountpoint configurations](https://github.com/awslabs/mountpoint-s3/blob/main/doc/CONFIGURATION.md) can be added in the `mountOptions` of the Persistent Volume spec. From 46e08d93fb825d63588e2e5ba747f8b36776aad1 Mon Sep 17 00:00:00 2001 From: Dev Lakhia Date: Tue, 5 Dec 2023 13:08:33 +0000 Subject: [PATCH 4/4] PR feedback --- docs/install.md | 2 +- examples/kubernetes/static_provisioning/README.md | 1 + .../kubernetes/static_provisioning/s3_express_specify_az.yaml | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/install.md b/docs/install.md index 3dc74a12..54fa15fb 100644 --- a/docs/install.md +++ b/docs/install.md @@ -115,7 +115,7 @@ Review the [configuration values](https://github.com/awslabs/mountpoint-s3-csi-d kubectl get pods -n kube-system -l app.kubernetes.io/name=aws-mountpoint-s3-csi-driver ``` -### Driver example +### Volume Configuration Example Follow the [README for examples](https://github.com/awslabs/mountpoint-s3-csi-driver/tree/main/examples/kubernetes/static_provisioning) on using the driver. ### Uninstalling the driver diff --git a/examples/kubernetes/static_provisioning/README.md b/examples/kubernetes/static_provisioning/README.md index a82172e7..4b75a7b7 100644 --- a/examples/kubernetes/static_provisioning/README.md +++ b/examples/kubernetes/static_provisioning/README.md @@ -5,6 +5,7 @@ This example shows how to make a static provisioned Mountpoint for S3 persistent - `static_provisioning.yaml` - spawning a pod which creates a file with name as the current date/time - `non_root.yaml` - same as above, but the pod is spawned as non-root (uid `1000`, gid `2000`) - `s3_express_specify_az.yaml` - same as above, but this uses a [S3 Express One Zone](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html) directory bucket and shows how to specify the availability zone (AZ) of the [pod assignment](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity) to co-locate the pod with the bucket for lower latency access + - Note: This example sets the node affinity to create the pod in an availability zone that matches that of one of the nodes. We have an [open issue](https://github.com/awslabs/mountpoint-s3-csi-driver/issues/93) to support topology to be able to schedule this pods using nodes that match the labels. ## Configure ### Edit [Persistent Volume](https://github.com/awslabs/mountpoint-s3-csi-driver/blob/main/examples/kubernetes/static_provisioning/static_provisioning.yaml) diff --git a/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml b/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml index 5ff77179..24d91ed6 100644 --- a/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml +++ b/examples/kubernetes/static_provisioning/s3_express_specify_az.yaml @@ -42,7 +42,7 @@ spec: - key: topology.kubernetes.io/zone operator: In values: - - us-west-2a # specify az where bucket lives + - us-west-2a # specify az where bucket lives, note: the code of the availability zone (https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) must be used here (the AZ ID won't work) containers: - name: app image: centos