Quarkus

Use the Quarkus framework with LocalStack

Introduction

Quarkus is a Java framework optimized for cloud, serverless, and containerized environments. Quarkus leverages a Kubernetes Native Java stack tailored for GraalVM & OpenJDK HotSpot, which further builds on various Java libraries and standards.

Localstack is supported by Quarkus as a Dev service for Amazon Services. Quarkus Amazon Services automatically starts a LocalStack container in development mode and when running tests, and the extension client is configured automatically.

Getting started

In this guide, we will demonstrate how you can create a service client for creating and managing Lambdas on LocalStack. The Lambda extension is based on AWS Java SDK 2.x.

Prerequisites

Create a Maven project

Create a new project with the following command:

$ mvn io.quarkus.platform:quarkus-maven-plugin:3.6.3:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=amazon-lambda-quickstart \
    -DclassName="org.acme.lambda.QuarkusLambdaSyncResource" \
    -Dpath="/sync" \
    -Dextensions="resteasy-reactive-jackson,amazon-lambda"
$ cd amazon-lambda-quickstart

The above command generates a Maven project structure with imports for RESTEasy Reactive/JAX-RS and Amazon Lambda Client extensions.

Configure Lambda Client

Both Lambda clients (sync and async) can be configured through the application.properties file, which should be located in the src/main/resources directory. Additionally, ensure that a suitable implementation of the sync client is added to the classpath. By default, the extension employs the URL connection HTTP client, so it’s necessary to include a URL connection client dependency in the pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>url-connection-client</artifactId>
</dependency>

If you want to use Apache HTTP client instead, configure it as follows in application.properties:

quarkus.lambda.sync-client.type=apache

Add the following dependencies to the pom.xml file:

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>apache-client</artifactId>
</dependency>

To configure LocalStack, add the following properties to the application.properties file:

quarkus.lambda.endpoint-override=http://localhost:4566 

quarkus.lambda.aws.region=us-east-1 
quarkus.lambda.aws.credentials.type=static 
quarkus.lambda.aws.credentials.static-provider.access-key-id=test-key
quarkus.lambda.aws.credentials.static-provider.secret-access-key=test-secret

Package the application

You can package the application with the following command:

$ ./mvnw clean package

You can further run the application in dev mode with the following command:

$ java -Dparameters.path=/quarkus/is/awesome/ -jar target/quarkus-app/quarkus-run.jar

Supported extensions

Configuration

The following configuration properties are fixed at build time. All the other configuration properties can be overridden at runtime.

PropertyTypeDefault
quarkus.aws.devservices.localstack.image-namestringlocalstack/localstack:3.0.1
quarkus.aws.devservices.localstack.init-scripts-folderstring
quarkus.aws.devservices.localstack.init-scripts-classpathstring
quarkus.aws.devservices.localstack.init-completion-msgstring
quarkus.aws.devservices.localstack.container-propertiesMap<String,String>
quarkus.aws.devservices.localstack.additional-services."additional-services".enabledboolean
quarkus.aws.devservices.localstack.additional-services."additional-services".sharedbooleanfalse
quarkus.aws.devservices.localstack.additional-services."additional-services".service-namestringlocalstack
quarkus.aws.devservices.localstack.additional-services."additional-services".container-propertiesMap<String,String>

Specific configuration

Dev Services can support specific configurations passed to the LocalStack container. These configurations can be globally applied to all containers or specified individually per service.

quarkus.aws.devservices.localstack.image-name=localstack/localstack:3.0.3
quarkus.dynamodb.devservices.container-properties.DYNAMODB_HEAP_SIZE=1G

Additional services

To start additional services for which a Quarkus extension does not exist or is not imported in the project, use the additional-services property:

quarkus.aws.devservices.localstack.additional-services."kinesis".enabled=true
quarkus.aws.devservices.localstack.additional-services."redshift".enabled=true
Last modified July 18, 2024: setup markdownlint (#1382) (f2ebb421e)