Package software.amazon.awscdk.services.efs
Amazon Elastic File System Construct Library
Amazon Elastic File System (Amazon EFS) provides a simple, scalable, fully managed elastic NFS file system for use with AWS Cloud services and on-premises resources. Amazon EFS provides file storage in the AWS Cloud. With Amazon EFS, you can create a file system, mount the file system on an Amazon EC2 instance, and then read and write data to and from your file system.
This module is part of the AWS Cloud Development Kit project.
File Systems
Amazon EFS provides elastic, shared file storage that is POSIX-compliant. The file system you create supports concurrent read and write access from multiple Amazon EC2 instances and is accessible from all of the Availability Zones in the AWS Region where it is created. Learn more about EFS file systems
Create an Amazon EFS file system
A Virtual Private Cloud (VPC) is required to create an Amazon EFS file system.
The following example creates a file system that is encrypted at rest, running in General Purpose
performance mode, and Bursting
throughput mode and does not transition files to the Infrequent
Access (IA) storage class.
FileSystem fileSystem = FileSystem.Builder.create(this, "MyEfsFileSystem") .vpc(new Vpc(this, "VPC")) .lifecyclePolicy(LifecyclePolicy.AFTER_14_DAYS) // files are not transitioned to infrequent access (IA) storage by default .performanceMode(PerformanceMode.GENERAL_PURPOSE) // default .outOfInfrequentAccessPolicy(OutOfInfrequentAccessPolicy.AFTER_1_ACCESS) // files are not transitioned back from (infrequent access) IA to primary storage by default .transitionToArchivePolicy(LifecyclePolicy.AFTER_14_DAYS) // files are not transitioned to Archive by default .replicationOverwriteProtection(ReplicationOverwriteProtection.ENABLED) .build();
⚠️ An Amazon EFS file system's performance mode can't be MAX_IO when its throughputMode is ELASTIC.
⚠️ An Amazon EFS file system's performance mode can't be changed after the file system has been created. Updating this property will replace the file system.
Any file system that has been created outside the stack can be imported into your CDK app.
Use the fromFileSystemAttributes()
API to import an existing file system.
Here is an example of giving a role write permissions on a file system.
import software.amazon.awscdk.services.iam.*; IFileSystem importedFileSystem = FileSystem.fromFileSystemAttributes(this, "existingFS", FileSystemAttributes.builder() .fileSystemId("fs-12345678") // You can also use fileSystemArn instead of fileSystemId. .securityGroup(SecurityGroup.fromSecurityGroupId(this, "SG", "sg-123456789", SecurityGroupImportOptions.builder() .allowAllOutbound(false) .build())) .build());
One Zone file system
To initialize a One Zone file system use the oneZone
property:
Vpc vpc; FileSystem.Builder.create(this, "OneZoneFileSystem") .vpc(vpc) .oneZone(true) .build();
⚠️ One Zone file systems are not compatible with the MAX_IO performance mode.
⚠️ When oneZone
is enabled, the file system is automatically placed in the first availability zone of the VPC.
To specify a different availability zone:
Vpc vpc; FileSystem.Builder.create(this, "OneZoneFileSystem") .vpc(vpc) .oneZone(true) .vpcSubnets(SubnetSelection.builder() .availabilityZones(List.of("us-east-1b")) .build()) .build();
⚠️ When oneZone
is enabled, mount targets will be created only in the specified availability zone.
This is to prevent deployment failures due to cross-AZ configurations.
⚠️ When oneZone
is enabled, vpcSubnets
can be specified with
availabilityZones
that contains exactly one single zone.
Replicating file systems
You can create a replica of your EFS file system in the AWS Region of your preference.
Vpc vpc; // auto generate a regional replication destination file system // auto generate a regional replication destination file system FileSystem.Builder.create(this, "RegionalReplicationFileSystem") .vpc(vpc) .replicationConfiguration(ReplicationConfiguration.regionalFileSystem("us-west-2")) .build(); // auto generate a one zone replication destination file system // auto generate a one zone replication destination file system FileSystem.Builder.create(this, "OneZoneReplicationFileSystem") .vpc(vpc) .replicationConfiguration(ReplicationConfiguration.oneZoneFileSystem("us-east-1", "us-east-1a")) .build(); FileSystem destinationFileSystem = FileSystem.Builder.create(this, "DestinationFileSystem") .vpc(vpc) // set as the read-only file system for use as a replication destination .replicationOverwriteProtection(ReplicationOverwriteProtection.DISABLED) .build(); // specify the replication destination file system // specify the replication destination file system FileSystem.Builder.create(this, "ReplicationFileSystem") .vpc(vpc) .replicationConfiguration(ReplicationConfiguration.existingFileSystem(destinationFileSystem)) .build();
Note: EFS now supports only one replication destination and thus allows specifying just one replicationConfiguration
for each file system.
Visit Replicating file systems for more details.
IAM to control file system data access
You can use both IAM identity policies and resource policies to control client access to Amazon EFS resources in a way that is scalable and optimized for cloud environments. Using IAM, you can permit clients to perform specific actions on a file system, including read-only, write, and root access.
import software.amazon.awscdk.services.iam.*; PolicyDocument myFileSystemPolicy = PolicyDocument.Builder.create() .statements(List.of(PolicyStatement.Builder.create() .actions(List.of("elasticfilesystem:ClientWrite", "elasticfilesystem:ClientMount")) .principals(List.of(new AccountRootPrincipal())) .resources(List.of("*")) .conditions(Map.of( "Bool", Map.of( "elasticfilesystem:AccessedViaMountTarget", "true"))) .build())) .build(); FileSystem fileSystem = FileSystem.Builder.create(this, "MyEfsFileSystem") .vpc(new Vpc(this, "VPC")) .fileSystemPolicy(myFileSystemPolicy) .build();
Alternatively, a resource policy can be added later using addToResourcePolicy(statement)
. Note that this will not work with imported FileSystem.
import software.amazon.awscdk.services.iam.*; PolicyStatement statement; FileSystem fileSystem = FileSystem.Builder.create(this, "MyEfsFileSystem") .vpc(new Vpc(this, "VPC")) .build(); fileSystem.addToResourcePolicy(statement);
Permissions
If you need to grant file system permissions to another resource, you can use the .grant()
API.
As an example, the following code gives elasticfilesystem:Backup
permissions to an IAM role.
Role role = Role.Builder.create(this, "Role") .assumedBy(new AnyPrincipal()) .build(); fileSystem.grant(role, "elasticfilesystem:Backup");
APIs for clients also include .grantRead()
, .grantReadWrite()
, and .grantRootAccess()
. Using these APIs grants access to clients.
Also, by default, the file system policy is updated to only allow access to clients using IAM authentication and deny access to anonymous clients.
Role role = Role.Builder.create(this, "ClientRole") .assumedBy(new AnyPrincipal()) .build(); fileSystem.grantRead(role);
You can control this behavior with allowAnonymousAccess
. The following example continues to allow anonymous client access.
import software.amazon.awscdk.services.iam.*; Role role = Role.Builder.create(this, "ClientRole") .assumedBy(new AnyPrincipal()) .build(); FileSystem fileSystem = FileSystem.Builder.create(this, "MyEfsFileSystem") .vpc(new Vpc(this, "VPC")) .allowAnonymousAccess(true) .build(); fileSystem.grantRead(role);
Access Point
An access point is an application-specific view into an EFS file system that applies an operating system user and group, and a file system path, to any file system request made through the access point. The operating system user and group override any identity information provided by the NFS client. The file system path is exposed as the access point's root directory. Applications using the access point can only access data in its own directory and below. To learn more, see Mounting a File System Using EFS Access Points.
Use the addAccessPoint
API to create an access point from a fileSystem.
fileSystem.addAccessPoint("AccessPoint");
By default, when you create an access point, the root(/
) directory is exposed to the client
connecting to the access point. You can specify a custom path with the path
property.
If path
does not exist, it will be created with the settings defined in the creationInfo
.
See Creating Access Points for more details.
Any access point that has been created outside the stack can be imported into your CDK app.
Use the fromAccessPointAttributes()
API to import an existing access point.
AccessPoint.fromAccessPointAttributes(this, "ap", AccessPointAttributes.builder() .accessPointId("fsap-1293c4d9832fo0912") .fileSystem(FileSystem.fromFileSystemAttributes(this, "efs", FileSystemAttributes.builder() .fileSystemId("fs-099d3e2f") .securityGroup(SecurityGroup.fromSecurityGroupId(this, "sg", "sg-51530134")) .build())) .build());
⚠️ Notice: When importing an Access Point using fromAccessPointAttributes()
, you must make sure
the mount targets are deployed and their lifecycle state is available
. Otherwise, you may encounter
the following error when deploying:
EFS file system
referenced by access point has mount targets created in all availability zones the function will execute in, but not all are in the available life cycle state yet. Please wait for them to become available and try the request again.
Connecting
To control who can access the EFS, use the .connections
attribute. EFS has
a fixed default port, so you don't need to specify the port:
fileSystem.connections.allowDefaultPortFrom(instance);
Learn more about managing file system network accessibility
Mounting the file system using User Data
After you create a file system, you can create mount targets. Then you can mount the file system on EC2 instances, containers, and Lambda functions in your virtual private cloud (VPC).
The following example automatically mounts a file system during instance launch.
fileSystem.connections.allowDefaultPortFrom(instance); instance.userData.addCommands("yum check-update -y", "yum upgrade -y", "yum install -y amazon-efs-utils", "yum install -y nfs-utils", "file_system_id_1=" + fileSystem.getFileSystemId(), "efs_mount_point_1=/mnt/efs/fs1", "mkdir -p \"${efs_mount_point_1}\"", "test -f \"/sbin/mount.efs\" && echo \"${file_system_id_1}:/ ${efs_mount_point_1} efs defaults,_netdev\" >> /etc/fstab || " + "echo \"${file_system_id_1}.efs." + Stack.of(this).getRegion() + ".amazonaws.com:/ ${efs_mount_point_1} nfs4 nfsvers=4.1,rsize=1048576,wsize=1048576,hard,timeo=600,retrans=2,noresvport,_netdev 0 0\" >> /etc/fstab", "mount -a -t efs,nfs4 defaults");
Learn more about mounting EFS file systems
Deleting
Since file systems are stateful resources, by default the file system will not be deleted when your stack is deleted.
You can configure the file system to be destroyed on stack deletion by setting a removalPolicy
FileSystem fileSystem = FileSystem.Builder.create(this, "EfsFileSystem") .vpc(new Vpc(this, "VPC")) .removalPolicy(RemovalPolicy.DESTROY) .build();
-
ClassDescriptionRepresents the AccessPoint.A fluent builder for
AccessPoint
.Attributes that can be specified when importing an AccessPoint.A builder forAccessPointAttributes
An implementation forAccessPointAttributes
Options to create an AccessPoint.A builder forAccessPointOptions
An implementation forAccessPointOptions
Properties for the AccessPoint.A builder forAccessPointProps
An implementation forAccessPointProps
Permissions as POSIX ACL.A builder forAcl
An implementation forAcl
TheAWS::EFS::AccessPoint
resource creates an EFS access point.A tag is a key-value pair attached to a file system.A builder forCfnAccessPoint.AccessPointTagProperty
An implementation forCfnAccessPoint.AccessPointTagProperty
A fluent builder forCfnAccessPoint
.Required if theRootDirectory
>Path
specified does not exist.A builder forCfnAccessPoint.CreationInfoProperty
An implementation forCfnAccessPoint.CreationInfoProperty
The full POSIX identity, including the user ID, group ID, and any secondary group IDs, on the access point that is used for all file system operations performed by NFS clients using the access point.A builder forCfnAccessPoint.PosixUserProperty
An implementation forCfnAccessPoint.PosixUserProperty
Specifies the directory on the Amazon EFS file system that the access point provides access to.A builder forCfnAccessPoint.RootDirectoryProperty
An implementation forCfnAccessPoint.RootDirectoryProperty
Properties for defining aCfnAccessPoint
.A builder forCfnAccessPointProps
An implementation forCfnAccessPointProps
TheAWS::EFS::FileSystem
resource creates a new, empty file system in Amazon Elastic File System ( Amazon EFS ).The backup policy turns automatic backups for the file system on or off.A builder forCfnFileSystem.BackupPolicyProperty
An implementation forCfnFileSystem.BackupPolicyProperty
A fluent builder forCfnFileSystem
.A tag is a key-value pair attached to a file system.A builder forCfnFileSystem.ElasticFileSystemTagProperty
An implementation forCfnFileSystem.ElasticFileSystemTagProperty
Describes the protection on the file system.A builder forCfnFileSystem.FileSystemProtectionProperty
An implementation forCfnFileSystem.FileSystemProtectionProperty
Describes a policy used by Lifecycle management that specifies when to transition files into and out of the EFS storage classes.A builder forCfnFileSystem.LifecyclePolicyProperty
An implementation forCfnFileSystem.LifecyclePolicyProperty
Describes the replication configuration for a specific file system.A builder forCfnFileSystem.ReplicationConfigurationProperty
An implementation forCfnFileSystem.ReplicationConfigurationProperty
Describes the destination file system in the replication configuration.A builder forCfnFileSystem.ReplicationDestinationProperty
An implementation forCfnFileSystem.ReplicationDestinationProperty
Properties for defining aCfnFileSystem
.A builder forCfnFileSystemProps
An implementation forCfnFileSystemProps
TheAWS::EFS::MountTarget
resource is an Amazon EFS resource that creates a mount target for an EFS file system.A fluent builder forCfnMountTarget
.Properties for defining aCfnMountTarget
.A builder forCfnMountTargetProps
An implementation forCfnMountTargetProps
Properties for configuring ReplicationConfiguration to replicate to an existing file system.A builder forExistingFileSystemProps
An implementation forExistingFileSystemProps
The Elastic File System implementation of IFileSystem.A fluent builder forFileSystem
.Properties that describe an existing EFS file system.A builder forFileSystemAttributes
An implementation forFileSystemAttributes
Properties of EFS FileSystem.A builder forFileSystemProps
An implementation forFileSystemProps
Represents an EFS AccessPoint.Internal default implementation forIAccessPoint
.A proxy class which represents a concrete javascript instance of this type.Represents an Amazon EFS file system.Internal default implementation forIFileSystem
.A proxy class which represents a concrete javascript instance of this type.EFS Lifecycle Policy, if a file is not accessed for given days, it will move to EFS Infrequent Access or Archive storage.Properties for configuring ReplicationConfiguration to replicate to a new One Zone file system.A builder forOneZoneFileSystemProps
An implementation forOneZoneFileSystemProps
EFS Out Of Infrequent Access Policy, if a file is accessed given times, it will move back to primary storage class.EFS Performance mode.Represents the PosixUser.A builder forPosixUser
An implementation forPosixUser
Properties for configuring ReplicationConfiguration to replicate to a new Regional file system.A builder forRegionalFileSystemProps
An implementation forRegionalFileSystemProps
EFS Replication Configuration.Properties for the ReplicationConfiguration.A builder forReplicationConfigurationProps
An implementation forReplicationConfigurationProps
The status of the file system's replication overwrite protection.EFS Throughput mode.