Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
Amazon EFS CSI driver
The Amazon EFS driver is only available as a self-managed installation in this
Amazon Web Services Region.
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 Amazon 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 persistent volume provisioning with Fargate nodes, but you can
use static provisioning.
-
Dynamic provisioning requires 1.2
or later of the driver. You can
statically provision 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.
Prerequisites
-
An existing Amazon Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or to create one, see Creating an IAM OIDC provider
for your cluster.
-
Version 2.12.3
or later or 1.27.160
or later of the Amazon CLI installed and configured on your device or Amazon CloudShell. You can check your current version with 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 Amazon CLI. To install the latest version, see
Installing, updating, and uninstalling the Amazon CLI and Quick configuration with aws configure
in the Amazon Command Line Interface User Guide. The Amazon CLI version installed in the Amazon CloudShell may also be several versions behind the latest version. To update it, see
Installing Amazon CLI to your home directory in the Amazon CloudShell User Guide.
-
The kubectl
command line tool is installed on your device or
Amazon 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.26
, you can use kubectl
version 1.25
, 1.26
, or 1.27
with it. To
install or upgrade kubectl
, see Installing or updating kubectl.
A Pod running on Amazon Fargate automatically mounts an Amazon EFS file system.
Creating an IAM role
The Amazon EFS CSI driver requires IAM permissions to interact with your file system. For
more information, see Set up driver permission on GitHub.
Create an IAM role and attach the required Amazon managed policy to it. Annotate the
Kubernetes service account with the IAM role ARN and the IAM role with the Kubernetes
service account name. You can use eksctl
, the Amazon Web Services Management Console, or the Amazon CLI.
- eksctl
-
To create your Amazon EFS CSI driver IAM role with
eksctl
Run the following commands to create the IAM role and Kubernetes service
account. The commands also attach the policy to the role, annotate the Kubernetes
service accounts (efs-csi-controller-sa
and
efs-csi-node-sa
) with the IAM role ARN, and add the
Kubernetes service account name to the trust policy for 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-cn:iam::aws:policy/service-role/AmazonEFSCSIDriverPolicy \
--approve
eksctl create iamserviceaccount \
--name efs-csi-node-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"
- Amazon Web Services Management Console
-
To create your Amazon EFS CSI driver IAM role with the Amazon Web Services Management Console
Open the IAM console at
https://console.amazonaws.cn/iam/.
-
In the left navigation pane, choose
Roles.
-
On the Roles page, choose Create
role.
-
On the Select trusted entity page, do the
following:
In the Trusted entity type section, choose Web identity.
-
For Identity provider, choose the
OpenID Connect provider
URL for your cluster (as shown under
Overview in Amazon EKS).
-
For Audience, choose
sts.amazonaws.com
.
Choose Next.
-
On the Add permissions page, do the
following:
-
In the Filter policies box, enter
AmazonEFSCSIDriverPolicy
.
-
Select the check box to the left of the
AmazonEFSCSIDriverPolicy
returned in the search.
Choose Next.
-
On the Name, review, and create page, do the
following:
-
For Role name, enter a unique name for your role, such as
AmazonEKS_EFS_CSI_DriverRole
.
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 Entities in the IAM User Guide.
-
Choose Create role.
After the role is created, choose the role in the console to open it for editing.
Choose the Trust relationships tab, and then choose Edit trust policy.
-
Find the line that looks similar to the following line:
"oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:aud": "sts.amazonaws.com"
Add the following line above the previous line.
Replace region-code
with the Amazon Web Services Region that your cluster is in. Replace
EXAMPLED539D4633E53DE1B71EXAMPLE
with your cluster's OIDC provider ID.
"oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:sub": "system:serviceaccount:kube-system:efs-csi-*",
-
Modify the Condition
operator from
"StringEquals"
to "StringLike"
.
Choose Update policy to finish.
-
For self-managed installations of the
driver, create Kubernetes service accounts that are annotated with the
ARN of the IAM role that you created. This step isn't required
if you are installing the driver as an Amazon EKS add-on.
-
Save the following contents to a file named
efs-service-account
.yaml
.
Replace
111122223333
with your account ID.
---
apiVersion: v1
kind: ServiceAccount
metadata:
labels:
app.kubernetes.io/name: aws-efs-csi-driver
name: efs-csi-controller-sa
namespace: kube-system
annotations:
eks.amazonaws.com/role-arn: arn:aws-cn:iam::111122223333
:role/AmazonEKS_EFS_CSI_DriverRole
---
apiVersion: v1
kind: ServiceAccount
metadata:
labels:
app.kubernetes.io/name: aws-efs-csi-driver
name: efs-csi-node-sa
namespace: kube-system
annotations:
eks.amazonaws.com/role-arn: arn:aws-cn:iam::111122223333
:role/AmazonEKS_EFS_CSI_DriverRole
-
Create the Kubernetes service account on your cluster. The
Kubernetes service accounts (efs-csi-controller-sa
and efs-csi-node-sa
) are annotated with the
IAM role that you created named
AmazonEKS_EFS_CSI_DriverRole
.
kubectl apply -f efs-service-account
.yaml
- Amazon CLI
-
To create your Amazon EFS CSI driver IAM role with the Amazon CLI
-
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.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
-
Create the IAM role, granting the Kubernetes service account the
AssumeRoleWithWebIdentity
action.
-
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.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws-cn:iam::111122223333
:oidc-provider/oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringLike": {
"oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:sub": "system:serviceaccount:kube-system:efs-csi-*",
"oidc.eks.region-code
.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:aud": "sts.amazonaws.com"
}
}
}
]
}
-
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"
-
Attach the required Amazon managed policy to the role with the
following command.
aws iam attach-role-policy \
--policy-arn arn:aws-cn:iam::aws:policy/service-role/AmazonEFSCSIDriverPolicy
\
--role-name AmazonEKS_EFS_CSI_DriverRole
-
For self-managed installations of the driver, create Kubernetes service
accounts that are annotated with the ARN of the IAM role that
you created. This step isn't required if you are installing the
driver as an Amazon EKS add-on.
-
Save the following contents to a file named
efs-service-account
.yaml
.
Replace
111122223333
with your account ID.
---
apiVersion: v1
kind: ServiceAccount
metadata:
labels:
app.kubernetes.io/name: aws-efs-csi-driver
name: efs-csi-controller-sa
namespace: kube-system
annotations:
eks.amazonaws.com/role-arn: arn:aws-cn:iam::111122223333
:role/AmazonEKS_EFS_CSI_DriverRole
---
apiVersion: v1
kind: ServiceAccount
metadata:
labels:
app.kubernetes.io/name: aws-efs-csi-driver
name: efs-csi-node-sa
namespace: kube-system
annotations:
eks.amazonaws.com/role-arn: arn:aws-cn:iam::111122223333
:role/AmazonEKS_EFS_CSI_DriverRole
-
Create the Kubernetes service account on your cluster. The
Kubernetes service accounts (efs-csi-controller-sa
and efs-csi-node-sa
) are annotated with the
IAM role that you created named
AmazonEKS_EFS_CSI_DriverRole
.
kubectl apply -f efs-service-account
.yaml
Installing the Amazon EFS CSI driver
For details on how to do a self-managed installation of the Amazon EFS
CSI driver, see Installation on GitHub.
Creating an Amazon EFS file system
To create an Amazon EFS file system, see Create an Amazon EFS file system for Amazon EKS on GitHub.
Deploying a sample application
You can deploy a variety of sample apps and modify them as needed. For more
information, see Examples on GitHub.