DirectS3Read

class aws_cdk.aws_lambda.DirectS3Read(*args: Any, **kwargs)

Bases: object

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 to bucket.
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.

ExampleMetadata:: infused

Example:

import aws_cdk as cdk
import aws_cdk.aws_ec2 as ec2
import aws_cdk.aws_s3 as s3
import aws_cdk.aws_s3files as s3files


vpc = ec2.Vpc(self, "Vpc")

# Versioning is required — S3 Files relies on object versions for consistency.
bucket = s3.Bucket(self, "Bucket", versioned=True)

# S3 Files assumes this role to sync data between S3 and the file system.
role = iam.Role(self, "S3FilesRole",
    assumed_by=iam.ServicePrincipal("elasticfilesystem.amazonaws.com")
)

# S3 permissions: read/write access to the bucket and objects
role.add_to_policy(iam.PolicyStatement(
    actions=["s3:ListBucket*"],
    resources=[bucket.bucket_arn]
))
role.add_to_policy(iam.PolicyStatement(
    actions=["s3:AbortMultipartUpload", "s3:DeleteObject", "s3:GetObject*", "s3:List*", "s3:PutObject*"],
    resources=[bucket.arn_for_objects("*")]
))

# EventBridge permissions: S3 Files creates rules prefixed "DO-NOT-DELETE-S3-Files"
# to detect S3 object changes and trigger data synchronization.
role.add_to_policy(iam.PolicyStatement(
    actions=["events:DeleteRule", "events:DisableRule", "events:EnableRule", "events:PutRule", "events:PutTargets", "events:RemoveTargets"
    ],
    resources=[f"arn:{cdk.Aws.PARTITION}:events:*:*:rule/DO-NOT-DELETE-S3-Files*"],
    conditions={"StringEquals": {"events:ManagedBy": "elasticfilesystem.amazonaws.com"}}
))
role.add_to_policy(iam.PolicyStatement(
    actions=["events:DescribeRule", "events:ListRuleNamesByTarget", "events:ListRules", "events:ListTargetsByRule"],
    resources=[f"arn:{cdk.Aws.PARTITION}:events:*:*:rule/*"]
))

file_system = s3files.CfnFileSystem(self, "S3FilesFs",
    bucket=bucket.bucket_arn,
    role_arn=role.role_arn
)

sg = ec2.SecurityGroup(self, "MountTargetSG", vpc=vpc)

# Create a mount target in each private subnet so Lambda can reach the file system via NFS.
vpc.private_subnets.for_each((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.
access_point = s3files.CfnAccessPoint(self, "AccessPoint",
    file_system_id=file_system.attr_file_system_id,
    root_directory=s3files.CfnAccessPoint.RootDirectoryProperty(
        path="/export/lambda",
        creation_permissions=s3files.CfnAccessPoint.CreationPermissionsProperty(owner_gid="1001", owner_uid="1001", permissions="750")
    ),
    posix_user=s3files.CfnAccessPoint.PosixUserProperty(gid="1001", uid="1001")
)

fn = lambda_.Function(self, "MyFunction",
    runtime=lambda_.Runtime.NODEJS_LATEST,
    handler="index.handler",
    code=lambda_.Code.from_asset(path.join(__dirname, "lambda-handler")),
    vpc=vpc,
    filesystem=lambda_.FileSystem.from_s3_files_access_point(access_point, "/mnt/s3files",
        # Enables direct reads and grants s3:GetObject/s3:GetObjectVersion on the bucket to the execution role.
        direct_s3_read=lambda_.DirectS3Read.enabled(bucket)
    )
)

Static Methods

classmethod auto()

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.

Return type:: DirectS3Read

classmethod disabled()

Disable direct S3 read;

all reads are routed through the S3 Files file system’s high-performance storage.

Return type:: DirectS3Read

classmethod enabled(bucket)

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.

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:: bucket (IBucket) – the S3 bucket backing the S3 Files file system.
Return type:: DirectS3Read

classmethod enabled_without_grant()

Enable direct S3 reads, bypassing the mount for higher throughput, without adding any S3 read permissions.

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.

Return type:: DirectS3Read