Creating Lambda container images
Amazon provides a set of open-source base images that you can use to create your container image. These base images include a runtime interface client to manage the interaction between Lambda and your function code.
For example applications, including a Node.js example and a Python example, see
Container image support for Lambda
To reduce the time it takes for Lambda container functions to become active, see Use multi-stage builds
Note
Container images aren't supported for Lambda functions in the Middle East (UAE) Region.
Topics
Prerequisites
Install the Amazon Command Line Interface (Amazon CLI) version 2 and the Docker CLI
-
The container image must implement the Lambda Runtime API. The Amazon open-source runtime interface clients implement the API. You can add a runtime interface client to your preferred base image to make it compatible with Lambda.
-
The container image must be able to run on a read-only file system. Your function code can access a writable
/tmp
directory with between 512 MB and 10,240 MB, in 1-MB increments, of storage. -
The default Lambda user must be able to read all the files required to run your function code. Lambda follows security best practices by defining a default Linux user with least-privileged permissions. Verify that your application code does not rely on files that other Linux users are restricted from running.
-
Lambda supports only Linux-based container images.
-
Lambda provides multi-architecture base images. However, the image you build for your function must target only one of the architectures. Lambda does not support functions that use multi-architecture container images.
Image types
You can use an Amazon provided base image or an alternative base image, such as Alpine or Debian. Lambda supports any image that conforms to one of the following image manifest formats:
Docker image manifest V2, schema 2 (used with Docker version 1.10 and newer)
Open Container Initiative (OCI) Specifications (v1.0.0 and up)
Lambda supports a maximum uncompressed image size of 10 GB, including all layers.
Container tools
To create your container image, you can use any development tool that supports one of the following container image manifest formats:
Docker image manifest V2, schema 2 (used with Docker version 1.10 and newer)
OCI Specifications (v1.0.0 and up)
For example, you can use the Docker CLI to build, test, and deploy your container images.
Container image settings
Lambda supports the following container image settings in the Dockerfile:
-
ENTRYPOINT – Specifies the absolute path to the entry point of the application.
-
CMD – Specifies parameters that you want to pass in with ENTRYPOINT.
-
WORKDIR – Specifies the absolute path to the working directory.
-
ENV – Specifies an environment variable for the Lambda function.
Note
Lambda ignores the values of any unsupported container image settings in the Dockerfile.
For more information about how Docker uses the container image settings, see ENTRYPOINT
You can specify the container image settings in the Dockerfile when you build your image. You can also override these configurations using the Lambda console or Lambda API. This allows you to deploy multiple functions that deploy the same container image but with different runtime configurations.
Warning
When you specify ENTRYPOINT or CMD in the Dockerfile or as an override, make sure that you enter the absolute path. Also, do not use symlinks as the entry point to the container.
Creating images from Amazon base images
To build a container image for a new Lambda function, you can start with an Amazon base image for Lambda. Lambda provides two types of base images:
-
Multi-architecture base image
Specify one of the main image tags (such as
python:3.9
orjava:11
) to choose this type of image. -
Architecture-specific base image
Specify an image tag with an architecture suffix. For example, specify
3.9-arm64
to choose the arm64 base image for Python 3.9.
You can also use an alternative base image from another container registry. Lambda provides open-source runtime interface clients that you add to an alternative base image to make it compatible with Lambda.
Note
Amazon periodically provides updates to the Amazon base images for Lambda. If your Dockerfile includes the image name in the FROM property, your Docker client pulls the latest version of the image from the Amazon ECR repository. To use the updated base image, you must rebuild your container image and update the function code.
To create an image from an Amazon base image for Lambda
-
On your local machine, create a project directory for your new function.
-
Create a directory named
app
in the project directory, and then add your function handler code to the app directory. -
Use a text editor to create a new Dockerfile.
The Amazon base images provide the following environment variables:
-
LAMBDA_TASK_ROOT=/var/task
-
LAMBDA_RUNTIME_DIR=/var/runtime
Install any dependencies under the ${LAMBDA_TASK_ROOT} directory alongside the function handler to ensure that the Lambda runtime can locate them when the function is invoked.
The following shows an example Dockerfile for Node.js, Python, and Ruby:
-
-
Build your Docker image with the
docker build
command. Enter a name for the image. The following example names the imagehello-world
.docker build -t
hello-world
. -
Start the Docker image with the
docker run
command. For this example, enterhello-world
as the image name.docker run -p 9000:8080
hello-world
-
(Optional) Test your application locally using the runtime interface emulator. From a new terminal window, post an event to the following endpoint using a
curl
command:curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'
This command invokes the function running in the container image and returns a response.
Creating images from alternative base images
Prerequisites
-
The Amazon CLI
-
Docker Desktop
-
Your function code
To create an image using an alternative base image
-
Choose a base image. Lambda supports all Linux distributions, such as Alpine, Debian, and Ubuntu.
-
On your local machine, create a project directory for your new function.
-
Create a directory named
app
in the project directory, and then add your function handler code to the app directory. -
Use a text editor to create a new Dockerfile with the following configuration:
Set the
FROM
property to the URI of the base image.Add instructions to install the runtime interface client.
Set the
ENTRYPOINT
property to invoke the runtime interface client.Set the
CMD
argument to specify the Lambda function handler.
The following example shows a Dockerfile for Python:
# Define function directory ARG FUNCTION_DIR="/function" FROM python:buster as build-image # Install aws-lambda-cpp build dependencies RUN apt-get update && \ apt-get install -y \ g++ \ make \ cmake \ unzip \ libcurl4-openssl-dev # Include global arg in this stage of the build ARG FUNCTION_DIR # Create function directory RUN mkdir -p ${FUNCTION_DIR} # Copy function code COPY app/* ${FUNCTION_DIR} # Install the runtime interface client RUN pip install \ --target ${FUNCTION_DIR} \ awslambdaric # Multi-stage build: grab a fresh copy of the base image FROM python:buster # Include global arg in this stage of the build ARG FUNCTION_DIR # Set working directory to function root directory WORKDIR ${FUNCTION_DIR} # Copy in the build image dependencies COPY --from=build-image ${FUNCTION_DIR} ${FUNCTION_DIR} ENTRYPOINT [ "/usr/local/bin/python", "-m", "awslambdaric" ] CMD [ "app.handler" ]
-
Build your Docker image with the
docker build
command. Enter a name for the image. The following example names the imagehello-world
.docker build -t
hello-world
. -
(Optional) Test your application locally using the Runtime interface emulator.
Upload the image to the Amazon ECR repository
To upload the image to Amazon ECR and create the Lambda function
-
Run the get-login-password
command to authenticate the Docker CLI to your Amazon ECR registry. -
Set the
--region
value to the Amazon Web Services Region where you want to create the Amazon ECR repository. -
Replace
111122223333
with your Amazon Web Services account ID.
aws ecr get-login-password --region
cn-north-1
| docker login --username AWS --password-stdin111122223333
.dkr.ecr.cn-north-1
.amazonaws.com.cn -
-
Create a repository in Amazon ECR using the create-repository
command. aws ecr create-repository --repository-name
hello-world
--image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLEIf successful, you see a response like this:
{ "repository": { "repositoryArn": "arn:aws:ecr:cn-north-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } }
-
Copy the
repositoryUri
from the output in the previous step. -
Run the docker tag
command to tag your local image into your Amazon ECR repository as the latest version. In this command: -
Replace
docker-image:test
with the name and tagof your Docker image. -
Replace the Amazon ECR repository URI with the
repositoryUri
that you copied. Make sure to include:latest
at the end of the URI.
docker tag
docker-image
:test
111122223333
.dkr.ecr.cn-north-1
.amazonaws.com.cn/hello-world
:latest -
-
Run the docker push
command to deploy your local image to the Amazon ECR repository. Make sure to include :latest
at the end of the repository URI.docker push
111122223333
.dkr.ecr.cn-north-1
.amazonaws.com.cn/hello-world
:latest -
Create an execution role for the function, if you don't already have one. You need the Amazon Resource Name (ARN) of the role in the next step.
-
Create the Lambda function. For
ImageUri
, specify the repository URI from earlier. Make sure to include:latest
at the end of the URI.aws lambda create-function \ --function-name
hello-world
\ --package-type Image \ --code ImageUri=111122223333
.dkr.ecr.cn-north-1
.amazonaws.com.cn/hello-world
:latest \ --rolearn:aws:iam::111122223333:role/lambda-ex
-
Invoke the function.
aws lambda invoke --function-name
hello-world
response.jsonYou should see a response like this:
{ "ExecutedVersion": "$LATEST", "StatusCode": 200 }
-
To see the output of the function, check the
response.json
file.
To update the function code, you must create a new image version and store the image in the Amazon ECR repository. For more information, see Updating function code.
Create an image using the Amazon SAM toolkit
You can use the Amazon Serverless Application Model (Amazon SAM) toolkit to create and deploy a function defined as a container image. For a
new project, you can use the Amazon SAM CLI init
command to set up the scaffolding for your project in
your preferred runtime.
In your Amazon SAM template, you set the Runtime
type to Image
and provide the URI of the
base image.
For more information, see Building applications in the Amazon Serverless Application Model Developer Guide.