Skip to content

quarkus.md

Latest commit

 

History

History
177 lines (135 loc) · 8.59 KB

quarkus.md

File metadata and controls

177 lines (135 loc) · 8.59 KB
title Quarkus
description Use the Quarkus framework with LocalStack
template doc
sidebar
order
3

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

:::tip With GraalVM installed, you can also create a native executable binary using the following command:

$ ./mvnw clean package -Dnative.

:::

:::note Dev Services for Amazon Services is automatically enabled for each extension added to the pom.xml, except in the following scenarios:

  • When quarkus.devservices.enabled is set to false.
  • When devservices.enabled is set to false per extension (e.g., quarkus.s3.devservices.enabled=false).
  • When the endpoint-override is configured (e.g., quarkus.s3.endpoint-override=http://localhost:4566). :::

Supported extensions

Configuration

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

Property Type Default
quarkus.aws.devservices.localstack.image-name string localstack/localstack:3.0.1
quarkus.aws.devservices.localstack.init-scripts-folder string
quarkus.aws.devservices.localstack.init-scripts-classpath string
quarkus.aws.devservices.localstack.init-completion-msg string
quarkus.aws.devservices.localstack.container-properties Map<String,String>
quarkus.aws.devservices.localstack.additional-services."additional-services".enabled boolean
quarkus.aws.devservices.localstack.additional-services."additional-services".shared boolean false
quarkus.aws.devservices.localstack.additional-services."additional-services".service-name string localstack
quarkus.aws.devservices.localstack.additional-services."additional-services".container-properties Map<String,String>

:::note

  • If quarkus.aws.devservices.localstack.additional-services."additional-services".enabled is set to true and the endpoint-override is not configured, LocalStack will be started and utilized instead of the provided configuration. For all services excluding Cognito, LocalStack will function as the core cloud emulator. In the case of Cognito, the emulation/mocking will be done by Moto.
  • The quarkus.aws.devservices.localstack.additional-services."additional-services".shared indicates whether the LocalStack container managed by Dev Services is shared. In shared mode, Quarkus utilizes label-based service discovery, specifically the quarkus-dev-service-localstack label, to identify running containers. If a matching container is found, it is used. Otherwise, Dev Services initiates a new container. It's important to note that sharing is not supported for the Cognito extension.
  • In quarkus.aws.devservices.localstack.additional-services."additional-services".service-name, the value of the quarkus-dev-service-localstack label is attached to the initiated container. In dev mode, when the shared flag is true, Dev Services checks for a container with the quarkus-dev-service-localstack label set to the configured value before starting a new one. If found, it utilizes the existing container. Otherwise, it creates a new container with the quarkus-dev-service-localstack label set to the specified value. In test mode, Dev Services groups services with the same service-name value into a single container instance. This property is useful when there's a requirement for multiple shared LocalStack instances. :::

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