DirectS3Read Class
The DirectS3Read configuration for an S3 Files filesystem mount.
Direct reads let Lambda read objects straight from the backing S3 bucket for higher throughput, instead of routing every read through the file system mount.
Create one with a factory method:
DirectS3Read.enabled(bucket)— turn direct reads on and grant the execution role read access tobucket.DirectS3Read.enabledWithoutGrant()— turn direct reads on but add no S3 permissions; grant read access to the execution role yourself.DirectS3Read.auto()— let the service decide based on the function's memory.DirectS3Read.disabled()— always read through the mount.
Example
ts
import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as s3files from 'aws-cdk-lib/aws-s3files';
const vpc = new ec2.Vpc(this, 'Vpc');
// Versioning is required — S3 Files relies on object versions for consistency.
const bucket = new s3.Bucket(this, 'Bucket', { versioned: true });
// S3 Files assumes this role to sync data between S3 and the file system.
const role = new iam.Role(this, 'S3FilesRole', {
assumedBy: new iam.ServicePrincipal('elasticfilesystem.amazonaws.com'),
});
// S3 permissions: read/write access to the bucket and objects
role.addToPolicy(new iam.PolicyStatement({
actions: ['s3:ListBucket*'],
resources: [bucket.bucketArn],
}));
role.addToPolicy(new iam.PolicyStatement({
actions: ['s3:AbortMultipartUpload', 's3:DeleteObject', 's3:GetObject*', 's3:List*', 's3:PutObject*'],
resources: [bucket.arnForObjects('*')],
}));
// EventBridge permissions: S3 Files creates rules prefixed "DO-NOT-DELETE-S3-Files"
// to detect S3 object changes and trigger data synchronization.
role.addToPolicy(new iam.PolicyStatement({
actions: [
'events:DeleteRule', 'events:DisableRule', 'events:EnableRule',
'events:PutRule', 'events:PutTargets', 'events:RemoveTargets',
],
resources: [`arn:${cdk.Aws.PARTITION}:events:*:*:rule/DO-NOT-DELETE-S3-Files*`],
conditions: { StringEquals: { 'events:ManagedBy': 'elasticfilesystem.amazonaws.com' } },
}));
role.addToPolicy(new iam.PolicyStatement({
actions: ['events:DescribeRule', 'events:ListRuleNamesByTarget', 'events:ListRules', 'events:ListTargetsByRule'],
resources: [`arn:${cdk.Aws.PARTITION}:events:*:*:rule/*`],
}));
const fileSystem = new s3files.CfnFileSystem(this, 'S3FilesFs', {
bucket: bucket.bucketArn,
roleArn: role.roleArn,
});
const sg = new ec2.SecurityGroup(this, 'MountTargetSG', { vpc });
// Create a mount target in each private subnet so Lambda can reach the file system via NFS.
vpc.privateSubnets.forEach((subnet, i) =>
new s3files.CfnMountTarget(this, `MountTarget${i}`, {
fileSystemId: fileSystem.attrFileSystemId,
subnetId: subnet.subnetId,
securityGroups: [sg.securityGroupId],
}),
);
// The access point defines the POSIX identity and root path Lambda uses on the file system.
const accessPoint = new s3files.CfnAccessPoint(this, 'AccessPoint', {
fileSystemId: fileSystem.attrFileSystemId,
rootDirectory: {
path: '/export/lambda',
creationPermissions: { ownerGid: '1001', ownerUid: '1001', permissions: '750' },
},
posixUser: { gid: '1001', uid: '1001' },
});
const fn = new lambda.Function(this, 'MyFunction', {
runtime: lambda.Runtime.NODEJS_LATEST,
handler: 'index.handler',
code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
vpc,
filesystem: lambda.FileSystem.fromS3FilesAccessPoint(accessPoint, '/mnt/s3files', {
// Enables direct reads and grants s3:GetObject/s3:GetObjectVersion on the bucket to the execution role.
directS3Read: lambda.DirectS3Read.enabled(bucket),
}),
});
Methods
auto(): DirectS3Read // chainable@staticmethod def auto() -> DirectS3Readpublic static DirectS3Read auto()public static DirectS3Read Auto()func Auto() DirectS3Readstatic#Let the service decide whether to use direct S3 read based on the function's memory configuration: direct reads are active for functions with 512 MB or more of memory.
No S3 read permissions are added; the execution role must already hold them for a service-initiated direct read to succeed, otherwise reads fall back to the mount.
disabled(): DirectS3Read // chainable@staticmethod def disabled() -> DirectS3Readpublic static DirectS3Read disabled()public static DirectS3Read Disabled()func Disabled() DirectS3Readstatic#Disable direct S3 read;
all reads are routed through the S3 Files file system's high-performance storage.
enabled(bucket: IBucket): DirectS3Read // chainable@staticmethod def enabled(bucket: IBucket) -> DirectS3Readpublic static DirectS3Read enabled(IBucket bucket)public static DirectS3Read Enabled(IBucket bucket)func Enabled(Bucket IBucket) DirectS3Readstatic#Enable direct S3 reads, bypassing the mount for higher throughput, and grant the function's execution role `s3:GetObject` and `s3:GetObjectVersion` on the bucket's objects so that direct reads can succeed.
notes · 1 parameter
Unlike auto(), this enables direct reads regardless of the function's memory size, including functions with less than 512 MB of memory.
If the bucket is encrypted with a customer-managed KMS key, also grant the execution role kms:Decrypt on that key yourself.
Parameters
bucketbucketbucketbucketBucket— the S3 bucket backing the S3 Files file system.
enabledWithoutGrant(): DirectS3Read // chainable@staticmethod def enabled_without_grant() -> DirectS3Readpublic static DirectS3Read enabledWithoutGrant()public static DirectS3Read EnabledWithoutGrant()func EnabledWithoutGrant() DirectS3Readstatic#Enable direct S3 reads, bypassing the mount for higher throughput, without adding any S3 read permissions.
notes
Like enabled(), this enables direct reads regardless of the function's memory size, including functions with less than 512 MB of memory.
Use this when the execution role already has s3:GetObject/s3:GetObjectVersion on the backing bucket (for example through a managed policy or a bucket policy). You are responsible for granting those permissions; without them, direct reads silently fall back to reading through the file system.