AWS Lambda Web Adapter

AWS Lambda Web Adapter allows you to run web applications built with any framework that supports HTTP 1.1 or 1.0 (such as Express.js, Next.js, Flask, SpringBoot, ASP.NET, or Laravel) on AWS Lambda with zero code changes.

Key capabilities include:

• Compatibility: Works with Amazon API Gateway (REST & HTTP API), Lambda Function URLs, and Application Load Balancer.
• Deployment Flexibility: Supports Lambda managed runtimes, custom runtimes, and Docker OCI images. The same Docker image can be used on AWS Lambda, Amazon EC2, AWS Fargate, or local machines.
• Advanced Features: Automatic binary response encoding, graceful shutdown, response payload compression (gzip/brotli), response streaming, and multi-tenancy via tenant ID propagation.
• Trigger Support: Supports non-HTTP event triggers like SQS, SNS, S3, DynamoDB, Kinesis, Kafka, EventBridge, and Bedrock Agents.

AWS Lambda Web Adapter acts as a bridge between AWS Lambda triggers and standard HTTP web applications. It supports triggers from Amazon API Gateway Rest API, Http API (v2 event format), and Application Load Balancer.

Core Workflow:

1. Event Conversion: It converts incoming AWS Lambda events into standard HTTP requests and forwards them to your web application.
2. Response Conversion: It converts the HTTP response from your application back into a valid AWS Lambda event response.
3. Deployment Flexibility: Because it operates as a Lambda Extension, it only runs when deployed within the AWS Lambda service. When running in other environments (like AWS Fargate or Amazon EC2), the adapter does not run, allowing you to use the exact same container image across different compute platforms without code changes.

The AWS Lambda Web Adapter uses a readiness check to determine when your web application is ready to receive traffic. During startup, the adapter boots as a Lambda Extension and then attempts to reach your application.

By default, the adapter performs the following steps:

1. Sends HTTP GET requests to your app at http://127.0.0.1:8080/.
2. Retries every 10 milliseconds.
3. Considers the app ready once it receives an HTTP response with a status code $\ge 100$ and $< 500$.
4. Starts the Lambda runtime client and begins forwarding invocations.

If your application is not ready, the adapter will continue retrying until the condition is met.

The adapter acts as a bridge between Lambda's event-driven model and traditional HTTP web applications. It follows this lifecycle for every request:

1. Event Conversion: Lambda receives an event (from API Gateway, ALB, etc.), and the adapter converts it into a standard HTTP request.
2. Forwarding: The HTTP request is forwarded to your web application on its configured port.
3. Response Conversion: Your app returns an HTTP response, which the adapter converts back into a Lambda event response.
4. Return: Lambda returns the response to the original caller.

To simulate the AWS Lambda and API Gateway environment locally, use the SAM CLI. This allows you to test your web app using curl, Postman, or a web browser.

sam local start-api --warm-containers EAGER --region <your-region>

Note: Replace <your-region> with the actual AWS region you are using.

sam local start-api --warm-containers EAGER --region us-west-2

Use the sam logs command to retrieve logs from your deployed Lambda functions directly in your terminal. This is useful for troubleshooting.

To fetch logs for a specific function and stream them (tailing), use the following command structure:

sam logs -n <FunctionName> --stack-name <StackName> --tail

sam logs -n HelloWorldFunction --stack-name nextjs-zip --tail

You can build and deploy the provided Express.js example using the AWS SAM CLI. After deployment, the output will provide the API Gateway endpoint URL (e.g., HelloWorldApi).

sam build
sam deploy --guided

To run a FastAPI application on AWS Lambda, you must include the Lambda Web Adapter binary in your container image. The adapter is placed in /opt/extensions/lambda-adapter.

In your Dockerfile, copy the binary from the official image and set the PORT environment variable to match your application's listening port. It is also recommended to set AWS_LWA_READINESS_CHECK_PROTOCOL=tcp for readiness checks.

FROM public.ecr.aws/docker/library/python:3.12.0-slim
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:1.0.1 /lambda-adapter /opt/extensions/lambda-adapter
ENV PORT=8000 AWS_LWA_READINESS_CHECK_PROTOCOL=tcp 
WORKDIR /var/task
COPY requirements.txt ./
RUN python -m pip install -r requirements.txt
COPY *.py ./
CMD exec uvicorn --port=$PORT main:app

Use the AWS SAM CLI to build and deploy the example project.

sam build --use-container
sam deploy --guided

To run a PHP application on AWS Lambda, you must attach a PHP layer that provides the PHP binary and a wrapper script. Choose the ARN based on your Lambda function's architecture:

• x86_64: arn:aws:lambda:${AWS::Region}:753240598075:layer:Php82FpmNginxX86:13
• arm64: arn:aws:lambda:${AWS::Region}:753240598075:layer:Php82FpmNginxArm:13

To use the adapter with a Zip-based Lambda function, follow these three steps:

1. Attach the Lambda Web Adapter layer to your function using the appropriate ARN for your architecture:
   • x86_64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:28
   • arm64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:28
2. Set the environment variable AWS_LAMBDA_EXEC_WRAPPER to /opt/bootstrap.
3. Set the function handler to your application's startup script (e.g., run.sh).