Deploy Java Lambda functions with container images

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

2. From a new terminal window, post an event to the following endpoint using a 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!"}'

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 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE

   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

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.

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.

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

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.

   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

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.

   docker run -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

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

3. Post an event to the following endpoint using a 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. Some functions might require a JSON payload. Example:

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

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 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE

   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

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.