Back to Guides
Edit this Page

AWS Lambda

The quarkus-amazon-lambda extension allows you to use Quarkus to build your AWS Lambdas. Your lambdas can use injection annotations from CDI or Spring and other Quarkus facilities as you need them.

Quarkus lambdas can be deployed using the Amazon Java Runtime, or you can build a native executable and use Amazon’s Custom Runtime if you want a smaller memory footprint and faster cold boot startup time.

Quarkus’s integration with lambdas also supports Quarkus’s Live Coding development cycle. You can bring up your Quarkus lambda project in dev or test mode and code on your project live.

Prerequisites

To complete this guide, you need:

  • Roughly 30 minutes

  • An IDE

  • JDK 17+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.9.16

  • Optionally the Quarkus CLI if you want to use it

  • Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)

  • An Amazon AWS account

  • AWS CLI

  • AWS SAM CLI, for local testing

For Gradle projects please see below, or for further reference consult the guide in the Gradle setup page.

Getting Started

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

Installing AWS bits

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.

Creating the Maven Deployment Project

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

mvn archetype:generate \
       -DarchetypeGroupId=io.quarkus \
       -DarchetypeArtifactId=quarkus-amazon-lambda-archetype \
       -DarchetypeVersion=3.40.1

The Maven archetype generates both Maven and Gradle build files. If you prefer to use Gradle, run gradle wrapper in the generated project to set up the Gradle wrapper (recommended).

Alternatively, you can generate a project via code.quarkus.io adding the quarkus-amazon-lambda extension as a dependency.

For full Gradle details, see the Gradle build section below.

Choose Your Lambda

The quarkus-amazon-lambda extension scans your project for a class that directly implements the Amazon RequestHandler<?, ?> or RequestStreamHandler 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 three lambdas within it. Two that implement the RequestHandler<?, ?> interface, and one that implements the RequestStreamHandler interface. One that is used and two that are unused. If you open up src/main/resources/application.properties you’ll see this:

quarkus.lambda.handler=test

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 three generated handler classes in the project, you’ll see that they are @Named differently.

@Named("test")
public class TestLambda implements RequestHandler<InputObject, OutputObject> {
}

@Named("unused")
public class UnusedLambda implements RequestHandler<InputObject, OutputObject> {
}

@Named("stream")
public class StreamLambda implements RequestStreamHandler {
}

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

Deploy to AWS Lambda Java Runtime

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 and Deploy

Build the project:

CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

This will compile and package your code.

Create an Execution Role

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 define a LAMBDA_ROLE_ARN environment variable in your profile or console window, Alternatively, you can edit the manage.sh script that is generated by the build and put the role value directly there:

LAMBDA_ROLE_ARN="arn:aws:iam::1234567890:role/lambda-role"

Extra Build Generated Files

After you run the build, there are a few extra files generated by the quarkus-amazon-lambda extension. These files are in the build directory: target/ for maven, build/ for gradle.

  • function.zip - lambda deployment file

  • manage.sh - wrapper around aws lambda cli calls

  • bootstrap-example.sh - example bootstrap script for native deployments

  • sam.jvm.yaml - (optional) for use with sam cli and local testing

  • sam.native.yaml - (optional) for use with sam cli and native local testing

Create the function

The target/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.

To verify your setup, that you have the AWS CLI installed, executed aws configure for the AWS access keys, and set up the LAMBDA_ROLE_ARN environment variable (as described above), please execute manage.sh without any parameters. A usage statement will be printed to guide you accordingly.