Create a Lambda function using a container image
Your AWS Lambda function's code consists of scripts or compiled programs and their dependencies. You use a deployment package to deploy your function code to Lambda. Lambda supports two types of deployment packages: container images and .zip file archives.
There are three ways to build a container image for a Lambda function:
-
Using an AWS base image for Lambda
The AWS base images are preloaded with a language runtime, a runtime interface client to manage the interaction between Lambda and your function code, and a runtime interface emulator for local testing.
-
Using an AWS OS-only base image
AWS OS-only base images
contain an Amazon Linux distribution and the runtime interface emulator . These images are commonly used to create container images for compiled languages, such as Go and Rust, and for a language or language version that Lambda doesn't provide a base image for, such as Node.js 19. You can also use OS-only base images to implement a custom runtime. To make the image compatible with Lambda, you must include a runtime interface client for your language in the image. -
You can use an alternative base image from another container registry, such as Alpine Linux or Debian. You can also use a custom image created by your organization. To make the image compatible with Lambda, you must include a runtime interface client for your language in the image.
Tip
To reduce the time it takes for Lambda container functions to become active, see Use multi-stage builds
To create a Lambda function from a container image, build your image locally and upload it to an Amazon Elastic Container Registry (Amazon ECR) repository. Then, specify the repository URI when you create the function. The Amazon ECR repository must be in the same AWS Region as the Lambda function. You can create a function using an image in a different AWS account, as long as the image is in the same Region as the Lambda function. For more information, see Amazon ECR cross-account permissions.
Note
Lambda does not support Amazon ECR FIPS endpoints for container images. If your repository URI includes
ecr-fips
, you are using a FIPS endpoint. Example: 111122223333.dkr.ecr-fips.us-east-1.amazonaws.com
.
This page explains the base image types and requirements for creating Lambda-compatible container images.
Note
You cannot change the deployment package type (.zip or container image) for an existing function. For example, you cannot convert a container image function to use a .zip file archive. You must create a new function.
Topics
Requirements
Install the AWS CLI version 2 and the Docker CLI
-
The container image must implement the Using the Lambda runtime API for custom runtimes. The AWS 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. This means that you don't need to specify a USER
in your Dockerfile. 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.
Using an AWS base image for Lambda
You can use one of the AWS base images
AWS periodically provides updates to the AWS 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
The Node.js 20, Python 3.12, Java 21, .NET 8, Ruby 3.3, and later base images are based on the Amazon Linux 2023 minimal container image. Earlier base images use Amazon Linux 2. AL2023 provides several advantages over Amazon Linux 2, including a smaller deployment footprint and updated versions of libraries such as glibc
.
AL2023-based images use microdnf
(symlinked as dnf
) as the package manager instead of yum
, which is the default package manager in Amazon Linux 2. microdnf
is a standalone implementation of dnf
. For a list of packages that are included in AL2023-based images, refer to the Minimal Container columns in Comparing packages installed on Amazon Linux 2023 Container Images. For more information about the differences between AL2023 and Amazon Linux 2, see Introducing the Amazon Linux 2023 runtime for AWS Lambda
Note
To run AL2023-based images locally, including with AWS Serverless Application Model (AWS SAM), you must use Docker version 20.10.10 or later.
To build a container image using an AWS base image, choose the instructions for your preferred language:
Using an AWS OS-only base image
AWS OS-only base images
Tags | Runtime | Operating system | Dockerfile | Deprecation |
---|---|---|---|---|
al2023 |
OS-only Runtime | Amazon Linux 2023 | Dockerfile
for OS-only Runtime on GitHub |
Not scheduled |
al2 |
OS-only Runtime | Amazon Linux 2 | Dockerfile
for OS-only Runtime on GitHub |
Not scheduled |
Amazon Elastic Container Registry Public Gallery: gallery.ecr.aws/lambda/provided
Using a non-AWS base image
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.
Note
To make the image compatible with Lambda, you must include a runtime interface client for your language in the image.
Runtime interface clients
If you use an OS-only base image or an alternative base image, you must include a runtime interface client in your image. The runtime interface client must extend the Using the Lambda runtime API for custom runtimes, which manages the interaction between Lambda and your function code. AWS provides open-source runtime interface clients for the following languages:
If you're using a language that doesn't have an AWS-provided runtime interface client, you must create your own.
Amazon ECR permissions
Before you create a Lambda function from a container image, you must build the image locally and upload it to an Amazon ECR repository. When you create the function, specify the Amazon ECR repository URI.
Make sure that the permissions for the user or role that creates the function includes GetRepositoryPolicy
and SetRepositoryPolicy
.
For example, use the IAM console to create a role with the following policy:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "ecr:SetRepositoryPolicy", "ecr:GetRepositoryPolicy" ], "Resource": "arn:aws:ecr:
us-east-1
:111122223333
:repository/hello-world
" } ] }
Amazon ECR repository policies
For a function in the same account as the container image in Amazon ECR, you can add ecr:BatchGetImage
and ecr:GetDownloadUrlForLayer
permissions to your Amazon ECR repository policy. The following example shows the
minimum policy:
{ "Sid": "LambdaECRImageRetrievalPolicy", "Effect": "Allow", "Principal": { "Service": "lambda.amazonaws.com" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ] }
For more information about Amazon ECR repository permissions, see Private repository policies in the Amazon Elastic Container Registry User Guide.
If the Amazon ECR repository does not include these permissions, Lambda adds ecr:BatchGetImage
and
ecr:GetDownloadUrlForLayer
to the container image repository permissions. Lambda can add these
permissions only if the principal calling Lambda has ecr:getRepositoryPolicy
and
ecr:setRepositoryPolicy
permissions.
To view or edit your Amazon ECR repository permissions, follow the directions in Setting a private repository policy statement in the Amazon Elastic Container Registry User Guide.
Amazon ECR cross-account permissions
A different account in the same region can create a function that uses a container image owned by your account. In the following example, your Amazon ECR repository permissions policy needs the following statements to grant access to account number 123456789012.
CrossAccountPermission – Allows account 123456789012 to create and update Lambda functions that use images from this ECR repository.
LambdaECRImageCrossAccountRetrievalPolicy – Lambda will eventually set a function's state to inactive if it is not invoked for an extended period. This statement is required so that Lambda can retrieve the container image for optimization and caching on behalf of the function owned by 123456789012.
Example — Add cross-account permission to your repository
{ "Version": "2012-10-17", "Statement": [ { "Sid": "CrossAccountPermission", "Effect": "Allow", "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Principal": { "AWS": "arn:aws:iam::
123456789012
:root" } }, { "Sid": "LambdaECRImageCrossAccountRetrievalPolicy", "Effect": "Allow", "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Principal": { "Service": "lambda.amazonaws.com" }, "Condition": { "StringLike": { "aws:sourceARN": "arn:aws:lambda:us-east-1
:123456789012
:function:*" } } } ] }
To give access to multiple accounts, you add the account IDs to the Principal list in the
CrossAccountPermission
policy and to the Condition evaluation list in the
LambdaECRImageCrossAccountRetrievalPolicy
.
If you are working with multiple accounts in an AWS Organization, we recommend that you enumerate each account ID in the ECR permissions policy. This approach aligns with the AWS security best practice of setting narrow permissions in IAM policies.
In addition to Lambda permissions, the user or role that creates the function must also have BatchGetImage
and GetDownloadUrlForLayer
permissions.
Function lifecycle
After you upload a new or updated container image, Lambda optimizes the image before the function can process invocations. The
optimization process can take a few seconds. The function remains in the Pending
state until the
process completes, when the state transitions to Active
. You can't invoke the function until it reaches the Active
state.
If a function is not invoked for multiple weeks, Lambda reclaims its optimized version, and the function
transitions to the Inactive
state. To reactivate the function, you must invoke it. Lambda rejects the
first invocation and the function enters the Pending
state until Lambda re-optimizes the image. The
function then returns to the Active
state.
Lambda periodically fetches the associated container image from the Amazon ECR repository. If the
corresponding container image no longer exists on Amazon ECR or permissions are revoked, the function enters the Failed
state, and
Lambda returns a failure for any function invocations.
You can use the Lambda API to get information about a function's state. For more information, see Lambda function states.