A tool to run web applications on AWS Lambda without changing code.

AWS Samples

Last update: Jan 2, 2023

Related tags

Utilities lambda aws-lambda

Overview

AWS Lambda Adapter

A tool to run web applications on AWS Lambda without changing code.

How does it work?

AWS Lambda Adapter supports AWS Lambda function triggered by Amazon API Gateway Rest API, Http API(v2 event format), and Application Load Balancer. Lambda Adapter converts incoming events to http requests and send to web application, and convert the http response back to lambda event response. When used outside of AWS Lambda execution environment, Lambda Adapter will just execute web application in the same process. This allows developers to package their web application as a container image and run it on AWS Lambda, AWS Fargate and Amazon EC2 without changing code.

After Lambda Adapter launch the application, it will perform readiness check on http://localhost:8080/ every 10ms. It will start lambda runtime client after receiving 200 response from the application and forward requests to http://localhost:8080.

How to build it?

AWS Lambda Adapter is written in Rust and based on AWS Lambda Rust Runtime. AWS Lambda executes functions in x86_64 Amazon Linux Environment. We need to compile the adapter to that environment.

Clone the repo

First, clone this repo to your local computer.

$ git clone https://github.com/aws-samples/aws-lambda-adapter.git
$ cd aws-lambda-adapter

Compiling with Docker

On x86_64 Windows, Linux and macOS, you can run one command to compile Lambda Adapter with docker. The Dockerfile is here. AWS CLI v2 should have been installed and configured.

$ make build

Once the build completes, it creates two docker images:

"aws-lambda-adapter:latest-x86_64" for x86_64.
"aws-lambda-adapter:latest-aarch64" for arm64.

AWS Lambda Adapter binary is packaged as '/opt/bootstrap' inside each docker image. "aws-lambda-adapter:latest" is tagged to the same image as "aws-lambda-adapter:latest-x86_64".

Compiling on macOS

If you want to install rust toolchain in your Macbook and play with the source code, you can follow the steps below. First, install rustup if you haven't done it already. Then, add targets for x86_86 and arm64:

$ rustup target add x86_64-unknown-linux-musl
$ rustup target add aarch64-unknown-linux-musl

And we have to install macOS cross-compiler toolchains. messense/homebrew-macos-cross-toolchains can be used on both Intel chip and Apple M1 chip.

$ brew tap messense/macos-cross-toolchains
$ brew install x86_64-unknown-linux-musl
$ brew install aarch64-unknown-linux-musl

And we need to inform Cargo that our project uses the newly-installed linker when building for the x86_64-unknown-linux-musl and aarch64-unknown-linux-musl platforms. Create a new directory called .cargo in your project folder and a new file called config inside the new folder.

.cargo/config ">

$ mkdir .cargo
$ echo '[target.x86_64-unknown-linux-musl]
linker = "x86_64-unknown-linux-musl-gcc"

[target.aarch64-unknown-linux-musl] 
linker = "aarch64-unknown-linux-musl-gcc"'> .cargo/config

Now we can cross compile AWS Lambda Adapter.

$ CC=x86_64-unknown-linux-musl-gcc cargo build --release --target=x86_64-unknown-linux-musl --features vendored
$ CC=aarch64-unknown-linux-musl-gcc cargo build --release --target=aarch64-unknown-linux-musl --features vendored

Lambda Adapter binary for x86_64 will be placed at target/x86_64-unknown-linux-musl/release/bootstrap. Lambda Adapter binary for arm64 will be placed at target/aarch64-unknown-linux-musl/release/bootstrap.

Finally, run the following command to package lambda adapter into two container images for x86_64 and arm64.

$ aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
$ docker build -f Dockerfile.mac --build-arg ARCH=x86_64 -t aws-lambda-adapter:latest-x86_64 .
$ docker build -f Dockerfile.mac --build-arg ARCH=aarch64 -t aws-lambda-adapter:latest-aarch64 .
$ docker tag aws-lambda-adapter:latest-x86_64 aws-lambda-adapter:latest

When these commands complete successfully, you will have the following container images.

"aws-lambda-adapter:latest-x86_64" for x86_64.
"aws-lambda-adapter:latest-aarch64" for arm64.
"aws-lambda-adapter:latest" is the same as "aws-lambda-adapter:latest-x86_64".

How to use it?

To use it, copy the bootstrap binary to your container, and use it as ENTRYPOINT. Below is an example Dockerfile for packaging a nodejs application.

FROM public.ecr.aws/lambda/nodejs:14
COPY --from=aws-lambda-adapter:latest /opt/bootstrap /opt/bootstrap
ENTRYPOINT ["/opt/bootstrap"]
EXPOSE 8080
WORKDIR "/var/task"
ADD extensions/ /opt
ADD src/package.json /var/task/package.json
ADD src/package-lock.json /var/task/package-lock.json
RUN npm install --production
ADD src/ /var/task
CMD ["node", "index.js"]

Line 2 and 3 copy lambda adapter binary and set it as ENTRYPOINT. This is the only configuration change required to run web application on AWS Lambda. No need to change the application code.

COPY --from=aws-lambda-adapter:latest /opt/bootstrap /opt/bootstrap
ENTRYPOINT ["/opt/bootstrap"]

To support Graviton2, change aws-lambda-adapter:latest to aws-lambda-adapter:latest-arm64.

The readiness check port/path and traffic port can be configured using environment variables.

Environment Variable	Description	Default
READINESS_CHECK_PORT	readiness check port	8080
READINESS_CHECK_PATH	readiness check path	/
PORT	traffic port	8080

Show me examples

4 examples are included under the 'examples' directory. Check them out, find out how easy it is to run a web application on AWS Lambda.

Acknowledgement

This project was inspired by several community projects.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

Comments

Question: accessing event and context
I'm using the go gin framework and wondering where the event payload from API GW is passed. I see in some examples (flask) there is an event.json file containing the payload, but don't see any example actually accessing that data within the request (unless I missed one).

Is it possible to get at that data for purposes such as checking fields passed from authorizers?

Here's a simple example below that I've deployed and tried, but have only received null responses for requestContext:

func Handler(c *gin.Context) { requestContext, ok := c.Get("requestContext") if !ok { requestContext = "Nope" } c.JSON(200, gin.H{ "message": fmt.Sprintf("ok? %v", requestContext), }) }

Thanks in advance!
opened by pogzyb 18
Support for `nodejs16.x`
When running this extension with nodejs16.x, getting Error: Runtime exited with error: exit status 254 Runtime.ExitError. But it works with nodejs14.x. Did anyone face this issue before? @bnusunny

run.sh

#!/bin/bash npm run start -- --port 8080
opened by rohanshiva 17
Running other node applications and/or reverse proxying?

Hi,

Love this adapter, have you been able to get it working with any other node library/app other than express? I'm trying currently with directus (https://github.com/directus/directus) with external sources for db and assets but having issues with port mapping. I've tried various iterations using directus' docker base image and also using alpine, nginx and reverse proxying - but still have no luck. I assume this is because of the inability to communicate internally via TCP on lambda.

Wondered if anyone had had any luck with anything similar?

Appreciate any help.

opened by gkodikara 17
Querystrings that have percent encodings get double encoded
Before I begin I do not have much experience with Rust or the details of its various packages, but I did try to research this before posting it.

Problem: Whenever a url that contains a querystring with percent encoded values is passed through the adapter, it gets double encoded because (I think) the public function Url.query(&self) -> Option<&str> automatically applies percent encoding to the Url's existing querystring. The now double-percent-encoded querystring is applied to the new Url that is passed to .set_query() here: https://github.com/awslabs/aws-lambda-web-adapter/blob/main/src/lib.rs#L236

Since this adapter operates on values as they are passed to a server, generally any percent encoded that is required should already have been applied, so doing any encoding here (imo) is an error. I believe the correct behavior would be to always pass the querystring through unmolested. Alternately the value returned by .query() could be urldecoded before passing it through to set_query()

Here is an example of a url that triggers this issue:

https://test.com/?originalQueryString=%3FshowAll%3Dtrue

and this is the same url after passing through the adapter:

https://test.com/?originalQueryString=%25253FshowAll%25253Dtrue

I did a very amateurish fix for our own temporary use that looks like this, but I have no idea what I am doing with Rust so I expect you will have a better way to do this. That said, this does fix the problem for our purposes.

// ORG CODE // app_url.set_query(parts.uri.query()); // NEW CODE let querystring = parts.uri.query().unwrap_or_default(); let decoded_querystring = urlencoding::decode(querystring).unwrap_or_default(); app_url.set_query(Some(&decoded_querystring));

Thanks in advance.
opened by heathprovost 11
Emulate Development with lambda runtime interface emulator

Hi Guys,

I'm trying to emulate lambda in a local development environment using lambda runtime interface emulator[1]. When making the invocation to lambda runtime, the adapter attempts to find something on /var/task instead of passing the event request to my HTTP daemon running at the same container.

I tried to create /var/task/ into the container. After that, the adapter tried to find a bootstrap script without success.

I started my daemon and runtime emulator using bash script in the ENTRYPOINT container.

Any idea how I can use lambda runtime to test lambda in a development environment without deployment?

Regards.

[1] - https://github.com/aws/aws-lambda-runtime-interface-emulator

opened by jpaulolins 9
Need aws-lambda-adapter support a new way for deployment - via ZIP not only container

Hello @bnusunny,

As we already have CD pipeline from S3 to lambda, is there any way to deploy existing services using aws-lambda-adapter via S3 (a zip package)?

opened by Crescent617 9
Logs are not shown

Hey,

I am using this awesome to run a fastAPI(Python) on Lambda, but it seems that print statements are not logged to cloudwatch as normally when not using the adapter.

Is that expected?

opened by philschmid 4
How does the `lambda-adapter` binary get executed?

Hi, probably a bit of a random question, but I'm just learning about how Lambda and how this lambda-adapter works. I understand how one can define and use a wrapper script (i.e. AWS_LAMBDA_EXEC_WRAPPER) or a custom runtime to inject and modify how a Lambda function executes. But after studying one of the examples for a long time, I can't figure out how the /opt/extensions/lambda-adapter binary should get invoked.

As far as I can tell. The nodejs14.x runtime will invoke the wrapper script /opt/bootstrap, which will replace the last argument with "${LAMBDA_TASK_ROOT}/${_HANDLER}" i.e. probably something like /var/task/app.js. This immediately takes the node.js runtime into the application's code (i.e. a simple express server) which doesn't leave any room for the lambda-adapter binary to be invoked.

The only thing I can think of is that the name /opt/extensions/lambda-adapter is a special path that the code within the nodejs14.x runtime knows to run. Is that the case? Or is there more setup missing here?

opened by peabnuts123 4
How do I access the request's context?

I'm building a Websocket API and I need to access the context to retrieve $context.connectionId. Where is the context placed after the event is processed by the web adapter?

opened by adarah 3
Request sent twice on cold start invocation
Hi, I see that when running an express app on Lambda with Web Adapter, a request is seemingly processed twice on a cold start. Is it an expected behavior?

Say I have the below express app:

const app = express(); app.get('/', async (_, res) => { console.log('got request'); res.send('success'); });

And I see two lines of got request in CloudWatch logs even though I sent only one request. FYI I'm invoking Lambda via API Gateway REST API.

It is not a blocker at all but I'd like to just confirm if it is expected or not. Thanks!
opened by tmokmss 2
Add login to ECR on flask-zip sample

Issue #, if available:

sam build --use-container fetch a docker image from public.ecr.aws, login is required otherwise raise an error during the pull

raise DockerImagePullFailedException( samcli.local.docker.manager.DockerImagePullFailedException: Could not find public.ecr.aws/sam/build-python3.9:latest-x86_64 image locally and failed to pull it from docker.

Description of changes:

Add docker login to the documentation.

opened by CGarces 2

Releases(v0.6.0)

v0.6.0(Dec 18, 2022)
What's Changed

relax readiness check for HTTP by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/106

forward RequestContext in a http header by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/108

Bump qs and express in /examples/expressjs/app/src by @dependabot in https://github.com/awslabs/aws-lambda-web-adapter/pull/110

update README and examples for v0.6.0 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/111

bump release version to 0.6.0 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/112

Full Changelog: https://github.com/awslabs/aws-lambda-web-adapter/compare/v0.5.1...v0.6.0
Source code(tar.gz)
Source code(zip)
v0.5.1(Oct 30, 2022)
What's Changed

upgrade to lambda_http v0.7.1 to pass correct x-ray trace id header by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/103

release v0.5.1 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/105

Full Changelog: https://github.com/awslabs/aws-lambda-web-adapter/compare/v0.5.0...v0.5.1
Source code(tar.gz)
Source code(zip)
v0.5.0(Oct 13, 2022)
What's Changed

update README for v0.4.1 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/89

add an example for flask in zip by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/91

add golang gin examples by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/93

add fastapi examples by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/98

Upgrade to lambda_http 0.7 by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/100

Release 0.5.0 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/101

Full Changelog: https://github.com/awslabs/aws-lambda-web-adapter/compare/v0.4.1...v0.5.0
Source code(tar.gz)
Source code(zip)
v0.4.1(Sep 21, 2022)
This release contains two notable changes:

add TCP readiness check option

minor change to the library public interface

What's Changed

update README and examples to v0.4.0 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/77

Hide run instruction by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/78

change register_default_extension() as a method on Adapter by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/79

update axum version to 0.5.16 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/81

Add more debug information for req/res transformations by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/83

update demo for sam local debug by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/84

Add tcp readiness check by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/86

Release v0.4.1 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/88

Full Changelog: https://github.com/awslabs/aws-lambda-web-adapter/compare/v0.4.0...v0.4.1
Source code(tar.gz)
Source code(zip)
v0.4.0(Sep 12, 2022)
Major updates

Support async init for long initialization lambda functions

Add more examples: Rust Axum (Zip) and Next.js (both Zip and Docker)

Refactor main logic into a library

Publish the library to crates.io

What's Changed

Update examples to version 0.3.3 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/52

support async init for long initialization lambda functions by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/53

Add Rust Axum Example by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/56

add next.js example by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/59

fix github build issue by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/60

Fix build command by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/61

fix Adapter Layer Version Permission by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/62

remove python3.6 from compatible runtimes for x86 layer by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/63

Bump next from 12.2.3 to 12.2.4 in /examples/nextjs/app by @dependabot in https://github.com/awslabs/aws-lambda-web-adapter/pull/65

Add Next.js Zip example by @julianbonilla in https://github.com/awslabs/aws-lambda-web-adapter/pull/66

Extract logic into a library. by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/68

Update lambda_http by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/69

add metadata for crates.io by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/70

Add Related projects in README.md by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/71

fix readiness check function by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/72

Fix casing in README by @mnapoli in https://github.com/awslabs/aws-lambda-web-adapter/pull/73

Remove blocking calls by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/74

configure log level with RUST_LOG environment variable by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/75

release v0.4.0 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/76

New Contributors

@dependabot made their first contribution in https://github.com/awslabs/aws-lambda-web-adapter/pull/65

@julianbonilla made their first contribution in https://github.com/awslabs/aws-lambda-web-adapter/pull/66

@mnapoli made their first contribution in https://github.com/awslabs/aws-lambda-web-adapter/pull/73

Full Changelog: https://github.com/awslabs/aws-lambda-web-adapter/compare/v0.3.3...v0.4.0
Source code(tar.gz)
Source code(zip)
v0.3.3(Jul 19, 2022)
What's Changed

Preserve aws-lambda-rust in the user-agent by @calavera in https://github.com/awslabs/aws-lambda-web-adapter/pull/33

Added Spring Boot Zip example by @maschnetwork in https://github.com/awslabs/aws-lambda-web-adapter/pull/34

Update project name in README file by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/37

readness_check_port defaults to port by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/45

readiness check verify the http status code is successful (2xx) by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/46

reduce idle connection pool time to 4 seconds by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/47

treat response body as TEXT when both CONTENT_ENCODING and CONTENT_TY… by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/48

upgrade to Rust 2021 edition by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/49

upgrade to the latest lambda-http crate by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/50

Bump crate version to 0.3.3 by @bnusunny in https://github.com/awslabs/aws-lambda-web-adapter/pull/51

New Contributors

@calavera made their first contribution in https://github.com/awslabs/aws-lambda-web-adapter/pull/33

@maschnetwork made their first contribution in https://github.com/awslabs/aws-lambda-web-adapter/pull/34

Full Changelog: https://github.com/awslabs/aws-lambda-web-adapter/compare/v0.3.2...v0.3.3
Source code(tar.gz)
Source code(zip)
v0.3.2(Mar 29, 2022)
What's Changed

support to remove base path from http request path by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/23

update pipeline to deploy adapter layer in beta and gamma accounts by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/24

update README file by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/25

update expressjs-zip example using the new adapter layer by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/26

make layers public by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/27

update pipeline to publish OCI images to ECR public repo by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/28

prepare to release v0.3.2 by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/29

update Makefile by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/30

update pipeline by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/31

update pipeline by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/32

Full Changelog: https://github.com/aws-samples/aws-lambda-adapter/compare/v0.3.1...v0.3.2
Source code(tar.gz)
Source code(zip)
v0.3.1(Mar 22, 2022)
This is a release for bug fix and minor improvement.

[bugfix] remove stage from URL send to app server

[improvement] Custom User-Agent as aws-lambda-adapter/CARGO-PACKAGE-VERSION

[improvement] Strip the binary to reduce size

Update examples

What's Changed

remove stage from URL send to app server + custom User-Agent by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/22

Full Changelog: https://github.com/aws-samples/aws-lambda-adapter/compare/v0.3.0...v0.3.1
Source code(tar.gz)
Source code(zip)
v0.3.0(Mar 20, 2022)
Upgrade Rust Runtime lambda_http crate to v0.5.1

What's Changed

upgrade to lambda_http v0.5.1 by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/21

[SpringBoot Example] use customized metrics to scale Provisioned Concurrency by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/17

Full Changelog: https://github.com/aws-samples/aws-lambda-adapter/compare/v0.2.0...v0.3.0
Source code(tar.gz)
Source code(zip)
v0.2.0(Feb 7, 2022)
Lambda Adapter as an Extension. Run web app containers on Lambda without changing ENTRYPOINT.

This is a breaking change. Please refer to README for updated usage.

What's Changed

run Lambda Adapter as an extension by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/16

Full Changelog: https://github.com/aws-samples/aws-lambda-adapter/compare/v0.1.2...v0.2.0
Source code(tar.gz)
Source code(zip)
v0.1.2(Jan 31, 2022)
support HTTP compression

What's Changed

Add an example to show how to use Lambda Adapter with managed runtime by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/13

add support for HTTP compression by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/14

Full Changelog: https://github.com/aws-samples/aws-lambda-adapter/compare/v0.1.1...v0.1.2
Source code(tar.gz)
Source code(zip)
v0.1.1(Oct 24, 2021)
New: instruction for compiling the adapter for Gravition2. Bug fix: forward query paramters to application process.

What's Changed

update README by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/6

add instructions for ARM support by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/8

update README for ARM support by @bnusunny in https://github.com/aws-samples/aws-lambda-adapter/pull/9

Full Changelog: https://github.com/aws-samples/aws-lambda-adapter/compare/v0.1.0...v0.1.1
Source code(tar.gz)
Source code(zip)
v0.1.0(Sep 15, 2021)

Initial release
Source code(tar.gz)
Source code(zip)