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

Amazon Elastic Block Store CSI driver

Overview

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.

Requirements

Kubernetes

• 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.

Features

Capabilities

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

CreateVolume Parameters

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

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 using:

kubectl create -f https://raw.githubusercontent.com/kubernetes/csi-api/master/pkg/crd/testdata/csinodeinfo.yaml --validate=false

And external-provisioner must have the togology feature gate enabled with --feature-gates=CSINodeInfo=true

Installation

Kubernetes

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 your AWS credentials. 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/v.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/v.12+/sample_app

Development

Please go through CSI Spec and General CSI driver development guideline to get some basic understanding of CSI driver before you start.

Requirements

• Golang 1.11.1+
• Ginkgo for integration and end-to-end testing
• Docker 17.05+ for releasing

Testing

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

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