Testing Lambda container images locally
You can use the Lambda runtime interface emulator to locally test a container image function before uploading it to Amazon Elastic Container Registry (Amazon ECR) and deploying it to Lambda. The emulator is a proxy for the Lambda runtime API. It's a lightweight web server that converts HTTP requests into JSON events to pass to the Lambda function in the container image.
The AWS base images and base images for custom runtimes include the runtime interface emulator. If you use an alternative base image, such as an Alpine Linux or Debian image, you can build the emulator into your image or install it on your local machine.
The runtime interface emulator is available on the AWS GitHub repository
Topics
Guidelines for using the runtime interface emulator
Note the following guidelines when using the runtime interface emulator:
-
The RIE does not emulate Lambda security and authentication configurations, or Lambda orchestration.
Lambda provides an emulator for each of the instruction set architectures.
The emulator does not support AWS X-Ray tracing or other Lambda integrations.
Environment variables
The runtime interface emulator supports a subset of environment variables for the Lambda function in the local running image.
If your function uses security credentials, you can configure the credentials by setting the following environment variables:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
AWS_DEFAULT_REGION
To set the function timeout, configure AWS_LAMBDA_FUNCTION_TIMEOUT
. Enter the maximum number of
seconds that you want to allow the function to run.
The emulator does not populate the following Lambda environment variables. However, you can set them to match the values that you expect when the function runs in the Lambda service:
AWS_LAMBDA_FUNCTION_VERSION
AWS_LAMBDA_FUNCTION_NAME
AWS_LAMBDA_FUNCTION_MEMORY_SIZE
Testing images built from AWS base images
The AWS base images for Lambda include the runtime interface emulator. After building your Docker image, follow these steps to test it locally.
-
Start the Docker image with the docker run command. In this example,
docker-image
is the image name andtest
is the tag.docker run -p 9000:8080
docker-image
:test
This command runs the image as a container and creates a local endpoint at
localhost:9000/2015-03-31/functions/function/invocations
. -
From a new terminal window, post an event to the following endpoint using a curl command:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '
{"payload":"hello world!"}
' -
Get the container ID.
docker ps
-
Use the docker kill
command to stop the container. In this command, replace 3766c4ab331c
with the container ID from the previous step.docker kill
3766c4ab331c
Testing images built from the provided.al2 base image
The base images for custom runtimes include the runtime interface emulator. After building your Docker image, follow these steps to test it locally.
-
Start the Docker image with the docker run command.
This command runs the image as a container and creates a local endpoint at
localhost:9000/2015-03-31/functions/function/invocations
. -
Post an event to the following endpoint using a curl command:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
This command invokes the function with an empty event and returns a response. Some functions might require a JSON payload. Example:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '
{"payload":"hello world!"}
' -
Get the container ID.
docker ps
-
Use the docker kill
command to stop the container. In this command, replace 3766c4ab331c
with the container ID from the previous step.docker kill
3766c4ab331c
Testing images built from alternative base images
If you use an alternative base image, such as an Alpine Linux or Debian image, you can build the emulator into your image or install it on your local machine.
Building the runtime interface emulator into an image
To build the emulator into your image
-
Create a script and save it in your project directory. Set execution permissions for the script file.
The script checks for the presence of the
AWS_LAMBDA_RUNTIME_API
environment variable, which indicates the presence of the runtime API. If the runtime API is present, the script runs the runtime interface client. Otherwise, the script runs the runtime interface emulator.Choose your language to see an example script:
-
Download the runtime interface emulator for your target architecture from GitHub into your project directory. Lambda provides an emulator for each of the instruction set architectures.
curl -Lo aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie \ && chmod +x aws-lambda-rie
To install the arm64 emulator, replace the GitHub repository URL in the previous command with the following:
https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64
-
Copy the script, install the emulator package, and change the
ENTRYPOINT
to the new script by adding the following lines to your Dockerfile.Example — Lines to add to Dockerfile
COPY ./
entry_script.sh
/entry_script.sh
ADD aws-lambda-rie /usr/local/bin/aws-lambda-rie ENTRYPOINT [ "/entry_script.sh
" ] -
Build the Docker image with the docker build
command. The following example names the image docker-image
and gives it thetest
tag. docker build --platform linux/amd64 -t
docker-image
:test
.Note
The command specifies the
--platform linux/amd64
option to ensure that your container is compatible with the Lambda execution environment regardless of the architecture of your build machine. If you intend to create a Lambda function using the ARM64 instruction set architecture, be sure to change the command to use the--platform linux/arm64
option instead. -
Start the Docker image with the docker run command.
This command runs the image as a container and creates a local endpoint at
localhost:9000/2015-03-31/functions/function/invocations
. -
Post an event to the following endpoint using a curl command:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
This command invokes the function with an empty event and returns a response. Some functions might require a JSON payload. Example:
curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '
{"payload":"hello world!"}
' -
Get the container ID.
docker ps
-
Use the docker kill
command to stop the container. In this command, replace 3766c4ab331c
with the container ID from the previous step.docker kill
3766c4ab331c
Install the runtime interface emulator locally
To install the runtime interface emulator on your local machine, download the package for your preferred architecture from GitHub. Then, use the docker run command to start the container image and set
the --entrypoint
to the emulator. For more information, choose the instructions for your preferred language: