Quarkus - Amazon Lambda with RESTEasy, Undertow, or Vert.x Web
quarkus-amazon-lambda-http extension allows you to write microservices with RESTEasy (JAX-RS),
Undertow (servlet), Vert.x Web, Funqy HTTP or any other Quarkus HTTP API that runs on top of Vert.x Web
and deploy them to Amazon Lambda
using Amazon’s API Gateway and Amazon’s SAM framework.
You can deploy your Lambda as a pure Java jar, or you can compile your project to a native image and deploy that for a smaller memory footprint and startup time.
This technology is considered preview.
In preview, backward compatibility and presence in the ecosystem is not guaranteed. Specific improvements might require to change configuration or APIs and plans to become stable are under way. Feedback is welcome on our mailing list or as issues in our GitHub issue tracker.
For a full list of possible extension statuses, check our FAQ entry.
This guide walks you through generating an example Java project via a maven archetype. Later on it walks through the structure of the project so you can adapt any existing projects you have to use Amazon Lambda.
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 SAM CLI.
Create the Quarkus AWS Lambda maven project using our Maven Archetype.
mvn archetype:generate \ -DarchetypeGroupId=io.quarkus \ -DarchetypeArtifactId=quarkus-amazon-lambda-http-archetype \ -DarchetypeVersion=1.12.0.Final
This extension has recently been upgraded to use API Gateway V2. If you need to still use V1 of the API Gateway
Build the project using maven.
./mvnw clean install
This will compile the code and run the unit tests included within the generated project. Unit testing is the same as any other Java project and does not require running on Amazon. Quarkus dev-mode is also available with this extension.
If you want to build for native too, make sure you have GraalVM installed correctly and just add a
to the build
./mvnw clean install -Dnative
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:
./mvnw clean install -Dnative -Dnative-image.docker-build=true
After you run the build, there are a few extra files generated by the
quarkus-amazon-lambda extension. These files
are in the the build directory:
target/ for maven,
build/ for gradle.
function.zip- lambda deployment file
sam.jvm.yaml- sam cli deployment script
sam.native.yaml- sam cli deployment script for native
The AWS SAM CLI allows you to run your lambda’s locally on your laptop in a simulated Lambda environment. This requires docker to be installed (see their install docs). After you have built your maven project, execute this command
sam local start-api --template target/sam.jvm.yaml
This will start a docker container that mimics Amazon’s Lambda’s deployment environment. Once the environment is started you can invoke the example lambda in your browser by going to
In the console you’ll see startup messages from the lambda. This particular deployment starts a JVM and loads your lambda as pure Java.
sam deploy -t target/sam.jvm.yaml -g
Answer all the questions and your lambda will be deployed and the necessary hooks to the API Gateway will be set up. If everything deploys successfully, the root URL of your microservice will be output to the console. Something like this:
Key LambdaHttpApi Description URL for application Value https://234asdf234as.execute-api.us-east-1.amazonaws.com/
Value attribute is the root URL for your lambda. Copy it to your browser and add
hello at the end.
Responses for binary types will be automatically encoded with base64. This is different than the behavior using
To deploy a native executable, you must build it with Graal.
./mvnw clean install -Dnative
You can then test the executable locally with sam local
sam local start-api --template target/sam.native.yaml
To deploy to AWS Lambda:
sam deploy -t target/sam.native.yaml -g
There is nothing special about the POM other than the inclusion of the
as a dependencies. The extension automatically generates everything you might need for your lambda deployment.
Also, at least in the generated maven archetype
dependencies are all optional. Pick which http framework(s) you want to use (JAX-RS, Vertx Web, and/or Servlet) and
remove the other dependencies to shrink your deployment.
sam.yaml syntax is beyond the scope of this document. There’s a couple of things to note though that are particular
Amazon’s API Gateway assumes that HTTP response bodies are text unless you explicitly tell it which media types are
binary through configuration. To make things easier, the Quarkus extension forces a binary (base 64) encoding of all
HTTP response messages and the
sam.yaml file must configure the API Gateway to assume all media types are binary:
Globals: Api: EndpointConfiguration: REGIONAL BinaryMediaTypes: - "*/*"
Another thing to note is that for pure Java lambda deployments, do not change the Lambda handler name.
Properties: Handler: io.quarkus.amazon.lambda.runtime.QuarkusStreamHandler::handleRequest Runtime: java11
This particular handler handles all the intricacies of integrating with the Quarkus runtime. So you must use that handler.
Finally, there’s an environment variable that must be set for native GraalVM deployments. If you look at
you’ll see this:
Environment: Variables: DISABLE_SIGNAL_HANDLERS: true
This environment variable resolves some incompatibilities between Quarkus and the Amazon Lambda Custom Runtime environment.
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.