Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Use Amazon S3 file system storage with the Amazon EFS CSI driver

S3 Files is a shared file system that connects any AWS compute directly with your data in Amazon S3. It provides fast, direct access to all of your S3 data as files with full file system semantics and low-latency performance, without your data ever leaving S3. That means file-based applications, agents, and teams can access and work with S3 data as a file system using the tools they already depend on. The Amazon EFS Container Storage Interface (CSI) driver allows Kubernetes clusters running on AWS to mount Amazon S3 file systems as persistent volumes starting from version 3.0.0. This topic shows you how to use the Amazon EFS CSI driver to manage Amazon S3 file system on your Amazon EKS cluster.

Considerations

Prerequisites

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 arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy managed policy to it.

To implement this procedure, you can use one of these tools:

eksctl

If using Pod Identities

Run the following commands to create an IAM role and Pod Identity association with eksctl. Replace my-cluster with your cluster name, <111122223333> with your account ID, and AmazonEKS_EFS_CSI_DriverRole with a different name if desired.

export cluster_name=my-cluster
export role_name=AmazonEKS_EFS_CSI_DriverRole
export account_id=111122223333
eksctl create podidentityassociation \
    --service-account-name efs-csi-controller-sa \
    --namespace kube-system \
    --cluster $cluster_name \
    --role-name $role_name \
    --permission-policy-arns arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy
eksctl create podidentityassociation \
    --service-account-name efs-csi-node-sa \
    --namespace kube-system \
    --cluster $cluster_name \
    --role-arn arn:aws:iam::$account_id:role/$role_name \
    --permission-policy-arns arn:aws:iam::aws:policy/service-role/AmazonS3FilesCSIDriverPolicy

If using IAM roles for service accounts

Run the following commands to create an IAM role with eksctl. Replace my-cluster with your cluster name, <111122223333> with your account ID, and AmazonEKS_EFS_CSI_DriverRole with a different name if desired.

export cluster_name=my-cluster
export role_name=AmazonEKS_EFS_CSI_DriverRole
export account_id=111122223333
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/AmazonS3FilesCSIDriverPolicy \
    --approve
TRUST_POLICY=$(aws iam get-role --output json --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"
eksctl create iamserviceaccount \
    --name efs-csi-node-sa \
    --namespace kube-system \
    --cluster $cluster_name \
    --attach-role-arn arn:aws:iam::$account_id:role/$role_name \
    --approve

AWS Management Console

Run the following to create an IAM role with AWS Management Console.

AWS CLI

Run the following commands to create an IAM role with AWS CLI.

If using Pod Identities

If using IAM roles for service accounts

Enable direct S3 read access

Enabling direct S3 read access allows the EFS CSI driver to read objects directly from S3, which can reduce costs and provide higher throughput for S3 file systems. Attach the following IAM policy to your EFS CSI driver’s IAM role. Replace {YOUR_S3_BUCKET_NAME} with your S3 bucket name. 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:.

Publish efs-utils logs to CloudWatch

Publishing efs-utils logs to Amazon CloudWatch provides visibility into mount operations and makes troubleshooting or monitoring easier. Attach the AWS managed policy AmazonElasticFileSystemUtils to your EFS CSI driver’s IAM role.

role_name = AmazonEKS_EFS_CSI_DriverRole
aws iam attach-role-policy \
  --role-name $role_name \
  --policy-arn arn:aws:iam::aws:policy/AmazonElasticFileSystemUtils

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 Create 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 S3 file system

To create an Amazon S3 file system, see Create an Amazon S3 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.