Skip to content

Commit afb0a54

Browse files
julianwoodjulianwood
authored
Merge pull request #3075 from NithinChandranR-AWS/NithinChandranR-AWS-feature-lambda-s3-files-cdk
New serverless pattern - lambda-s3-files-cdk
2 parents 65cd134 + fb20a87 commit afb0a54

10 files changed

Lines changed: 499 additions & 0 deletions

File tree

‎lambda-s3-files-cdk/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules
2+
cdk.out
3+
*.js
4+
!src/**/*.js
5+
*.d.ts
6+
package-lock.json

‎lambda-s3-files-cdk/README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# AWS Lambda with Amazon S3 Files Mount
2+
3+
This pattern deploys an AWS Lambda function with an Amazon S3 Files file system mounted as a local directory, enabling standard file operations on S3 data without downloading objects.
4+
5+
Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/lambda-s3-files-cdk
6+
7+
Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example.
8+
9+
## Requirements
10+
11+
- [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The AWS IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources.
12+
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured
13+
- [Git Installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
14+
- [Node and NPM](https://nodejs.org/en/download/) installed
15+
- [AWS CDK](https://docs.aws.amazon.com/cdk/latest/guide/cli.html) installed
16+
17+
## Deployment Instructions
18+
19+
1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository:
20+
```bash
21+
git clone https://github.com/aws-samples/serverless-patterns
22+
```
23+
2. Change directory to the pattern directory:
24+
```bash
25+
cd serverless-patterns/lambda-s3-files-cdk
26+
```
27+
3. Install CDK dependencies:
28+
```bash
29+
npm install
30+
```
31+
4. Deploy the stack:
32+
```bash
33+
cdk deploy
34+
```
35+
36+
## How it works
37+
38+
[Amazon S3 Files](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files.html) provides NFS access to S3 buckets with full POSIX semantics. This pattern mounts an S3 bucket on a Lambda function at `/mnt/s3data`.
39+
40+
### What gets deployed
41+
42+
| Resource | Purpose |
43+
|---|---|
44+
| S3 Bucket | Data store backing the file system |
45+
| VPC (2 AZs) | Network for Lambda and mount targets |
46+
| S3 Files FileSystem | NFS file system linked to the S3 bucket |
47+
| S3 Files MountTargets | Network endpoints in each private subnet |
48+
| S3 Files AccessPoint | Application entry point (UID/GID 1000, root `/lambda`) |
49+
| Security Group | Allows NFS traffic (port 2049) |
50+
| Lambda Function | Reads, writes, and lists files via the mount |
51+
52+
### Architecture
53+
54+
```
55+
┌──────────┐ ┌─────────────────────────────────────────┐
56+
│ S3 Bucket│◄───►│ S3 Files FileSystem │
57+
└──────────┘ │ (auto-sync between S3 and filesystem) │
58+
└──────────────┬────────────────────────────┘
59+
│ NFS (port 2049)
60+
┌──────────────┴────────────────────────────┐
61+
│ VPC │
62+
│ ┌────────────────┐ ┌────────────────┐ │
63+
│ │ Mount Target │ │ Mount Target │ │
64+
│ │ (AZ-1) │ │ (AZ-2) │ │
65+
│ └────────────────┘ └────────────────┘ │
66+
│ ▲ │
67+
│ │ │
68+
│ ┌────────┴───────┐ │
69+
│ │ Lambda Function│ │
70+
│ │ /mnt/s3data │ │
71+
│ └────────────────┘ │
72+
└────────────────────────────────────────────┘
73+
```
74+
75+
### Key S3 Files concepts
76+
77+
- **FileSystem** — A shared file system linked to your S3 bucket. Changes sync bidirectionally.
78+
- **MountTarget** — Network endpoint in a specific AZ. Lambda must be in the same VPC/subnet.
79+
- **AccessPoint** — Application-specific entry point with POSIX user identity and root directory.
80+
- **High-performance storage** — Actively used data cached locally for sub-millisecond latency.
81+
82+
## Testing
83+
84+
1. After deployment, note the `FunctionName` and `BucketName` outputs.
85+
86+
2. **Write a file** through the Lambda mount:
87+
```bash
88+
aws lambda invoke \
89+
--function-name <FunctionName> \
90+
--payload '{"action": "write", "filename": "hello.txt", "content": "Hello from Lambda via S3 Files!"}' \
91+
--cli-binary-format raw-in-base64-out \
92+
output.json
93+
94+
cat output.json
95+
```
96+
97+
3. **Verify the file appeared in S3** (sync takes ~1 minute):
98+
```bash
99+
aws s3 ls s3://<BucketName>/lambda/
100+
```
101+
102+
4. **Read the file** back through Lambda:
103+
```bash
104+
aws lambda invoke \
105+
--function-name <FunctionName> \
106+
--payload '{"action": "read", "filename": "hello.txt"}' \
107+
--cli-binary-format raw-in-base64-out \
108+
output.json
109+
110+
cat output.json
111+
```
112+
113+
5. **List directory** contents:
114+
```bash
115+
aws lambda invoke \
116+
--function-name <FunctionName> \
117+
--payload '{"action": "list"}' \
118+
--cli-binary-format raw-in-base64-out \
119+
output.json
120+
121+
cat output.json
122+
```
123+
124+
## Cleanup
125+
126+
```bash
127+
cdk destroy
128+
```
129+
130+
---
131+
132+
Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved.
133+
134+
SPDX-License-Identifier: MIT-0

‎lambda-s3-files-cdk/bin/app.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/usr/bin/env node
2+
import "source-map-support/register";
3+
import * as cdk from "aws-cdk-lib";
4+
import { LambdaS3FilesStack } from "../lib/lambda-s3-files-stack";
5+
6+
const app = new cdk.App();
7+
new LambdaS3FilesStack(app, "LambdaS3FilesStack");

‎lambda-s3-files-cdk/cdk.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"app": "npx ts-node --prefer-ts-exts bin/app.ts",
3+
"watch": {
4+
"include": ["**"],
5+
"exclude": ["README.md", "cdk*.json", "**/*.d.ts", "**/*.js", "node_modules", "src"]
6+
},
7+
"context": {
8+
"@aws-cdk/aws-lambda:recognizeLayerVersion": true,
9+
"@aws-cdk/core:checkSecretUsage": true
10+
}
11+
}

‎lambda-s3-files-cdk/example-pattern.json‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
{
2+
"title": "AWS Lambda with Amazon S3 Files Mount",
3+
"description": "Mount an Amazon S3 bucket as a local file system on AWS Lambda using Amazon S3 Files, enabling standard file operations (read, write, list) without downloading objects.",
4+
"language": "TypeScript",
5+
"level": "300",
6+
"framework": "AWS CDK",
7+
"introBox": {
8+
"headline": "How it works",
9+
"text": [
10+
"This pattern deploys a Lambda function with an Amazon S3 Files file system mounted at /mnt/s3data. The function performs standard file operations (read, write, list) on S3 data using the local filesystem — no S3 API calls needed.",
11+
"S3 Files provides NFS access to S3 buckets with sub-millisecond latency on small files and full POSIX semantics. The pattern creates a VPC, S3 Files file system, mount targets, access point, and a Lambda function wired together.",
12+
"Multiple Lambda functions can connect to the same S3 Files file system simultaneously, sharing data through a common workspace without custom synchronization logic."
13+
]
14+
},
15+
"gitHub": {
16+
"template": {
17+
"repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/lambda-s3-files-cdk",
18+
"templateURL": "serverless-patterns/lambda-s3-files-cdk",
19+
"projectFolder": "lambda-s3-files-cdk",
20+
"templateFile": "lib/lambda-s3-files-stack.ts"
21+
}
22+
},
23+
"resources": {
24+
"bullets": [
25+
{
26+
"text": "Amazon S3 Files Documentation",
27+
"link": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files.html"
28+
},
29+
{
30+
"text": "Configuring Amazon S3 Files access for Lambda",
31+
"link": "https://docs.aws.amazon.com/lambda/latest/dg/configuration-filesystem-s3files.html"
32+
},
33+
{
34+
"text": "Mounting S3 file systems on Lambda functions",
35+
"link": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-mounting-lambda.html"
36+
}
37+
]
38+
},
39+
"deploy": {
40+
"text": [
41+
"cdk deploy"
42+
]
43+
},
44+
"testing": {
45+
"text": [
46+
"See the GitHub repo for detailed testing instructions."
47+
]
48+
},
49+
"cleanup": {
50+
"text": [
51+
"Delete the stack: <code>cdk destroy</code>."
52+
]
53+
},
54+
"authors": [
55+
{
56+
"name": "Nithin Chandran R",
57+
"bio": "Technical Account Manager at AWS",
58+
"linkedin": "nithin-chandran-r"
59+
}
60+
]
61+
}

‎lambda-s3-files-cdk/lambda-s3-files-cdk.json‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
{
2+
"title": "AWS Lambda with Amazon S3 Files Mount",
3+
"description": "Mount an Amazon S3 bucket as a local file system on AWS Lambda using Amazon S3 Files, enabling standard file operations (read, write, list) without downloading objects.",
4+
"language": "TypeScript",
5+
"level": "300",
6+
"framework": "AWS CDK",
7+
"introBox": {
8+
"headline": "How it works",
9+
"text": [
10+
"This pattern deploys a Lambda function with an Amazon S3 Files file system mounted at /mnt/s3data. The function performs standard file operations (read, write, list) on S3 data using the local filesystem — no S3 API calls needed.",
11+
"S3 Files provides NFS access to S3 buckets with sub-millisecond latency on small files and full POSIX semantics. The pattern creates a VPC, S3 Files file system, mount targets, access point, and a Lambda function wired together.",
12+
"Multiple Lambda functions can connect to the same S3 Files file system simultaneously, sharing data through a common workspace without custom synchronization logic."
13+
]
14+
},
15+
"gitHub": {
16+
"template": {
17+
"repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/lambda-s3-files-cdk",
18+
"templateURL": "serverless-patterns/lambda-s3-files-cdk",
19+
"projectFolder": "lambda-s3-files-cdk",
20+
"templateFile": "lib/lambda-s3-files-stack.ts"
21+
}
22+
},
23+
"resources": {
24+
"bullets": [
25+
{
26+
"text": "Amazon S3 Files Documentation",
27+
"link": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files.html"
28+
},
29+
{
30+
"text": "Configuring Amazon S3 Files access for Lambda",
31+
"link": "https://docs.aws.amazon.com/lambda/latest/dg/configuration-filesystem-s3files.html"
32+
},
33+
{
34+
"text": "Mounting S3 file systems on Lambda functions",
35+
"link": "https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-files-mounting-lambda.html"
36+
}
37+
]
38+
},
39+
"deploy": {
40+
"text": [
41+
"cdk deploy"
42+
]
43+
},
44+
"testing": {
45+
"text": [
46+
"See the GitHub repo for detailed testing instructions."
47+
]
48+
},
49+
"cleanup": {
50+
"text": [
51+
"Delete the stack: <code>cdk destroy</code>."
52+
]
53+
},
54+
"authors": [
55+
{
56+
"name": "Nithin Chandran R",
57+
"bio": "Technical Account Manager at AWS",
58+
"linkedin": "nithin-chandran-r"
59+
}
60+
],
61+
"patternArch": {
62+
"icon1": {
63+
"x": 20,
64+
"y": 50,
65+
"service": "lambda",
66+
"label": "AWS Lambda"
67+
},
68+
"icon2": {
69+
"x": 80,
70+
"y": 50,
71+
"service": "s3",
72+
"label": "Amazon S3 Files"
73+
},
74+
"line1": {
75+
"from": "icon1",
76+
"to": "icon2",
77+
"label": "read/write"
78+
}
79+
}
80+
}

0 commit comments

Comments
 (0)