Deploy Java Lambda functions with 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).

Deploy Java Lambda functions with container images

There are three ways to build a container image for a Java Lambda function:

Tip

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

This page explains how to build, test, and deploy container images for Lambda.

Amazon base images for Java

Amazon provides the following base images for Java:

Tags Runtime Operating system Dockerfile Deprecation

21

Java 21 Amazon Linux 2023 Dockerfile for Java 21 on GitHub

17

Java 17 Amazon Linux 2 Dockerfile for Java 17 on GitHub

11

Java 11 Amazon Linux 2 Dockerfile for Java 11 on GitHub

8.al2

Java 8 Amazon Linux 2 Dockerfile for Java 8 on GitHub

Amazon ECR repository: gallery.ecr.aws/lambda/java

The Java 21 and later base images are based on the Amazon Linux 2023 minimal container image. Earlier base images use Amazon Linux 2. AL2023 provides several advantages over Amazon Linux 2, including a smaller deployment footprint and updated versions of libraries such as glibc.

AL2023-based images use microdnf (symlinked as dnf) as the package manager instead of yum, which is the default package manager in Amazon Linux 2. microdnf is a standalone implementation of dnf. For a list of packages that are included in AL2023-based images, refer to the Minimal Container columns in Comparing packages installed on Amazon Linux 2023 Container Images. For more information about the differences between AL2023 and Amazon Linux 2, see Introducing the Amazon Linux 2023 runtime for Amazon Lambda on the Amazon Compute Blog.

Note

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

Using an Amazon base image for Java

To complete the steps in this section, you must have the following:

Maven
  1. Run the following command to create a Maven project using the archetype for Lambda. The following parameters are required:

    • service – The Amazon Web Service client to use in the Lambda function. For a list of available sources, see aws-sdk-java-v2/services on GitHub.

    • region – The Amazon Web Services Region where you want to create the Lambda function.

    • groupId – The full package namespace of your application.

    • artifactId – Your project name. This becomes the name of the directory for your project.

    In Linux and macOS, run this command:

    mvn -B archetype:generate \ -DarchetypeGroupId=software.amazon.awssdk \ -DarchetypeArtifactId=archetype-lambda -Dservice=s3 -Dregion=US_WEST_2 \ -DgroupId=com.example.myapp \ -DartifactId=myapp

    In PowerShell, run this command:

    mvn -B archetype:generate ` "-DarchetypeGroupId=software.amazon.awssdk" ` "-DarchetypeArtifactId=archetype-lambda" "-Dservice=s3" "-Dregion=US_WEST_2" ` "-DgroupId=com.example.myapp" ` "-DartifactId=myapp"

    The Maven archetype for Lambda is preconfigured to compile with Java SE 8 and includes a dependency to the Amazon SDK for Java. If you create your project with a different archetype or by using another method, you must configure the Java compiler for Maven and declare the SDK as a dependency.

  2. Open the myapp/src/main/java/com/example/myapp directory, and find the App.java file. This is the code for the Lambda function. You can use the provided sample code for testing, or replace it with your own.

  3. Navigate back to the project's root directory, and then create a new Dockerfile with the following configuration:

    • Set the FROM property to the URI of the base image.

    • Set the CMD argument to the Lambda function handler.

    Example Dockerfile
    FROM public.ecr.aws/lambda/java:21 # Copy function code and runtime dependencies from Maven layout COPY target/classes ${LAMBDA_TASK_ROOT} COPY target/dependency/* ${LAMBDA_TASK_ROOT}/lib/ # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "com.example.myapp.App::handleRequest" ]
  4. Compile the project and collect the runtime dependencies.

    mvn compile dependency:copy-dependencies -DincludeScope=runtime
  5. Build the Docker image with the docker build command. The following example names the image docker-image and gives it the test tag.

    docker build --platform linux/amd64 -t docker-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.

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

    mkdir example cd example
  2. Run the following command to have Gradle generate a new Java application project in the example directory in your environment. For Select build script DSL, choose 2: Groovy.

    gradle init --type java-application
  3. Open the /example/app/src/main/java/example directory, and find the App.java file. This is the code for the Lambda function. You can use the following sample code for testing, or replace it with your own.

    Example App.java
    package com.example; import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; public class App implements RequestHandler<Object, String> { public String handleRequest(Object input, Context context) { return "Hello world!"; } }
  4. Open the build.gradle file. If you're using the sample function code from the previous step, replace the contents of build.gradle with the following. If you're using your own function code, modify your build.gradle file as needed.

    Example build.gradle (Groovy DSL)
    plugins { id 'java' } group 'com.example' version '1.0-SNAPSHOT' sourceCompatibility = 1.8 repositories { mavenCentral() } dependencies { implementation 'com.amazonaws:aws-lambda-java-core:1.2.1' } jar { manifest { attributes 'Main-Class': 'com.example.App' } }
  5. The gradle init command from step 2 also generated a dummy test case in the app/test directory. For the purposes of this tutorial, skip running tests by deleting the /test directory.

  6. Build the project.

    gradle build
  7. In the project's root directory (/example), create a Dockerfile with the following configuration:

    Example Dockerfile
    FROM public.ecr.aws/lambda/java:21 # Copy function code and runtime dependencies from Gradle layout COPY app/build/classes/java/main ${LAMBDA_TASK_ROOT} # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "com.example.App::handleRequest" ]
  8. Build the Docker image with the docker build command. The following example names the image docker-image and gives it the test tag.

    docker build --platform linux/amd64 -t docker-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 the docker run command. In this example, docker-image is the image name and test is the tag.

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

    This command runs the image as a container and creates a local endpoint at localhost: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 following curl 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 following Invoke-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 the docker kill command to stop the container. In this command, replace 3766c4ab331c with the container ID from the previous step.

    docker kill 3766c4ab331c
To upload the image to Amazon ECR and create the Lambda function
  1. Run the get-login-password command to authenticate the Docker CLI to your Amazon ECR registry.

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

    • Replace 111122223333 with your Amazon Web Services account ID.

    aws ecr get-login-password --region cn-north-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn
  2. Create a repository in Amazon ECR using the create-repository command.

    aws ecr create-repository --repository-name hello-world --region cn-north-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
    Note

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

    If successful, you see a response like this:

    { "repository": { "repositoryArn": "arn:aws:ecr:cn-north-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } }
  3. Copy the repositoryUri from the output in the previous step.

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

    • Replace docker-image:test with the name and tag of your Docker image.

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

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

    Example:

    docker tag docker-image:test 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest
  5. Run the docker 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 push 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/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. For ImageUri, specify the repository URI from earlier. Make sure to include :latest at the end of the URI.

    aws lambda create-function \ --function-name hello-world \ --package-type Image \ --code ImageUri=111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest \ --role arn:aws:iam::111122223333:role/lambda-ex
    Note

    You can create a function using an image in a different Amazon 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-name hello-world response.json

    You should see a response like this:

    { "ExecutedVersion": "$LATEST", "StatusCode": 200 }
  9. To see the output of the function, check the response.json file.

To update the function code, you must build the image again, upload the new image to the Amazon ECR repository, and then use the update-function-code command to deploy the image to the Lambda function.

Using an alternative base image with the runtime interface client

If you use an OS-only base image or an alternative base image, you must include the runtime interface client in your image. The runtime interface client extends the Lambda runtime API, which manages the interaction between Lambda and your function code.

Install the runtime interface client for Java in your Dockerfile, or as a dependency in your project. For example, to install the runtime interface client using the Maven package manager, add the following to your pom.xml file:

<dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-lambda-java-runtime-interface-client</artifactId> <version>2.3.2</version> </dependency>

For package details, see Amazon Lambda Java Runtime Interface Client in the Maven Central Repository. You can also review the runtime interface client source code in the Amazon Lambda Java Support Libraries GitHub repository.

The following example demonstrates how to build a container image for Java using an Amazon Corretto image. Amazon Corretto is a no-cost, multiplatform, production-ready distribution of the Open Java Development Kit (OpenJDK). The Maven project includes the runtime interface client as a dependency.

To complete the steps in this section, you must have the following:

  1. Create a Maven project. The following parameters are required:

    • groupId – The full package namespace of your application.

    • artifactId – Your project name. This becomes the name of the directory for your project.

    Linux/macOS
    mvn -B archetype:generate \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DgroupId=example \ -DartifactId=myapp \ -DinteractiveMode=false
    PowerShell
    mvn -B archetype:generate ` -DarchetypeArtifactId=maven-archetype-quickstart ` -DgroupId=example ` -DartifactId=myapp ` -DinteractiveMode=false
  2. Open the project directory.

    cd myapp
  3. Open the pom.xml file and replace the contents with the following. This file includes the aws-lambda-java-runtime-interface-client as a dependency. Alternatively, you can install the runtime interface client in the Dockerfile. However, the simplest approach is to include the library as a dependency.

    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>example</groupId> <artifactId>hello-lambda</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>hello-lambda</name> <url>http://maven.apache.org</url> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> </properties> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-lambda-java-runtime-interface-client</artifactId> <version>2.3.2</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-dependency-plugin</artifactId> <version>3.1.2</version> <executions> <execution> <id>copy-dependencies</id> <phase>package</phase> <goals> <goal>copy-dependencies</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project>
  4. Open the myapp/src/main/java/com/example/myapp directory, and find the App.java file. This is the code for the Lambda function. Replace the code with the following.

    Example function handler
    package example; public class App { public static String sayHello() { return "Hello world!"; } }
  5. The mvn -B archetype:generate command from step 1 also generated a dummy test case in the src/test directory. For the purposes of this tutorial, skip over running tests by deleting this entire generated /test directory.

  6. Navigate back to the project's root directory, and then create a new Dockerfile. The following example Dockerfile uses an Amazon Corretto image. Amazon Corretto is a no-cost, multiplatform, production-ready distribution of the OpenJDK.

    • Set the FROM property to the URI of the base image.

    • Set the ENTRYPOINT 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 the CMD argument to the Lambda function handler.

    Example Dockerfile
    FROM public.ecr.aws/amazoncorretto/amazoncorretto:21 as base # Configure the build environment FROM base as build RUN yum install -y maven WORKDIR /src # Cache and copy dependencies ADD pom.xml . RUN mvn dependency:go-offline dependency:copy-dependencies # Compile the function ADD . . RUN mvn package # Copy the function artifact and dependencies onto a clean base FROM base WORKDIR /function COPY --from=build /src/target/dependency/*.jar ./ COPY --from=build /src/target/*.jar ./ # Set runtime interface client as default command for the container runtime ENTRYPOINT [ "/usr/bin/java", "-cp", "./*", "com.amazonaws.services.lambda.runtime.api.client.AWSLambda" ] # Pass the name of the function handler as an argument to the runtime CMD [ "example.App::sayHello" ]
  7. Build the Docker image with the docker build command. The following example names the image docker-image and gives it the test tag.

    docker build --platform linux/amd64 -t docker-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.

Use the runtime interface emulator to locally test the image. You can build the emulator into your image or install it on your local machine.

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 the docker run command. Note the following:

    • docker-image is the image name and test is the tag.

    • /usr/bin/java -cp './*' com.amazonaws.services.lambda.runtime.api.client.AWSLambda example.App::sayHello is the ENTRYPOINT followed by the CMD 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/bin/java -cp './*' com.amazonaws.services.lambda.runtime.api.client.AWSLambda example.App::sayHello
    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/bin/java -cp './*' com.amazonaws.services.lambda.runtime.api.client.AWSLambda example.App::sayHello

    This command runs the image as a container and creates a local endpoint at localhost: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 following curl 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 following Invoke-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 the docker kill command to stop the container. In this command, replace 3766c4ab331c with the container ID from the previous step.

    docker kill 3766c4ab331c
To upload the image to Amazon ECR and create the Lambda function
  1. Run the get-login-password command to authenticate the Docker CLI to your Amazon ECR registry.

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

    • Replace 111122223333 with your Amazon Web Services account ID.

    aws ecr get-login-password --region cn-north-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn
  2. Create a repository in Amazon ECR using the create-repository command.

    aws ecr create-repository --repository-name hello-world --region cn-north-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE
    Note

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

    If successful, you see a response like this:

    { "repository": { "repositoryArn": "arn:aws:ecr:cn-north-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } }
  3. Copy the repositoryUri from the output in the previous step.

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

    • Replace docker-image:test with the name and tag of your Docker image.

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

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

    Example:

    docker tag docker-image:test 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest
  5. Run the docker 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 push 111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/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. For ImageUri, specify the repository URI from earlier. Make sure to include :latest at the end of the URI.

    aws lambda create-function \ --function-name hello-world \ --package-type Image \ --code ImageUri=111122223333.dkr.ecr.cn-north-1.amazonaws.com.cn/hello-world:latest \ --role arn:aws:iam::111122223333:role/lambda-ex
    Note

    You can create a function using an image in a different Amazon 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-name hello-world response.json

    You should see a response like this:

    { "ExecutedVersion": "$LATEST", "StatusCode": 200 }
  9. To see the output of the function, check the response.json file.

To update the function code, you must build the image again, upload the new image to the Amazon ECR repository, and then use the update-function-code command to deploy the image to the Lambda function.