Skip to content

Latest commit

 

History

History
202 lines (136 loc) · 10.5 KB

configuration-images.md

File metadata and controls

202 lines (136 loc) · 10.5 KB

Configuring functions defined as container images

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

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

Topics

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. The unpublished version is named $LATEST. To view the current function version, choose the function, then choose Qualifiers.

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.

Update the user permissions

Make sure that the permissions for the AWS Identity and Access Management (IAM) 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:<region>:<account>:repository/<repo name>/"
            }
        ]
    }
}

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

  1. Open the Functions page on 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, 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.

    3. (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 (" ").

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

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

  1. Open the Functions page on 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.

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

  1. Open the Functions page on 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 AWS Lambda environment variables.

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.

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 \
    --imageUri <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 AWS::Lambda::Function::ImageConfig resource 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 resource in your AWS CloudFormation template, you must provide values for all three of the ImageConfig properties.

For information about the ImageConfig resource, see ImageConfig in the AWS Serverless Application Model Developer Guide.