The Amazon Elastic File System Container Storage Interface (CSI) Driver implements the CSI specification for container orchestrators to manage the lifecycle of Amazon EFS file systems.
| AWS EFS CSI Driver \ CSI Spec Version | v0.3.0 | v1.1.0 | v1.2.0 |
|---|---|---|---|
| master branch | no | no | yes |
| v1.x.x | no | no | yes |
| v0.3.0 | no | yes | no |
| v0.2.0 | no | yes | no |
| v0.1.0 | yes | no | no |
EFS CSI driver supports dynamic provisioning and static provisioning. Currently Dynamic Provisioning creates an access point for each PV. This mean an AWS EFS file system has to be created manually on AWS first and should be provided as an input to the storage class parameter. For static provisioning, AWS EFS file system needs to be created manually on AWS first. After that it can be mounted inside a container as a volume using the driver.
The following CSI interfaces are implemented:
- Controller Service: CreateVolume, DeleteVolume, ControllerGetCapabilities, ValidateVolumeCapabilities
- Node Service: NodePublishVolume, NodeUnpublishVolume, NodeGetCapabilities, NodeGetInfo, NodeGetId, NodeGetVolumeStats
- Identity Service: GetPluginInfo, GetPluginCapabilities, Probe
| Parameters | Values | Default | Optional | Description |
|---|---|---|---|---|
| provisioningMode | efs-ap | false | Type of volume provisioned by efs. Currently, Access Points are supported. | |
| fileSystemId | false | File System under which access points are created. | ||
| directoryPerms | false | Directory permissions for Access Point root directory creation. | ||
| uid | true | POSIX user Id to be applied for Access Point root directory creation and for user identity enforcement. | ||
| gid | true | POSIX group Id to be applied for Access Point root directory creation and for user identity enforcement. | ||
| gidRangeStart | 50000 | true | Start range of the POSIX group Id to be applied for Access Point root directory creation and for user identity enforcement. Not used if uid/gid is set. For user identity enforcement, this value will be applied as both the uid and the gid. | |
| gidRangeEnd | 7000000 | true | End range of the POSIX group Id. Not used if uid/gid is set. | |
| basePath | true | Path under which access points for dynamic provisioning is created. If this parameter is not specified, access points are created under the root directory of the file system | ||
| az | "" | true | Used for cross-account mount. az under storage class parameter is optional. If specified, mount target associated with the az will be used for cross-account mount. If not specified, a random mount target will be picked for cross account mount |
Notes:
- Custom Posix group Id range for Access Point root directory must include both
gidRangeStartandgidRangeEndparameters. These parameters are optional only if both are omitted. If you specify one, the other becomes mandatory. - When using a custom Posix group ID range, there is a possibility for the driver to run out of available POSIX group Ids. We suggest ensuring custom group ID range is large enough or create a new storage class with a new file system to provision additional volumes.
azunder storage class parameter is not be confused with efs-utils mount optionaz. Theazmount option is used for cross-az mount or efs one zone file system mount within the same aws account as the cluster.- Using dynamic provisioning, user identity enforcement is always applied.
- When user enforcement is enabled, Amazon EFS replaces the NFS client's user and group IDs with the identity configured on the access point for all file system operations.
- The uid/gid configured on the access point is either the uid/gid specified in the storage class, a value in the gidRangeStart-gidRangeEnd (used as both uid/gid) specified in the storage class, or is a value selected by the driver is no uid/gid or gidRange is specified.
- We suggest using static provisioning if you do not wish to use user identity enforcement.
Note
If you want to pass any other mountOptions to EFS CSI driver while mounting, they can be passed in through the Persistent Volume or the Storage Class objects, depending on whether static or dynamic provisioning is used. Examples of some mountOptions that can be passed:
lookupcache: Specifies how the kernel manages its cache of directory entries for a given mount point. Mode can be one of all, none, pos, or positive. Each mode has different functions and for more information you can refer to this link.
iam: Use the CSI Node Pod's IAM identity to authenticate with EFS.
One of the advantages of using EFS is that it provides encryption in transit support using TLS. Using encryption in transit, data will be encrypted during its transition over the network to the EFS service. This provides an extra layer of defence-in-depth for applications that requires strict security compliance.
Encryption in transit is enabled by default in the master branch version of the driver. To disable it and mount volumes using plain NFSv4, set volumeAttributes field encryptInTransit to "false" in your persistent volume manifest. For an example manifest, see Encryption in Transit Example.
Note Kubernetes version 1.13+ is required if you are using this feature in Kubernetes.
The following sections are Kubernetes specific. If you are a Kubernetes user, use this for driver features, installation steps and examples.
| AWS EFS CSI Driver \ Kubernetes Version | maturity | v1.11 | v1.12 | v1.13 | v1.14 | v1.15 | v1.16 | v1.17+ |
|---|---|---|---|---|---|---|---|---|
| master branch | GA | no | no | no | no | no | no | yes |
| v1.5.x | GA | no | no | no | no | no | no | yes |
| v1.4.x | GA | no | no | no | no | no | no | yes |
| v1.3.x | GA | no | no | no | no | no | no | yes |
| v1.2.x | GA | no | no | no | no | no | no | yes |
| v1.1.x | GA | no | no | no | yes | yes | yes | yes |
| v1.0.x | GA | no | no | no | yes | yes | yes | yes |
| v0.3.0 | beta | no | no | no | yes | yes | yes | yes |
| v0.2.0 | beta | no | no | no | yes | yes | yes | yes |
| v0.1.0 | alpha | yes | yes | yes | no | no | no | no |
| EFS CSI Driver Version | Image |
|---|---|
| master branch | amazon/aws-efs-csi-driver:master |
| v1.5.7 | amazon/aws-efs-csi-driver:v1.5.7 |
| v1.5.6 | amazon/aws-efs-csi-driver:v1.5.6 |
| v1.5.5 | amazon/aws-efs-csi-driver:v1.5.5 |
| v1.5.4 | amazon/aws-efs-csi-driver:v1.5.4 |
| v1.5.3 | amazon/aws-efs-csi-driver:v1.5.3 |
| v1.5.2 | amazon/aws-efs-csi-driver:v1.5.2 |
| v1.5.1 | amazon/aws-efs-csi-driver:v1.5.1 |
| v1.5.0 | amazon/aws-efs-csi-driver:v1.5.0 |
| v1.4.9 | amazon/aws-efs-csi-driver:v1.4.9 |
| v1.4.8 | amazon/aws-efs-csi-driver:v1.4.8 |
| v1.4.7 | amazon/aws-efs-csi-driver:v1.4.7 |
| v1.4.6 | amazon/aws-efs-csi-driver:v1.4.6 |
| v1.4.5 | amazon/aws-efs-csi-driver:v1.4.5 |
| v1.4.4 | amazon/aws-efs-csi-driver:v1.4.4 |
| v1.4.3 | amazon/aws-efs-csi-driver:v1.4.3 |
| v1.4.2 | amazon/aws-efs-csi-driver:v1.4.2 |
| v1.4.1 | amazon/aws-efs-csi-driver:v1.4.1 |
| v1.4.0 | amazon/aws-efs-csi-driver:v1.4.0 |
| v1.3.8 | amazon/aws-efs-csi-driver:v1.3.8 |
| v1.3.7 | amazon/aws-efs-csi-driver:v1.3.7 |
| v1.3.6 | amazon/aws-efs-csi-driver:v1.3.6 |
| v1.3.5 | amazon/aws-efs-csi-driver:v1.3.5 |
| v1.3.4 | amazon/aws-efs-csi-driver:v1.3.4 |
| v1.3.3 | amazon/aws-efs-csi-driver:v1.3.3 |
| v1.3.2 | amazon/aws-efs-csi-driver:v1.3.2 |
| v1.3.1 | amazon/aws-efs-csi-driver:v1.3.1 |
| v1.3.0 | amazon/aws-efs-csi-driver:v1.3.0 |
| v1.2.1 | amazon/aws-efs-csi-driver:v1.2.1 |
| v1.2.0 | amazon/aws-efs-csi-driver:v1.2.0 |
| v1.1.1 | amazon/aws-efs-csi-driver:v1.1.1 |
| v1.1.0 | amazon/aws-efs-csi-driver:v1.1.0 |
| v1.0.0 | amazon/aws-efs-csi-driver:v1.0.0 |
| v0.3.0 | amazon/aws-efs-csi-driver:v0.3.0 |
| v0.2.0 | amazon/aws-efs-csi-driver:v0.2.0 |
| v0.1.0 | amazon/aws-efs-csi-driver:v0.1.0 |
| Driver Version | ECR Image |
|---|---|
| v1.5.0 | public.ecr.aws/efs-csi-driver/amazon/aws-efs-csi-driver:v1.5.0 |
Note : You can find previous efs-csi-driver versions' images from here
- Static provisioning - EFS file system needs to be created manually first, then it could be mounted inside container as a persistent volume (PV) using the driver.
- Dynamic provisioning - Uses a persistent volume claim (PVC) to dynamically provision a persistent volume (PV). On Creating a PVC, kuberenetes requests EFS to create an Access Point in a file system which will be used to mount the PV.
- Mount Options - Mount options can be specified in the persistent volume (PV) or storage class for dynamic provisioning to define how the volume should be mounted.
- Encryption of data in transit - EFS file systems are mounted with encryption in transit enabled by default in the master branch version of the driver.
- Cross account mount - EFS file systems from different aws accounts can be mounted from an EKS cluster.
- Multiarch - EFS CSI driver image is now multiarch on ECR
Notes:
- Since EFS is an elastic file system it doesn't really enforce any file system capacity. The actual storage capacity value in persistent volume and persistent volume claim is not used when creating the file system. However, since the storage capacity is a required field by Kubernetes, you must specify the value and you can use any valid value for the capacity.
The driver requires IAM permission to talk to Amazon EFS to manage the volume on user's behalf. There are several methods to grant driver IAM permission:
- Using IAM Role for Service Account (Recommended if you're using EKS): create an IAM Role for service accounts with the required permissions. Uncomment annotations and put the IAM role ARN in service-account manifest
- Using IAM instance profile - grant all the worker nodes with required permissions by attaching policy to the instance profile of the worker.
If you want to deploy the stable driver:
kubectl apply -k "github.com/kubernetes-sigs/aws-efs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.5"If you want to deploy the development driver:
kubectl apply -k "github.com/kubernetes-sigs/aws-efs-csi-driver/deploy/kubernetes/overlays/dev/?ref=master"Alternatively, you could also install the driver using helm:
helm repo add aws-efs-csi-driver https://kubernetes-sigs.github.io/aws-efs-csi-driver/
helm repo update
helm upgrade --install aws-efs-csi-driver --namespace kube-system aws-efs-csi-driver/aws-efs-csi-driverTo force the efs-csi-driver to use FIPS, you can add an argument to the helm upgrade command:
helm upgrade --install aws-efs-csi-driver --namespace kube-system aws-efs-csi-driver/aws-efs-csi-driver --set useFips=true
Notes:
hostNetwork: true(should be added under spec/deployment on kubernetes installations where AWS metadata is not reachable from pod network. To fix the following errorNoCredentialProviders: no valid providers in chainthis parameter should be added.)
| Parameters | Values | Default | Optional | Description |
|---|---|---|---|---|
| vol-metrics-opt-in | false | true | Opt in to emit volume metrics. | |
| vol-metrics-refresh-period | 240 | true | Refresh period for volume metrics in minutes. | |
| vol-metrics-fs-rate-limit | 5 | true | Volume metrics routines rate limiter per file system. | |
| tags | true | Space separated key:value pairs which will be added as tags for EFS resources. For example, '--tags=name:efs-tag-test date:Jan24' |
| Parameters | Values | Default | Optional | Description |
|---|---|---|---|---|
| delete-access-point-root-dir | false | true | Opt in to delete access point root directory by DeleteVolume. By default, DeleteVolume will delete the access point behind Persistent Volume and deleting access point will not delete the access point root directory or its contents. |
If you want to update to latest released version:
kubectl apply -k "github.com/kubernetes-sigs/aws-efs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.5"If you want to update to a specific version, first customize the driver yaml file locally:
kubectl kustomize "github.com/kubernetes-sigs/aws-efs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.5" > driver.yamlThen, update all lines referencing image: amazon/aws-efs-csi-driver to the desired version (e.g., to image: amazon/aws-efs-csi-driver:v1.5.0) in the yaml file, and deploy driver yaml again:
kubectl apply -f driver.yamlBefore the example, you need to:
- Get yourself familiar with how to setup Kubernetes on AWS and how to create EFS file system.
- When creating EFS file system, make sure it is accessible from Kubernetes cluster. This can be achieved by creating the file system inside the same VPC as Kubernetes cluster or using VPC peering.
- Install EFS CSI driver following the Installation steps.
- Static provisioning
- Dynamic provisioning
- Encryption in transit
- Accessing the file system from multiple pods
- Consume EFS in StatefulSets
- Mount subpath
- Use Access Points
- EFS CSI driver supports using botocore to retrieve mount target ip address when dns name cannot be resolved, e.g., when user is mounting a file system in another VPC, botocore comes preinstalled on efs-csi-driver which can solve this DNS issue.
- IAM policy prerequisites to use this feature :
Allowelasticfilesystem:DescribeMountTargetsandec2:DescribeAvailabilityZonesactions in your policy attached to the EKS service account role, refer to example policy here.
-
Please go through CSI Spec and Kubernetes CSI Developer Documentation to get some basic understanding of CSI driver before you start.
-
If you are about to update iam policy file, please also update efs policy in weaveworks/eksctl https://github.com/weaveworks/eksctl/blob/main/pkg/cfn/builder/statement.go */
- Golang 1.13.4+
Dependencies are managed through go module. To build the project, first turn on go mod using export GO111MODULE=on, to build the project run: make
To execute all unit tests, run: make test
To pull logs and troubleshoot the driver, see troubleshooting/README.md.
This library is licensed under the Apache 2.0 License.