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.

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.

Prerequisites

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.

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

Permissions

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": "lambda.amazonaws.com"
        },
        "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.

{"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": "lambda.amazonaws.com"
        },
        "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.

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.

Overriding container settings

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

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

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.

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.

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:

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

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