Working with Lambda container images

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 base image for custom runtimes

  AWS provides base images that contain the Amazon Linux or Amazon Linux 2 operating system and the runtime interface emulator. You can add your preferred runtime, dependencies, and code to these images. To make the image compatible with Lambda, you must include a runtime interface client for your language in the image.

• Using a non-AWS base 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 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.

This page explains the base image types and requirements for creating Lambda-compatible container images.

Requirements

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

• The container image must implement the Lambda runtime API. 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. 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 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.

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. To use the updated base image, you must rebuild your container image and update the function code.

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

• Node.js

• TypeScript (uses a Node.js base image)

• Python

• Java

• Go

• .NET

• Ruby

Using an AWS base image for custom runtimes

AWS provides base images that contain the Amazon Linux or Amazon Linux 2 operating system and the runtime interface emulator. You can add your preferred runtime, dependencies, and code to these images. 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
al2	Custom Runtime	Amazon Linux 2	Dockerfile for Custom Runtime on GitHub
alami	Custom Runtime	Amazon Linux	Dockerfile for Custom Runtime on GitHub	Dec 31, 2023

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 a base image for custom runtimes 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. AWS provides open-source runtime interface clients for the following languages:

• Node.js

• Python

• Java

• .NET

• Go

• Ruby

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 contain the AWS 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 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.

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