WARNING: This driver is in ALPHA currently. This means that there may be potentially backwards compatibility breaking changes moving forward. Do NOT use this driver in a production environment in its current state.
DISCLAIMER: This is not an officially supported Amazon product
The Amazon Elastic Block Store CSI Driver provides a CSI interface used by Container Orchestrators to manage the lifecycle of EBS volumes.
This driver is in alpha stage and basic volume operations are already working including CreateVolume/DeleteVolume, ControllerPublishVolume/ControllerUnpublishVolume, NodeStageVolume/NodeUnstageVolume, NodePublishVolume/NodeUnpublishVolume and Volume Scheduling.
| AWS EBS CSI Driver Version | Image |
|---|---|
| v0.1.0 | amazon/aws-ebs-csi-driver:0.1.0-alpha |
| master branch | amazon/aws-ebs-csi-driver:latest |
| AWS EBS CSI Driver \ CSI Version | v0.3.0 | v1.0.0 |
|---|---|---|
| v0.1.0 | yes | no |
| master branch | no | yes |
| AWS EBS CSI Driver \ Kubernetes Version | v1.12 | v1.13 |
|---|---|---|
| v0.1.0 | yes | yes |
| master branch | no | yes |
-
Kubernetes 1.12+ is required. Although this driver should work with any other container orchestration system that implements the CSI specification, so far it has only been tested in Kubernetes.
-
Kube-apiserver and kubelet should run with the flag
--allow-privileged=trueset. -
For general CSI driver setup on kubernetes, please refer to kubernetes CSI docs.
The list of supported driver capabilities:
- Identity Service: CONTROLLER_SERVICE and ACCESSIBILITY_CONSTRAINTS
- Controller Service: CREATE_DELETE_VOLUME and PUBLISH_UNPUBLISH_VOLUME
- Node Service: STAGE_UNSTAGE_VOLUME
There are several optional parameters that could be passed into CreateVolumeRequest.parameters map:
| Parameters | Values | Default | Description |
|---|---|---|---|
| "type" | io1, gp2, sc1, st1 | gp2 | EBS volume type |
| "iopsPerGB" | I/O operations per second per GiB. Required when io1 volume type is specified | ||
| "fsType" | ext2, ext3, ext4 | ext4 | File system type that will be formatted during volume creation |
| "encrypted" | Whether the volume should be encrypted or not. Valid values are "true" or "false" | ||
| "kmsKeyId" | The full ARN of the key to use when encrypting the volume. When not specified, the default KMS key is used |
topology.ebs.csi.aws.com/zone is the only topology key that represents the availability zone of which a volume is accessible.
To enable topology support on kuberetes, make sure CSINodeInfo and CSIDriverRegistry feature flags are enabled on both kubelet and kube-apiserver and CSINodeInfo CRD is installed on the cluster following Enabling CSINodeInfo.
And external-provisioner must have the togology feature gate enabled with --feature-gates=CSINodeInfo=true
Under the directory deploy/kubernetes, there are a few manifest files that are needed to deploy the CSI driver along with sidecar containers. If you are using Kubernetes v1.12, use the manifest files under deploy/kubernetes/v1.12; for kubernetes v1.10 and v1.11, use the files under deploy/kubernetes/v1.[10,11].
In this example we'll use Kubernetes v1.12. First of all, edit the deploy/kubernetes/v1.12/secrets.yaml file and add AWS credentials of the IAM user. It's a best practice to only grant required permission to the driver. A sample IAM policy can be found in example-iam-policy.json.
The file will look like this:
apiVersion: v1
kind: Secret
metadata:
name: aws-secret
stringData:
key_id: [aws_access_key_id]
access_key: [aws_secret_access_key]
Now, with one command we will create the secret and deploy the sidecar containers and the CSI driver:
kubectl apply -f deploy/kubernetes/v1.12
From now on we can start creating EBS volumes using the CSI driver. Under deploy/kubernetes/v1.12/sample_app you will find a sample app deployment that uses the recently deployed driver:
kubectl apply -f deploy/kubernetes/v1.12/sample_app
Please go through CSI Spec and General CSI driver development guideline to get some basic understanding of CSI driver before you start.
- Golang 1.11.2+
- Ginkgo for integration and end-to-end testing
- Docker 17.05+ for releasing
In order to make sure that the driver complies with the CSI specification, run the command:
make test-sanity
To execute all unit tests, run:
make test
To execute integration tests, run:
make test-integration
Note: EC2 instance is required to run integration test, since it is exercising the actual flow of creating EBS volume, attaching it and read/write on the disk.
Build and publish container image of the driver is as simple as building the image and pushing it to the container registry with the command:
make image && make push