Working with Lambda container images - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Working with Lambda container images

Your Amazon 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:

Tip

To reduce the time it takes for Lambda container functions to become active, see Use multi-stage builds in the Docker documentation. To build efficient container images, follow the Best practices for writing Dockerfiles.

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 Amazon Web Services Region as the Lambda function. You can create a function using an image in a different Amazon account, as long as the image is in the same Region as the Lambda function. For more information, see Amazon ECR cross-account permissions.

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.

Requirements

Install the Amazon Command Line Interface (Amazon CLI) version 2 and the Docker CLI. Additionally, note the following requirements:

  • 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.

Using an Amazon base image for Lambda

You can use one of the Amazon base images for Lambda to build the container image for your function code. The base images are preloaded with a language runtime and other components required to run a container image on Lambda. You add your function code and dependencies to the base image and then package it as a container image.

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.

The Node.js 20, Python 3.12, Java 21, AL2023, 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 Amazon Lambda on the Amazon Compute Blog.

Note

To run AL2023-based images locally, including with Amazon Serverless Application Model (Amazon SAM), you must use Docker version 20.10.10 or later.

To build a container image using an Amazon base image, choose the instructions for your preferred language:

Using an Amazon OS-only base image

Amazon 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.

Tags Runtime Operating system Dockerfile Deprecation

al2023

OS-only Runtime Amazon Linux 2023 Dockerfile for OS-only Runtime on GitHub

al2

OS-only Runtime Amazon Linux 2 Dockerfile for OS-only Runtime on GitHub

Amazon Elastic Container Registry Public Gallery: gallery.ecr.aws/lambda/provided

Using a non-Amazon 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 Lambda runtime API, which manages the interaction between Lambda and your function code. Amazon provides open-source runtime interface clients for the following languages:

If you're using a language that doesn't have an Amazon-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 contain the Amazon managed policies 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 Amazon Organization, we recommend that you enumerate each account ID in the ECR permissions policy. This approach aligns with the Amazon security best practice of setting narrow permissions in IAM policies.

Container image settings

The following are common container image settings. If you use these settings in your Dockerfile, note how Lambda interprets and processes these settings:

  • 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.

For more information about how Docker uses the container image settings, see ENTRYPOINT in the Dockerfile reference on the Docker Docs website. For more information about using ENTRYPOINT and CMD, see Demystifying ENTRYPOINT and CMD in Docker on the Amazon Open Source Blog.

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.

To override the configuration values in the container image
  1. Open the Functions page of the Lambda console.

  2. Choose the function to update.

  3. Under Image configuration, choose Edit.

  4. Enter new values for any of the override settings, and then choose Save.

  5. (Optional) To add or override environment variables, under Environment variables, choose Edit.

For more information, see Using Lambda environment variables.