https://github.com/awslabs/aws-lambda-web-adapter Skip to content Navigation Menu Toggle navigation Sign in * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + GitHub Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code Explore + All features + Documentation + GitHub Skills + Blog * Solutions For + Enterprise + Teams + Startups + Education By Solution + CI/CD & Automation + DevOps + DevSecOps Resources + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} awslabs / aws-lambda-web-adapter Public * Notifications You must be signed in to change notification settings * Fork 96 * Star 1.4k * Run web applications on AWS Lambda License Apache-2.0 license 1.4k stars 96 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 5 * Pull requests 3 * Discussions * Actions * Projects 0 * Security * Insights Additional navigation options * Code * Issues * Pull requests * Discussions * Actions * Projects * Security * Insights awslabs/aws-lambda-web-adapter This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main BranchesTags Go to file Code Folders and files Name Name Last commit Last commit message date Latest commit History 418 Commits .cargo .cargo .config .config .github/workflows .github/workflows docs docs examples examples layer layer src src tests tests .dockerignore .dockerignore .gitallowed .gitallowed .gitattributes .gitattributes .gitignore .gitignore .rustfmt.toml .rustfmt.toml CHANGELOG.md CHANGELOG.md CODE_OF_CONDUCT.md CODE_OF_CONDUCT.md CONTRIBUTING.md CONTRIBUTING.md Cargo.lock Cargo.lock Cargo.toml Cargo.toml LICENSE LICENSE Makefile Makefile NOTICE NOTICE README.md README.md template-arm64.yaml template-arm64.yaml template-x86_64.yaml template-x86_64.yaml View all files Repository files navigation * README * Code of conduct * Apache-2.0 license * Security AWS Lambda Web Adapter A tool to run web applications on AWS Lambda AWS Lambda Web Adapter allows developers to build web apps (http api) with familiar frameworks (e.g. Express.js, Next.js, Flask, SpringBoot, ASP.NET and Laravel, anything speaks HTTP 1.1/1.0) and run it on AWS Lambda. The same docker image can run on AWS Lambda, Amazon EC2, AWS Fargate, and local computers. Lambda Web Adapter Features * Run web applications on AWS Lambda * Supports Amazon API Gateway Rest API and Http API endpoints, Lambda Function URLs, and Application Load Balancer * Supports Lambda managed runtimes, custom runtimes and docker OCI images * Supports any web frameworks and languages, no new code dependency to include * Automatic encode binary response * Enables graceful shutdown * Supports response payload compression * Supports response streaming * Supports non-http event triggers Usage AWS Lambda Web Adapter work with Lambda functions packaged as both docker images and Zip packages. Lambda functions packaged as Docker Images or OCI Images To use Lambda Web Adapter with docker images, package your web app (http api) in a Dockerfile, and add one line to copy Lambda Web Adapter binary to /opt/extensions inside your container: COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.3 /lambda-adapter /opt/extensions/lambda-adapter Non-AWS base images may be used since the Runtime Interface Client ships with the Lambda Web Adapter. By default, Lambda Web Adapter assumes the web app is listening on port 8080. If not, you can specify the port via configuration. Pre-compiled Lambda Web Adapter binaries are provided in ECR public repo: public.ecr.aws/awsguru/aws-lambda-adapter. Multi-arch images are also provided in this repo. It works on both x86_64 and arm64 CPU architecture. Below is a Dockerfile for an example nodejs application. FROM public.ecr.aws/docker/library/node:20-slim COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.8.3 /lambda-adapter /opt/extensions/lambda-adapter ENV PORT=7000 WORKDIR "/var/task" ADD src/package.json /var/task/package.json ADD src/package-lock.json /var/task/package-lock.json RUN npm install --omit=dev ADD src/ /var/task CMD ["node", "index.js"] This works with any base images except AWS managed base images. To use AWS managed base images, you need to override the ENTRYPOINT to start your web app. Lambda functions packaged as Zip package for AWS managed runtimes AWS Lambda Web Adapter also works with AWS managed Lambda runtimes. You need to do three things: 1. attach Lambda Web Adapter layer to your function. AWS Commercial Regions 1. x86_64: arn:aws:lambda:$ {AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:22 2. arm64: arn:aws:lambda:$ {AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:22 AWS China Regions 1. cn-north-1 (Beijing) o x86_64: arn:aws-cn:lambda:cn-north-1:041581134020:layer:LambdaAdapterLayerX86:22 2. cn-northwest-1 (Ningxia) o x86_64: arn:aws-cn:lambda:cn-northwest-1:069767869989:layer:LambdaAdapterLayerX86:22 2. configure Lambda environment variable AWS_LAMBDA_EXEC_WRAPPER to /opt/bootstrap. 3. set function handler to your web application start up script. e.g. run.sh. For details, please check out the example Node.js application. Readiness Check When a new Lambda Execution Environment starts up, Lambda Web Adapter will boot up as a Lambda Extension, followed by the web application. By default, Lambda Web Adapter will send HTTP GET requests to the web application at http://127.0.0.1:8080/. The port and path can be customized with two environment variables: AWS_LWA_READINESS_CHECK_PORT and AWS_LWA_READINESS_CHECK_PATH. Lambda Web Adapter will retry this request every 10 milliseconds until the web application returns an HTTP response (status code >= 100 and < 500) or the function times out. In addition, you can configure the adapter to preform readiness check with TCP connect, by setting AWS_LWA_READINESS_CHECK_PROTOCOL to tcp. After passing readiness check, Lambda Web Adapter will start Lambda Runtime and forward the invokes to the web application. Configurations The readiness check port/path and traffic port can be configured using environment variables. These environment variables can be defined either within docker file or as Lambda function configuration. Environment Variable Description Default AWS_LWA_PORT / PORT* traffic port "8080" AWS_LWA_READINESS_CHECK_PORT / readiness check READINESS_CHECK_PORT* port, default to PORT the traffic port AWS_LWA_READINESS_CHECK_PATH / readiness check "/" READINESS_CHECK_PATH* path readiness check AWS_LWA_READINESS_CHECK_PROTOCOL / protocol: "http" "http" READINESS_CHECK_PROTOCOL* or "tcp", default is "http" The minimum HTTP AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS status code that "500" is considered unhealthy enable asynchronous AWS_LWA_ASYNC_INIT / ASYNC_INIT* initialization for "false" long initialization functions the base path to AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH* be removed from None request path enable gzip AWS_LWA_ENABLE_COMPRESSION compression for "false" response body Lambda function invoke mode: AWS_LWA_INVOKE_MODE "buffered" or "buffered" "response_stream", default is "buffered" the path for receiving event AWS_LWA_PASS_THROUGH_PATH payloads that are "/events" passed through from non-http triggers Note: We use "AWS_LWA_" prefix to namespacing all environment variables used by Lambda Web Adapter. The original ones will be supported until we reach version 1.0. AWS_LWA_PORT / PORT - Lambda Web Adapter will send traffic to this port. This is the port your web application listening on. Inside Lambda execution environment, the web application runs as a non-root user, and not allowed to listen on ports lower than 1024. Please also avoid port 9001 and 3000. Lambda Runtime API is on port 9001. CloudWatch Lambda Insight extension uses port 3000. AWS_LWA_ASYNC_INIT / ASYNC_INIT - Lambda managed runtimes offer up to 10 seconds for function initialization. During this period of time, Lambda functions have burst of CPU to accelerate initialization, and it is free. If a lambda function couldn't complete the initialization within 10 seconds, Lambda will restart the function, and bill for the initialization. To help functions to use this 10 seconds free initialization time and avoid the restart, Lambda Web Adapter supports asynchronous initialization. When this feature is enabled, Lambda Web Adapter performs readiness check up to 9.8 seconds. If the web app is not ready by then, Lambda Web Adapter signals to Lambda service that the init is completed, and continues readiness check in the handler. This feature is disabled by default. Enable it by setting environment variable AWS_LWA_ASYNC_INIT to true. AWS_LWA_REMOVE_BASE_PATH / REMOVE_BASE_PATH - The value of this environment variable tells the adapter whether the application is running under a base path. For example, you could have configured your API Gateway to have a /orders/{proxy+} and a /catalog/{proxy+} resource. Each resource is handled by a separate Lambda functions. For this reason, the application inside Lambda may not be aware of the fact that the /orders path exists. Use REMOVE_BASE_PATH to remove the /orders prefix when routing requests to the application. Defaults to empty string. Checkout SpringBoot example. AWS_LWA_ENABLE_COMPRESSION - Lambda Web Adapter supports gzip compression for response body. This feature is disabled by default. Enable it by setting environment variable AWS_LWA_ENABLE_COMPRESSION to true. When enabled, this will compress responses unless it's an image as determined by the content-type starting with image or the response is less than 32 bytes. This will also compress HTTP/1.1 chunked streaming response. AWS_LWA_INVOKE_MODE - Lambda function invoke mode, this should match Function Url invoke mode. The default is "buffered". When configured as "response_stream", Lambda Web Adapter will stream response to Lambda service blog. Please check out FastAPI with Response Streaming example. AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS - allows you to customize which HTTP status codes are considered healthy and which ones are not AWS_LWA_PASS_THROUGH_PATH - Path to receive events payloads passed through from non-http event triggers. The default is "/events". Request Context Request Context is metadata API Gateway sends to Lambda for a request. It usually contains requestId, requestTime, apiId, identity, and authorizer. Identity and authorizer are useful to get client identity for authorization. API Gateway Developer Guide contains more details here. Lambda Web Adapter forwards this information to the web application in a Http Header named "x-amzn-request-context". In the web application, you can retrieve the value of this http header and deserialize it into a JSON object. Check out Express.js in Zip on how to use it. Lambda Context Lambda Context is an object that Lambda passes to the function handler. This object provides information about the invocation, function, and execution environment. You can find a full list of properties accessible through the Lambda Context here Lambda Web Adapter forwards this information to the web application in a Http Header named "x-amzn-lambda-context". In the web application, you can retrieve the value of this http header and deserialize it into a JSON object. Check out Express.js in Zip on how to use it. Graceful Shutdown For a function with Lambda Extensions registered, Lambda enables shutdown phase for the function. When Lambda service is about to shut down a Lambda execution environment, it sends a SIGTERM signal to the runtime and then a SHUTDOWN event to each registered external extensions. Developers could catch the SIGTERM signal in the lambda functions and perform graceful shutdown tasks. The Express.js gives a simple example. More details in this repo. Local Debugging Lambda Web Adapter allows developers to develop web applications locally with familiar tools and debuggers: just run the web app locally and test it. If you want to simulate Lambda Runtime environment locally, you can use AWS SAM CLI. The following command starts a local api gateway endpoint and simulate the Lambda runtime execution environment. sam local start-api Please note that sam local starts a Lambda Runtime Interface Emulator on port 8080. So your web application should avoid port 8080 if you plan to use sam local. Non-HTTP Event Triggers The Lambda Web Adapter also supports all non-HTTP event triggers, such as SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge, and Bedrock Agents. The adapter forwards the event payload to the web application via http post to a path defined by the AWS_LWA_PASS_THROUGH_PATH environment variable. By default, this path is set to /events. Upon receiving the event payload from the request body, the web application should processes it and returns the results as a JSON response. Please checkout SQS Express.js and Bedrock Agent FastAPI in Zip examples. Examples * FastAPI * FastAPI in Zip * FastAPI with Background Tasks * FastAPI with Response Streaming * FastAPI with Response Streaming in Zip * Flask * Flask in Zip * Serverless Django by @efi-mk * Express.js * Express.js in Zip * Next.js * Next.js in Zip * Next.js Response Streaming * SpringBoot * SpringBoot in Zip * SpringBoot Response Streaming * Nginx * PHP * Rust Actix Web in Zip * Rust Axum in Zip * Golang Gin * Golang Gin in Zip * Deno Oak in Zip * Laravel on Lambda * ASP.NET MVC * ASP.NET MVC in Zip * ASP.NET Web API in Zip * SQS Express.js * Bedrock Agent FastAPI * Bedrock Agent FastAPI in Zip Acknowledgement This project was inspired by several community projects. * re:Web * Serverlessish Similar Projects Several projects also provide similar capabilities as language specific packages/frameworks. * Serverless Java Container * Serverless Express * Serverless Python - Zappa * Serverless Rails - Lamby * Serverless PHP - Bref Security See CONTRIBUTING for more information. License This project is licensed under the Apache-2.0 License. About Run web applications on AWS Lambda Topics lambda aws-lambda Resources Readme License Apache-2.0 license Code of conduct Code of conduct Security policy Security policy Activity Custom properties Stars 1.4k stars Watchers 31 watching Forks 96 forks Report repository Releases 24 v0.8.3 Latest Apr 21, 2024 + 23 releases Packages 0 No packages published Contributors 30 * * * * * * * * * * * * * * + 16 contributors Languages * Rust 96.5% * Makefile 3.0% * Other 0.5% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.