Quarkus - Amazon Lambda

To complete this guide, you need:

This guide walks you through generating an example Java project via a maven archetype and deploying it to AWS.

Installing all the AWS bits is probably the most difficult thing about this guide. Make sure that you follow all the steps for installing AWS CLI.

Create the Quarkus AWS Lambda maven project using our Maven Archetype.

The quarkus-amazon-lambda extension scans your project for a class that implements the Amazon RequestHandler interface. It must find a class in your project that implements this interface or it will throw a build time failure. If it finds more than one handler class, a build time exception will also be thrown.

Sometimes, though, you might have a few related lambdas that share code and creating multiple maven modules is just an overhead you don’t want to do. The quarkus-amazon-lambda extension allows you to bundle multiple lambdas in one project and use configuration or an environment variable to pick the handler you want to deploy.

The generated project has two lambdas within it. One that is used and one that is unused. If you open up src/main/resources/application.properties you’ll see this:

The quarkus.lambda.handler property tells Quarkus which lambda handler to deploy. This can be overridden with an environment variable too.

If you look at the two generated handler classes in the project, you’ll see that they are @Named differently.

The CDI name of the handler class must match the value specified within the quarkus.lambda.handler property.

There are a few steps to get your lambda running on AWS. The generated maven project contains a helpful script to create, update, delete, and invoke your lambdas for pure Java and native deployments.

Build the project using maven.

This will compile and package your code.

View the Getting Started Guide for deploying a lambda with AWS CLI. Specifically, make sure you have created an Execution Role. You will need to copy and paste the Role Arn into the scripts generated by the maven archetype. To use the provided scripts, you will either need to define a LAMBDA_ROLE_ARN environment variable in your profile or define it prior to executing the scripts like this:

The manage.sh script is for managing your lambda using the AWS Lambda Java runtime. This script is provided only for your convenience. Examine the output of the manage.sh script if you want to learn what aws commands are executed to create, delete, and update your lambdas.

manage.sh supports four operation: create, delete, update, and invoke. You can create your function using the following command:

or if you do not have LAMBDA_ROLE_ARN already defined in this shell:

If there are any problems creating the function, you must delete it with the delete function before re-running the create command.

Commands may also be stacked:

Use the invoke command to invoke your function.

The example lambda takes input passed in via the --payload switch which points to a json file in the root directory of the project. If you want to see the output of the lambda, open the response.txt file. The lambda can also be invoked locally like this:

If you are working with your native image build, simply replace the template name above with the native version.

You can update the Java code as you see fit. Once you’ve rebuilt, you can redeploy your lambda by executing the update command.

If you want a lower memory footprint and faster initialization times for your lambda, you can compile your Java code to a native executable. Just make sure to rebuild your project with the -Pnative switch.

If you are building on a non-linux system, you will need to also pass in a property instructing quarkus to use a docker build as Amazon Lambda requires linux binaries. You can do this by passing this property to your maven build: -Dnative-image.docker-build=true. This requires you to have docker installed locally, however.

Either of these commands will compile and create a native executable image. It also generates a zip file target/function.zip. This zip file contains your native executable image renamed to bootstrap. This is a requirement of Amazon Lambda Custom Runtime.

The instructions here are exactly as above with one change: you’ll need to add native as the first parameter to the manage.sh script:

As above, commands can be stacked. The only requirement is that native be the first parameter should you wish to work with native image builds. The script will take care of the rest of the details necessary to manage your native image function deployments.

Examine the output of the manage.sh script if you want to learn what aws commands are executed to create, delete, and update your lambdas.

One thing to note about the create command for native is that the aws lambda create-function call must set a specific environment variable:

If you want to adapt an existing project to use Quarkus’s Amazon Lambda extension, there are a couple of things you need to do. Take a look at the generated example project to get an example of what you need to adapt.

NB: With gradle, to build the uber-jar execute: ./gradlew quarkusBuild --uber-jar

The AWS SAM CLI allows you to run your lambdas locally on your laptop in a simulated Lambda environment. This requires docker to be installed. This is an optional approach should you choose to take advantage of it. Otherwise, dev mode should be sufficient for most of your needs.

A starter template has been generated for both JVM and native execution modes.

Run the following SAM CLI command to locally test your lambda function:

The native image can also be locally tested using the sam.native.yaml template:

If you are building native images, and want to use AWS X-Ray Tracing with your lambda you will need to include quarkus-amazon-lambda-xray as a dependency in your pom. The AWS X-Ray library is not fully compatible with GraalVM so we had to do some integration work to make this work.