Store an elastic file system with Amazon EFS

Amazon Elastic File System (Amazon EFS) provides serverless, fully elastic file storage so that you can share file data without provisioning or managing storage capacity and performance. The Amazon EFS Container Storage Interface (CSI) driver provides a CSI interface that allows Kubernetes clusters running on AWS to manage the lifecycle of Amazon EFS file systems. This topic shows you how to deploy the Amazon EFS CSI driver to your Amazon EKS cluster.

Considerations

• The Amazon EFS CSI driver isn't compatible with Windows-based container images.

• You can't use dynamic provisioning for persistent volumes with Fargate nodes, but you can use static provisioning.

• Dynamic provisioning requires 1.2 or later of the driver. You can use static provisioning for persistent volumes using version 1.1 of the driver on any supported Amazon EKS cluster version.

• Version 1.3.2 or later of this driver supports the Arm64 architecture, including Amazon EC2 Graviton-based instances.

• Version 1.4.2 or later of this driver supports using FIPS for mounting file systems.

• Take note of the resource quotas for Amazon EFS. For example, there's a quota of 1000 access points that can be created for each Amazon EFS file system. For more information, see Amazon EFS resource quotas that you cannot change.

• Starting in version 2.0.0, this driver switched from using stunnel to efs-proxy for TLS connections. When efs-proxy is used, it will open a number of threads equal to one plus the number of cores for the node it's running on.

Prerequisites

• An existing AWS Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or to create one, see Create an IAM OIDC provider for your cluster.

• Version 2.12.3 or later or version 1.27.160 or later of the AWS Command Line Interface (AWS CLI) installed and configured on your device or AWS CloudShell. To check your current version, use aws --version | cut -d / -f2 | cut -d ' ' -f1. Package managers such yum, apt-get, or Homebrew for macOS are often several versions behind the latest version of the AWS CLI. To install the latest version, see Installing, updating, and uninstalling the AWS CLI and Quick configuration with aws configure in the AWS Command Line Interface User Guide. The AWS CLI version that is installed in AWS CloudShell might also be several versions behind the latest version. To update it, see Installing AWS CLI to your home directory in the AWS CloudShell User Guide.

• The kubectl command line tool is installed on your device or AWS CloudShell. The version can be the same as or up to one minor version earlier or later than the Kubernetes version of your cluster. For example, if your cluster version is 1.30, you can use kubectl version 1.29, 1.30, or 1.31 with it. To install or upgrade kubectl, see Set up kubectl and eksctl.

Step 1: Create an IAM role

The Amazon EFS CSI driver requires IAM permissions to interact with your file system. Create an IAM role and attach the required AWS managed policy to it. You can use eksctl, the AWS Management Console, or the AWS CLI.

Note

The specific steps in this procedure are written for using the driver as an Amazon EKS add-on. For details on self-managed installations, see Set up driver permission on GitHub.

eksctl

To create your Amazon EFS CSI driver IAM role with eksctl

Run the following commands to create the IAM role. Replace my-cluster with your cluster name and AmazonEKS_EFS_CSI_DriverRole with the name for your role.

export cluster_name=my-cluster
export role_name=AmazonEKS_EFS_CSI_DriverRole
eksctl create iamserviceaccount \
    --name efs-csi-controller-sa \
    --namespace kube-system \
    --cluster $cluster_name \
    --role-name $role_name \
    --role-only \
    --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEFSCSIDriverPolicy \
    --approve
TRUST_POLICY=$(aws iam get-role --role-name $role_name --query 'Role.AssumeRolePolicyDocument' | \
    sed -e 's/efs-csi-controller-sa/efs-csi-*/' -e 's/StringEquals/StringLike/')
aws iam update-assume-role-policy --role-name $role_name --policy-document "$TRUST_POLICY"

AWS Management Console

To create your Amazon EFS CSI driver IAM role with the AWS Management Console

1. Open the IAM console at https://console.aws.amazon.com/iam/.

2. In the left navigation pane, choose Roles.

3. On the Roles page, choose Create role.

4. On the Select trusted entity page, do the following:

   1. In the Trusted entity type section, choose Web identity.

   2. For Identity provider, choose the OpenID Connect provider URL for your cluster (as shown under Overview in Amazon EKS).

   3. For Audience, choose sts.amazonaws.com.

   4. Choose Next.

5. On the Add permissions page, do the following:

   1. In the Filter policies box, enter AmazonEFSCSIDriverPolicy.

   2. Select the check box to the left of the AmazonEFSCSIDriverPolicy returned in the search.

   3. Choose Next.

6. On the Name, review, and create page, do the following:

   1. For Role name, enter a unique name for your role, such as AmazonEKS_EFS_CSI_DriverRole.

   2. Under Add tags (Optional), add metadata to the role by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM resources in the IAM User Guide.

   3. Choose Create role.

7. After the role is created, choose the role in the console to open it for editing.

8. Choose the Trust relationships tab, and then choose Edit trust policy.

9. Find the line that looks similar to the following line:

   "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"

   Add the following line above the previous line. Replace region-code with the AWS Region that your cluster is in. Replace EXAMPLED539D4633E53DE1B71EXAMPLE with your cluster's OIDC provider ID.

   "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:efs-csi-*",
   

10. Modify the Condition operator from "StringEquals" to "StringLike".

11. Choose Update policy to finish.

AWS CLI

To create your Amazon EFS CSI driver IAM role with the AWS CLI

1. View your cluster's OIDC provider URL. Replace my-cluster with your cluster name. If the output from the command is None, review the Prerequisites.

   aws eks describe-cluster --name my-cluster --query "cluster.identity.oidc.issuer" --output text
   

   An example output is as follows.

   https://oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE

2. Create the IAM role that grants the AssumeRoleWithWebIdentity action.

   1. Copy the following contents to a file named aws-efs-csi-driver-trust-policy.json. Replace 111122223333 with your account ID. Replace EXAMPLED539D4633E53DE1B71EXAMPLE and region-code with the values returned in the previous step. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replace arn:aws: with arn:aws-us-gov:.

      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Principal": {
              "Federated": "arn:aws:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
              "StringLike": {
                "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:efs-csi-*",
                "oidc.eks.region-code.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com"
              }
            }
          }
        ]
      }

   2. Create the role. You can change AmazonEKS_EFS_CSI_DriverRole to a different name, but if you do, make sure to change it in later steps too.

      aws iam create-role \
        --role-name AmazonEKS_EFS_CSI_DriverRole \
        --assume-role-policy-document file://"aws-efs-csi-driver-trust-policy.json"
      

3. Attach the required AWS managed policy to the role with the following command. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replace arn:aws: with arn:aws-us-gov:.

   aws iam attach-role-policy \
     --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEFSCSIDriverPolicy \
     --role-name AmazonEKS_EFS_CSI_DriverRole
   

Step 2: Get the Amazon EFS CSI driver

We recommend that you install the Amazon EFS CSI driver through the Amazon EKS add-on. To add an Amazon EKS add-on to your cluster, see Creating an Amazon EKS add-on. For more information about add-ons, see Amazon EKS add-ons. If you're unable to use the Amazon EKS add-on, we encourage you to submit an issue about why you can't to the Containers roadmap GitHub repository.

Alternatively, if you want a self-managed installation of the Amazon EFS CSI driver, see Installation on GitHub.

Step 3: Create an Amazon EFS file system

Note

This step isn't needed for AWS Fargate. A Pod running on Fargate automatically mounts an Amazon EFS file system.

To create an Amazon EFS file system, see Create an Amazon EFS file system for Amazon EKS on GitHub.

Step 4: Deploy a sample application

You can deploy a variety of sample apps and modify them as needed. For more information, see Examples on GitHub.