Creating Lambda functions defined 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 Creating Lambda functions defined 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.

Note
You cannot convert an existing container image function to use a .zip file archive. 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.

Note
In Amazon ECR, if you reassign the image tag to another image, Lambda does not update the image version.

Topics

Function version $LATEST
Container image deployment
Amazon ECR permissions
Override the container settings
Creating a function (console)
Updating the function code (console)
Overriding the image parameters (console)
Using the Lambda API
AWS CloudFormation

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.

Container image deployment

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.

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.

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.

Override the 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.

Creating a function (console)

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

Open the Functions page on the Lambda console.
Choose Create function.
Choose the Container image option.
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.
(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:
```
"app.handler"
```
- For Working directory, enter the full path of the working directory for the function. The following example shows the working directory for an AWS base image for Lambda:
```
"/var/task"
```

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

(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.
(Optional) Under Permissions, expand Change default execution role. Then, choose to create a new Execution role, or to use an existing role.
Choose Create function.

Updating the function code (console)

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

Open the Functions page on the Lambda console.
Choose the function to update.
Under Image, choose Deploy new image.
Choose Browse images.
In the Select container image dialog box, select the Amazon ECR repository from the dropdown list, and then select the new image version.
Choose Save.

Overriding the image parameters (console)

You can use the Lambda console to override the configuration values in the container image.

To override the configuration values in the container image

Open the Functions page on the Lambda console.
Choose the function to update.
Under Image configuration, choose Edit.
Enter new values for any of the override settings, and then choose Save.
(Optional) To add or override environment variables, under Environment variables, choose Edit.

For more information, see Using AWS Lambda environment variables.

Using the Lambda API

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

CreateFunction
UpdateFunctionCode
UpdateFunctionConfiguration

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

Note
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"}'

AWS CloudFormation

You can use AWS CloudFormation to create Lambda functions defined as container images. In your AWS 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 AWS 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.

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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

configuration-images.md

configuration-images.md

Creating Lambda functions defined as container images

Function version $LATEST

Container image deployment

Amazon ECR permissions

Amazon ECR cross-account permissions

Override the container settings

Creating a function (console)

Updating the function code (console)

Overriding the image parameters (console)

Using the Lambda API

AWS CloudFormation

Files

configuration-images.md

Latest commit

History

configuration-images.md

File metadata and controls

Creating Lambda functions defined as container images

Function version $LATEST

Container image deployment

Amazon ECR permissions

Amazon ECR cross-account permissions

Override the container settings

Creating a function (console)

Updating the function code (console)

Overriding the image parameters (console)

Using the Lambda API

AWS CloudFormation