Amazon EFS CSI Driver

The Amazon EFS CSI Driver enables Kubernetes clusters running on AWS to mount both Amazon EFS and Amazon S3 file systems (starting from driver version 3.0.0 or above) as persistent volumes.

Key capabilities include:

• Dynamic Provisioning: Automatically creates an EFS or S3 access point when a Persistent Volume Claim (PVC) is created.
• Static Provisioning: Allows mounting existing, manually created EFS or S3 file systems.
• Encryption: Supports encryption in transit by default (in the master branch).
• Cross-account mounting: Supports mounting EFS file systems from different AWS accounts.
• Multiarch support: The driver image is available as a multiarch image on ECR.

Important Notes:

• Capacity Placeholders: Since EFS and S3 are fully elastic, the storage capacity specified in PersistentVolumes (PV) and PersistentVolumeClaims (PVC) is a required Kubernetes placeholder and does not affect actual scaling or billing.
• Avoid Node-level Installation: Do not install amazon-efs-utils directly on EKS worker nodes. The driver packages efs-utils within its own containers and manages the mount process. Installing it at the node level can cause unexpected behavior.

The impact of an Availability Zone (AZ) outage depends on your provisioning mode:

1. DNS mode (crossaccount=true in the secret): Nodes resolve mount targets via DNS at mount time. Pods in healthy AZs continue working; pods in the failed AZ lose connectivity until rescheduled.
2. Default per-node AZ selection (no az or crossaccount specified): The controller resolves all mount targets at provisioning. Nodes select their own AZ's mount target. If a node's AZ has no mount target, it falls back to an available one (logged as a warning). Pods in healthy AZs continue working.
3. Pinned AZ (StorageClass az=<zone>): Every pod is forced to use the mount target in the specified zone. If that AZ goes down, all pods using that StorageClass lose connectivity.

Note: If using an older driver version that baked a single IP into PVs, upgrade to v3.1.0 or newer to enable the default per-node AZ selection feature.

The driver determines how to mount an EFS file system based on the combination of the provisioner secret and the StorageClass configuration. This selection logic dictates whether the driver uses DNS resolution, a specific IP, or automatic AZ-aware selection.

Note: For static provisioning, you must explicitly set crossaccount: "true" or mounttargetip: <ip> in the PV's volumeAttributes to control this behavior.

The EFS CSI driver can automatically resolve EFS filesystem IDs from Kubernetes ConfigMaps or Secrets. This is useful when external tools provision EFS filesystems and store the resulting IDs in Kubernetes resources.

To use this feature, you must provide a reference in the StorageClass parameters using the format: namespace/name/key.

Parameter Constraints: You must specify exactly one of the following in your StorageClass parameters:

• fileSystemId: The raw filesystem ID string.
• fileSystemIdConfigRef: A reference to a ConfigMap in the format namespace/name/key.
• fileSystemIdSecretRef: A reference to a Secret in the format namespace/name/key.

# Example: Using a ConfigMap to provide the filesystem ID
apiVersion: v1
kind: ConfigMap
metadata:
  name: efs-config
  namespace: kube-system
data:
  fileSystemId: fs-02604354c13d0316d
---
kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: efs-sc
provisioner: efs.csi.aws.com
parameters:
  provisioningMode: efs-ap
  fileSystemIdConfigRef: "kube-system/efs-config/fileSystemId"
  directoryPerms: "700"

Dynamic provisioning automates the creation of EFS Access Points when a user requests storage via a StorageClass and PVC. The driver manages the entire lifecycle from creation to deletion.

Workflow Phases:

1. Provisioning Phase

• Trigger: User creates a StorageClass and a PVC.
• Action: The csi-provisioner detects the PVC and calls the CreateVolume RPC on the Controller.
• EFS Creation: The Controller parses parameters (like UID/GID) from the StorageClass, calls the EFS CreateAccessPoint API, and generates a VolumeId in the format fileSystemId::accessPointId.
• K8s Binding: The driver creates a PV object with the generated VolumeId, which is then bound to the PVC.

2. Node Publish Phase

• Trigger: Kubelet schedules a Pod to a node.
• Action: Kubelet calls the NodePublishVolume RPC on the Node Service.
• Mounting: The Node Service extracts the fileSystemId and accessPointId from the VolumeId and uses efs-utils to mount the filesystem (using the access point and TLS options) at the target path.

3. Deletion Phase

• Trigger: User deletes the PVC.
• Action: The csi-provisioner calls the DeleteVolume RPC on the Controller.
• Cleanup: The Controller parses the accessPointId. If deleteAccessPointRootDir is enabled, it temporarily mounts the filesystem to delete the root directory and its contents before calling the EFS DeleteAccessPoint API and deleting the PV.