Deploying Lambda functions as 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).

Deploying Lambda functions as container images

When you create a Lambda function, you package your function code into a deployment package. Lambda supports two types of deployment packages: container images and .zip file archives. The workflow to create a function is different depending on the deployment package type. To configure a function defined as a .zip file archive, see Deploying Lambda functions as .zip file archives.

You can use the Lambda console and the Lambda API to create a function defined as a container image, update and test the image code, and configure other function settings.


You cannot convert an existing .zip file archive function to use a container image. You must create a new function.

When you select an image using an image tag, Lambda translates the tag to the underlying image digest. To retrieve the digest for your image, use the GetFunctionConfiguration API operation. To update the function to a newer image version, you must use the Lambda console to update the function code, or use the UpdateFunctionCode API operation. Configuration operations such as UpdateFunctionConfiguration do not update the function's container image.


To complete the following steps, you need the Amazon Command Line Interface (Amazon CLI) version 2. Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.0.57 Python/3.7.4 Darwin/19.6.0 exe/x86_64

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager.


In Windows, some Bash CLI commands that you commonly use with Lambda (such as zip) are not supported by the operating system's built-in terminals. To get a Windows-integrated version of Ubuntu and Bash, install the Windows Subsystem for Linux. Example CLI commands in this guide use Linux formatting. Commands which include inline JSON documents must be reformatted if you are using the Windows CLI.

Before you create the function, you must create a container image and upload it to Amazon ECR.


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-cn:ecr:<region>:<account>:repository/<repo name>/" } ] }

Amazon ECR permissions

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. The following example shows the minimum policy:

{ "Sid": "LambdaECRImageRetrievalPolicy", "Effect": "Allow", "Principal": { "Service": "" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ] }

For more information about Amazon ECR repository permissions, see 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 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-cn:iam::123456789012:root" } }, { "Sid": "LambdaECRImageCrossAccountRetrievalPolicy", "Effect": "Allow", "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Principal": { "Service": "" }, "Condition": { "StringLike": { "aws:sourceARN": "arn:aws-cn: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.

Creating the function

To create a function defined as a container image, you must first create the image and then store the image in the Amazon ECR repository.

To create the function
  1. Open the Functions page of the Lambda console.

  2. Choose Create function.

  3. Choose the Container image option.

  4. Under Basic information, do the following:

    1. For Function name, enter the function name.

    2. For Container image URI, provide a container image that is compatible with the instruction set architecture that you want for your function code.

      You can enter the Amazon ECR image URI or browse for the Amazon ECR image.

      • Enter the Amazon ECR image URI.

      • Or, to browse an Amazon ECR repository for the image, choose Browse images. Select the Amazon ECR repository from the dropdown list, and then select the image.

  5. (Optional) To override configuration settings that are included in the Dockerfile, expand Container image overrides. You can override any of the following settings:

    • For Entrypoint, enter the full path of the runtime executable. The following example shows an entrypoint for a Node.js function:

      "/usr/bin/npx", "aws-lambda-ric"
    • For Command, enter additional parameters to pass in to the image with Entrypoint. The following example shows a command for a Node.js function:

    • For Working directory, enter the full path of the working directory for the function. The following example shows the working directory for an Amazon base image for Lambda:


    For the override settings, make sure that you enclose each string in quotation marks (" ").

  6. (Optional) For Architecture, choose the instruction set architecture for the function. The default architecture is x86_64. Note: when you build the container image for your function, make sure that it is compatible with this instruction set architecture.

  7. (Optional) Under Permissions, expand Change default execution role. Then, choose to create a new Execution role, or to use an existing role.

  8. Choose Create function.

Lambda creates your function and an execution role that grants the function permission to upload logs. Lambda assumes the execution role when you invoke your function, and uses the execution role to create credentials for the Amazon SDK and to read data from event sources.

When you deploy code as a container image to a Lambda function, the image undergoes an optimization process for running on Lambda. This process can take a few seconds, during which the function is in pending state. When the optimization process completes, the function enters the active state.

Testing the function

Invoke your Lambda function using the sample event data provided in the console.

To invoke a function
  1. After selecting your function, choose the Test tab.

  2. For Test event action, choose Create new event.

  3. For Event name, enter a name for the test event.

  4. For Event sharing settings, choose Private.

  5. For Template, leave the default hello-world option.

  6. Choose Save changes, and then choose Test. Lambda runs your function on your behalf. The function handler receives and then processes the sample event.

  7. Review the Execution result and Details:

    • The Summary section shows the key information from the REPORT line in the invocation log.

    • The Log output section shows the complete invocation log. Lambda writes all invocation logs to Amazon CloudWatch.

Overriding container settings

You can use the Lambda console or the Lambda API to override the following container image settings:

  • ENTRYPOINT – Specifies the absolute path of the entry point to the application.

  • CMD – Specifies parameters that you want to pass in with ENTRYPOINT.

  • WORKDIR – Specifies the absolute path of the working directory.

  • ENV – Specifies an environment variable for the Lambda function.

Any values that you provide in the Lambda console or the Lambda API override the values in the Dockerfile.

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 Amazon Lambda environment variables.

Updating function code

After you deploy a container image to a function, the image is read-only. To update the function code, you must first deploy a new image version. Create a new image version, and then store the image in the Amazon ECR repository.

To configure the function to use an updated container image
  1. Open the Functions page of the Lambda console.

  2. Choose the function to update.

  3. Under Image, choose Deploy new image.

  4. Choose Browse images.

  5. In the Select container image dialog box, select the Amazon ECR repository from the dropdown list, and then select the new image version.

  6. Choose Save.

Function version $LATEST

When you publish a function version, the code and most of the configuration settings are locked to maintain a consistent experience for users of that version. You can change the code and many configuration settings only on the unpublished version of the function. By default, the console displays configuration information for the unpublished version of the function. To view the versions of a function, choose Qualifiers. The unpublished version is named $LATEST.

Note that Amazon Elastic Container Registry (Amazon ECR) also uses a latest tag to denote the latest version of the container image. Be careful not to confuse this tag with the $LATEST function version.

For more information about managing versions, see Lambda function versions.

Using the Lambda API

To manage functions defined as container images, use the following API operations:

To create a function defined as container image, use the create-function command. Set the package-type to Image and specify your container image URI using the code parameter.

When you create the function, you can specify the instruction set architecture. The default architecture is x86-64. Make sure that the code in your container image is compatible with the architecture.

You can create the function from the same account as the container registry or from a different account in the same region as the container registry in Amazon ECR. For cross-account access, adjust the Amazon ECR permissions for the image.

aws lambda create-function --region sa-east-1 --function-name my-function \ --package-type Image \ --code ImageUri=<ECR Image URI> \ --role arn:aws-cn:iam::123456789012:role/lambda-ex

To update the function code, use the update-function-code command. Specify the container image location using the image-uri parameter.


You cannot change the package-type of a function.

aws lambda update-function-code --region sa-east-1 --function-name my-function \ --image-uri <ECR Image URI> \

To update the function parameters, use the update-function-configuration operation. Specify EntryPoint and Command as arrays of strings, and WorkingDirectory as a string.

aws lambda update-function-configuration --function-name my-function \ --image-config '{"EntryPoint": ["/usr/bin/npx", "aws-lambda-ric"], \ "Command": ["app.handler"] , \ "WorkingDirectory": "/var/task"}'

Amazon CloudFormation

You can use Amazon CloudFormation to create Lambda functions defined as container images. In your Amazon CloudFormation template, the AWS::Lambda::Function resource specifies the Lambda function. For descriptions of the properties in the AWS::Lambda::Function resource, see AWS::Lambda::Function in the Amazon CloudFormation User Guide.

In the AWS::Lambda::Function resource, set the following properties to create a function defined as a container image:

  • AWS::Lambda::Function

    • PackageType – Set to Image.

    • Code – Enter your container image URI in the ImageUri field.

    • ImageConfig – (Optional) Override the container image configuration properties.

The ImageConfig property in AWS::Lambda::Function contains the following fields:

  • Command – Specifies parameters that you want to pass in with EntryPoint.

  • EntryPoint – Specifies the entry point to the application.

  • WorkingDirectory – Specifies the working directory.


If you declare an ImageConfig property in your Amazon CloudFormation template, you must provide values for all three of the ImageConfig properties.

For more information, see ImageConfig in the Amazon CloudFormation User Guide.