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.
WARNING: The ALPHA driver is NOT compatible with Kubernetes versions <1.12.
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.
This driver is compatiable with CSI version v0.3.0.
Stable alpha image: amazon/aws-ebs-csi-driver:0.1.0-alpha
To check our current development efforts, visit our Milestones page.
-
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
set. -
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.
The file will look like this:
apiVersion: v1
kind: Secret
metadata:
name: aws-secret
stringData:
key_id: my_key_id
access_key: my_access_key
Now, with one command we will create the secret and deploy the sidecar containers and the CSI driver:
kubectl create -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 create -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.1+
- 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