To reduce the time it takes for Lambda container functions to become active, seeUse multi-stage builds in the Docker documentation. To build efficient container images, follow theBest practices for writing Dockerfiles.

To run AL2023-based images locally, including with AWS Serverless Application Model (AWS SAM), you must use Docker version 20.10.10 or later.

• AWS CLI version 2

• Docker (minimum version 25.0.0)

• The Dockerbuildx plugin.

• Python

1. Create a directory for the project, and then switch to that directory.

   mkdir examplecd example

2. Create a new file calledlambda_function.py. You can add the following sample function code to the file for testing, or use your own.

   Example Python function

   import sysdef handler(event, context):    return 'Hello from AWS Lambda using Python' + sys.version + '!'

3. Create a new file calledrequirements.txt. If you're using the sample function code from the previous step, you can leave the file empty because there are no dependencies. Otherwise, list each required library. For example, here's what yourrequirements.txt should look like if your function uses the AWS SDK for Python (Boto3):

   Example requirements.txt

   boto3

4. Create a new Dockerfile with the following configuration:

   • Set theFROM property to theURI of the base image.

   • Use the COPY command to copy the function code and runtime dependencies to{LAMBDA_TASK_ROOT}, aLambda-defined environment variable.

   • Set theCMD argument to the Lambda function handler.

   Note that the example Dockerfile does not include aUSER instruction. When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to theroot user when noUSER instruction is provided.

   Example Dockerfile

   FROM public.ecr.aws/lambda/python:3.12# Copy requirements.txtCOPY requirements.txt ${LAMBDA_TASK_ROOT}# Install the specified packagesRUN pip install -r requirements.txt# Copy function codeCOPY lambda_function.py ${LAMBDA_TASK_ROOT}# Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile)CMD [ "lambda_function.handler" ]

5. Build the Docker image with thedocker build command. The following example names the imagedocker-image and gives it thetesttag. To make your image compatible with Lambda, you must use the--provenance=false option.

   docker buildx build --platform linux/amd64 --provenance=false -tdocker-image:test .

   Note

   The command specifies the--platform linux/amd64 option to ensure that your container is compatible with the Lambda execution environment regardless of the architecture of your build machine. If you intend to create a Lambda function using the ARM64 instruction set architecture, be sure to change the command to use the--platform linux/arm64 option instead.

1. Start the Docker image with thedocker run command. In this example,docker-image is the image name andtest is the tag.

   docker run --platform linux/amd64 -p 9000:8080docker-image:test

   This command runs the image as a container and creates a local endpoint atlocalhost:9000/2015-03-31/functions/function/invocations.

   Note

   If you built the Docker image for the ARM64 instruction set architecture, be sure to use the--platform linux/arm64 option instead of--platform linux/amd64.

2. From a new terminal window, post an event to the local endpoint.

   Linux/macOS

   In Linux and macOS, run the followingcurl command:

   curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

   This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:

   curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'

   PowerShell

   In PowerShell, run the followingInvoke-WebRequest command:

   Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"

   This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:

   Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"

3. Get the container ID.

   docker ps

4. Use thedocker kill command to stop the container. In this command, replace3766c4ab331c with the container ID from the previous step.

   docker kill3766c4ab331c

1. Run theget-login-password command to authenticate the Docker CLI to your Amazon ECR registry.

   • Set the--region value to the AWS Region where you want to create the Amazon ECR repository.

   • Replace111122223333 with your AWS account ID.

   aws ecr get-login-password --regionus-east-1 | docker login --username AWS --password-stdin111122223333.dkr.ecr.us-east-1.amazonaws.com

2. Create a repository in Amazon ECR using thecreate-repository command.

   aws ecr create-repository --repository-namehello-world --regionus-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE

   Note

   The Amazon ECR repository must be in the same AWS Region as the Lambda function.

   If successful, you see a response like this:

   {    "repository":{        "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world",        "registryId": "111122223333",        "repositoryName": "hello-world",        "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world",        "createdAt": "2023-03-09T10:39:01+00:00",        "imageTagMutability": "MUTABLE",        "imageScanningConfiguration":{            "scanOnPush": true        },        "encryptionConfiguration":{            "encryptionType": "AES256"        }    }}

3. Copy therepositoryUri from the output in the previous step.

4. Run thedocker tag command to tag your local image into your Amazon ECR repository as the latest version. In this command:

   • docker-image:test is the name andtag of your Docker image. This is the image name and tag that you specified in thedocker build command.

   • Replace<ECRrepositoryUri> with therepositoryUri that you copied. Make sure to include:latest at the end of the URI.

   docker tag docker-image:test<ECRrepositoryUri>:latest

   Example:

   docker tagdocker-image:test111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

5. Run thedocker push command to deploy your local image to the Amazon ECR repository. Make sure to include:latest at the end of the repository URI.

   docker push111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

6. Create an execution role for the function, if you don't already have one. You need the Amazon Resource Name (ARN) of the role in the next step.

7. Create the Lambda function. ForImageUri, specify the repository URI from earlier. Make sure to include:latest at the end of the URI.

   aws lambda create-function \  --function-namehello-world \  --package-type Image \  --code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \  --rolearn:aws:iam::111122223333:role/lambda-ex

   Note

   You can create a function using an image in a different AWS account, as long as the image is in the same Region as the Lambda function. For more information, see Amazon ECR cross-account permissions.

8. Invoke the function.

   aws lambda invoke --function-namehello-world response.json

   You should see a response like this:

   {  "ExecutedVersion": "$LATEST",   "StatusCode": 200}

9. To see the output of the function, check theresponse.json file.

• AWS CLI version 2

• Docker (minimum version 25.0.0)

• The Dockerbuildx plugin.

• Python

1. Create a directory for the project, and then switch to that directory.

   mkdir examplecd example

2. Create a new file calledlambda_function.py. You can add the following sample function code to the file for testing, or use your own.

   Example Python function

   import sysdef handler(event, context):    return 'Hello from AWS Lambda using Python' + sys.version + '!'

3. Create a new file calledrequirements.txt. If you're using the sample function code from the previous step, you can leave the file empty because there are no dependencies. Otherwise, list each required library. For example, here's what yourrequirements.txt should look like if your function uses the AWS SDK for Python (Boto3):

   Example requirements.txt

   boto3

4. Create a new Dockerfile. The following Dockerfile uses an official Python base image instead of anAWS base image. The Dockerfile includes theruntime interface client, which makes the image compatible with Lambda. The following example Dockerfile uses amulti-stage build.

   • Set theFROM property to the base image.

   • Set theENTRYPOINT to the module that you want the Docker container to run when it starts. In this case, the module is the runtime interface client.

   • Set theCMD to the Lambda function handler.

   Note that the example Dockerfile does not include aUSER instruction. When you deploy a container image to Lambda, Lambda automatically defines a default Linux user with least-privileged permissions. This is different from standard Docker behavior which defaults to theroot user when noUSER instruction is provided.

   Example Dockerfile

   # Define custom function directoryARG FUNCTION_DIR="/function"FROMpython:3.12 AS build-image# Include global arg in this stage of the buildARG FUNCTION_DIR# Copy function codeRUN mkdir -p ${FUNCTION_DIR}COPY . ${FUNCTION_DIR}# Install the function's dependenciesRUN pip install \    --target ${FUNCTION_DIR} \        awslambdaric# Use a slim version of the base Python image to reduce the final image sizeFROMpython:3.12-slim# Include global arg in this stage of the buildARG FUNCTION_DIR# Set working directory to function root directoryWORKDIR ${FUNCTION_DIR}# Copy in the built dependenciesCOPY --from=build-image ${FUNCTION_DIR} ${FUNCTION_DIR}# Set runtime interface client as default command for the container runtimeENTRYPOINT [ "/usr/local/bin/python", "-m", "awslambdaric" ]# Pass the name of the function handler as an argument to the runtimeCMD [ "lambda_function.handler" ]

5. Build the Docker image with thedocker build command. The following example names the imagedocker-image and gives it thetesttag. To make your image compatible with Lambda, you must use the--provenance=false option.

   docker buildx build --platform linux/amd64 --provenance=false -tdocker-image:test .

   Note

   The command specifies the--platform linux/amd64 option to ensure that your container is compatible with the Lambda execution environment regardless of the architecture of your build machine. If you intend to create a Lambda function using the ARM64 instruction set architecture, be sure to change the command to use the--platform linux/arm64 option instead.

To install and run the runtime interface emulator on your local machine

1. From your project directory, run the following command to download the runtime interface emulator (x86-64 architecture) from GitHub and install it on your local machine.

   Linux/macOS

   mkdir -p ~/.aws-lambda-rie && \    curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie && \    chmod +x ~/.aws-lambda-rie/aws-lambda-rie

   To install the arm64 emulator, replace the GitHub repository URL in the previous command with the following:

   https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64

   PowerShell

   $dirPath = "$HOME\.aws-lambda-rie"if (-not (Test-Path $dirPath)){    New-Item -Path $dirPath -ItemType Directory}      $downloadLink = "https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie"$destinationPath = "$HOME\.aws-lambda-rie\aws-lambda-rie"Invoke-WebRequest -Uri $downloadLink -OutFile $destinationPath

   To install the arm64 emulator, replace the$downloadLink with the following:

   https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64

2. Start the Docker image with thedocker run command. Note the following:

   • docker-image is the image name andtest is the tag.

   • /usr/local/bin/python -m awslambdaric lambda_function.handler is theENTRYPOINT followed by theCMD from your Dockerfile.

   Linux/macOS

   docker run --platform linux/amd64 -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \    --entrypoint /aws-lambda/aws-lambda-rie \docker-image:test \/usr/local/bin/python -m awslambdaric lambda_function.handler

   PowerShell

   docker run --platform linux/amd64 -d -v "$HOME\.aws-lambda-rie:/aws-lambda" -p 9000:8080 `--entrypoint /aws-lambda/aws-lambda-rie `docker-image:test `/usr/local/bin/python -m awslambdaric lambda_function.handler

   This command runs the image as a container and creates a local endpoint atlocalhost:9000/2015-03-31/functions/function/invocations.

   Note

   If you built the Docker image for the ARM64 instruction set architecture, be sure to use the--platform linux/arm64 option instead of--platform linux/amd64.

3. Post an event to the local endpoint.

   Linux/macOS

   In Linux and macOS, run the followingcurl command:

   curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

   This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:

   curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}'

   PowerShell

   In PowerShell, run the followingInvoke-WebRequest command:

   Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json"

   This command invokes the function with an empty event and returns a response. If you're using your own function code rather than the sample function code, you might want to invoke the function with a JSON payload. Example:

   Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json"

4. Get the container ID.

   docker ps

5. Use thedocker kill command to stop the container. In this command, replace3766c4ab331c with the container ID from the previous step.

   docker kill3766c4ab331c

1. Run theget-login-password command to authenticate the Docker CLI to your Amazon ECR registry.

   • Set the--region value to the AWS Region where you want to create the Amazon ECR repository.

   • Replace111122223333 with your AWS account ID.

   aws ecr get-login-password --regionus-east-1 | docker login --username AWS --password-stdin111122223333.dkr.ecr.us-east-1.amazonaws.com

2. Create a repository in Amazon ECR using thecreate-repository command.

   aws ecr create-repository --repository-namehello-world --regionus-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE

   Note

   The Amazon ECR repository must be in the same AWS Region as the Lambda function.

   If successful, you see a response like this:

   {    "repository":{        "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world",        "registryId": "111122223333",        "repositoryName": "hello-world",        "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world",        "createdAt": "2023-03-09T10:39:01+00:00",        "imageTagMutability": "MUTABLE",        "imageScanningConfiguration":{            "scanOnPush": true        },        "encryptionConfiguration":{            "encryptionType": "AES256"        }    }}

3. Copy therepositoryUri from the output in the previous step.

4. Run thedocker tag command to tag your local image into your Amazon ECR repository as the latest version. In this command:

   • docker-image:test is the name andtag of your Docker image. This is the image name and tag that you specified in thedocker build command.

   • Replace<ECRrepositoryUri> with therepositoryUri that you copied. Make sure to include:latest at the end of the URI.

   docker tag docker-image:test<ECRrepositoryUri>:latest

   Example:

   docker tagdocker-image:test111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

5. Run thedocker push command to deploy your local image to the Amazon ECR repository. Make sure to include:latest at the end of the repository URI.

   docker push111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

6. Create an execution role for the function, if you don't already have one. You need the Amazon Resource Name (ARN) of the role in the next step.

7. Create the Lambda function. ForImageUri, specify the repository URI from earlier. Make sure to include:latest at the end of the URI.

   aws lambda create-function \  --function-namehello-world \  --package-type Image \  --code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \  --rolearn:aws:iam::111122223333:role/lambda-ex

   Note

   You can create a function using an image in a different AWS account, as long as the image is in the same Region as the Lambda function. For more information, see Amazon ECR cross-account permissions.

8. Invoke the function.

   aws lambda invoke --function-namehello-world response.json

   You should see a response like this:

   {  "ExecutedVersion": "$LATEST",   "StatusCode": 200}

9. To see the output of the function, check theresponse.json file.