Developing, testing, building, and deploying Native Quarkus-based Java microservices to Kubernetes on AWS, using GitOps

Introduction

Although it may no longer be the undisputed programming language leader, according to many developer surveys, Java still ranks right up there with Go, Python, C/C++, and JavaScript. Given Java’s continued popularity, especially amongst enterprises, and the simultaneous rise of cloud-native software development, vendors have focused on creating purpose-built, modern JVM-based frameworks, tooling, and standards for developing applications — specifically, microservices.

Leading JVM-based microservice application frameworks typically provide features such as native support for a Reactive programming model, MicroProfile, GraalVM Native Image, OpenAPI and Swagger definition generation, GraphQL, CORS (Cross-Origin Resource Sharing), gRPC (gRPC Remote Procedure Calls), CDI (Contexts and Dependency Injection), service discovery, and distributed tracing.

Leading JVM-based Microservices Frameworks

Review lists of the most popular cloud-native microservices framework for Java, and you are sure to find Spring Boot with Spring Cloud, Micronaut, Helidon, and Quarkus at or near the top.

Spring Boot with Spring Cloud

According to their website, Spring makes programming Java quicker, easier, and safer for everybody. Spring’s focus on speed, simplicity, and productivity has made it the world’s most popular Java framework. Spring Boot makes it easy to create stand-alone, production-grade Spring based Applications that you can just run. Spring Boot’s many purpose-built features make it easy to build and run your microservices in production at scale. However, the distributed nature of microservices brings challenges. Spring Cloud can help with service discovery, load-balancing, circuit-breaking, distributed tracing, and monitoring with several ready-to-run cloud patterns. It can even act as an API gateway.

Helidon

Oracle’s Helidon is a cloud-native, open‑source set of Java libraries for writing microservices that run on a fast web core powered by Netty. Helidon supports MicroProfile, a reactive programming model, and, similar to Micronaut, Spring, and Quarkus, it supports GraalVM Native Image.

Micronaut

According to their website, the Micronaut framework is a modern, open-source, JVM-based, full-stack toolkit for building modular, easily testable microservice and serverless applications. Micronaut supports a polyglot programming model, discovery services, distributed tracing, and aspect-oriented programming (AOP). In addition, Micronaut offers quick startup time, blazing-fast throughput, and a minimal memory footprint.

Quarkus

Quarkus, developed and sponsored by RedHat, is self-described as the ‘Supersonic Subatomic Java.’ Quarkus is a cloud-native, Kubernetes-native, [Linux] container first, microservices first framework for writing Java applications. Quarkus is a Kubernetes Native Java stack tailored for OpenJDK HotSpot and GraalVM, crafted from over fifty best-of-breed Java libraries and standards.

Developing Native Quarkus Microservices

In the following post, we will develop, build, test, deploy, and monitor a native Quarkus microservice application to Kubernetes. The RESTful service will expose a rich Application Programming Interface (API) and interacts with a PostgreSQL database on the backend.

Some of the features of the Quarkus application in this post include:

• Hibernate Object Relational Mapper (ORM), the de facto Jakarta Persistence API (formerly Java Persistence API) implementation
• Hibernate Reactive with Panache, a Quarkus-specific library that simplifies the development of Hibernate Reactive entities
• RESTEasy Reactive, a new JAX-RS implementation, works with the common Vert.x layer and is thus fully reactive
• Advanced RESTEasy Reactive Jackson support for JSON serialization
• Reactive PostgreSQL client
• Built on Mandrel, a downstream distribution of the GraalVM community edition
• Built with Gradle, the modern, open-source build automation tool focused on flexibility and performance

TL;DR

Do you want to explore the source code for this post’s Quarkus microservice application or deploy it to Kubernetes before reading the full article? All the source code and Kubernetes resources are open-source and available on GitHub:

git clone --depth 1 -b main \
    https://github.com/garystafford/tickit-srv.git

The latest Docker Image is available on docker.io:

docker pull garystafford/tickit-srv:<latest-tag>

Quarkus Projects with IntelliJ IDE

Although not a requirement, I used JetBrains IntelliJ IDEA 2022 (Ultimate Edition) to develop and test the post’s Quarkus application. Bootstrapping Quarkus projects with IntelliJ is easy. Using the Quarkus plugin bundled with the Ultimate edition, developers can quickly create a Quarkus project.

The Quarkus plugin’s project creation wizard is based on code.quarkus.io. If you have bootstrapped a Spring Initializr project, code.quarkus.io works very similar to start.spring.io.

Visual Studio Code

RedHat also provides a Quarkus extension for the popular Visual Studio Code IDE.

Gradle

This post uses Gradle instead of Maven to develop, test, build, package, and deploy the Quarkus application to Kubernetes. Based on the packages selected in the new project setup shown above, the Quarkus plugin’s project creation wizard creates the following build.gradle file (Lombak added separately).

	plugins {
	id 'java'
	id 'io.quarkus'
	id 'io.freefair.lombok' version '6.4.3'
	}
	repositories {
	mavenCentral()
	mavenLocal()
	}
	dependencies {
	implementation enforcedPlatform("${quarkusPlatformGroupId}:${quarkusPlatformArtifactId}:${quarkusPlatformVersion}")
	implementation("io.quarkus:quarkus-container-image-docker")
	implementation("io.quarkus:quarkus-kubernetes")
	implementation("io.quarkus:quarkus-kubernetes-config")
	implementation("io.quarkus:quarkus-resteasy-reactive")
	implementation("io.quarkus:quarkus-resteasy-reactive-jackson")
	implementation("io.quarkus:quarkus-hibernate-reactive-panache")
	implementation("io.quarkus:quarkus-reactive-pg-client")
	implementation("io.quarkus:quarkus-smallrye-health")
	implementation("io.quarkus:quarkus-smallrye-openapi")
	implementation("io.quarkus:quarkus-micrometer-registry-prometheus")
	testImplementation("io.quarkus:quarkus-junit5")
	testImplementation("io.rest-assured:rest-assured")
	}
	group 'com.tickit'
	version '1.0.0'
	java {
	sourceCompatibility = JavaVersion.VERSION_17
	targetCompatibility = JavaVersion.VERSION_17
	}
	compileJava {
	options.encoding = 'UTF-8'
	options.compilerArgs << '-parameters'
	}
	compileTestJava {
	options.encoding = 'UTF-8'
	}

view raw build.gradle hosted with ❤ by GitHub

The wizard also created the following gradle.properties file, which has been updated to the latest release of Quarkus available at the time of this post, 2.9.2.

	quarkusPlatformArtifactId=quarkus-bom
	quarkusPlatformGroupId=io.quarkus.platform
	quarkusPlatformVersion=2.9.2.Final
	quarkusPluginId=io.quarkus
	quarkusPluginVersion=2.9.2.Final

view raw gradle.properties hosted with ❤ by GitHub

Gradle and Quarkus

You can use the Quarkus CLI or the Quarkus Maven plugin to scaffold a Gradle project. Taking a dependency on the Quarkus plugin adds several additional Quarkus tasks to Gradle. We will use Gradle to develop, test, build, containerize, and deploy the Quarkus microservice application to Kubernetes. The quarkusDev, quarkusTest, and quarkusBuild tasks will be particularly useful in this post.

Java Compilation

The Quarkus application in this post is compiled as a native image with the most recent Java 17 version of Mandrel, a downstream distribution of the GraalVM community edition.

GraalVM and Native Image

According to the documentation, GraalVM is a high-performance JDK distribution. It is designed to accelerate the execution of applications written in Java and other JVM languages while also providing runtimes for JavaScript, Ruby, Python, and other popular languages.

Further, according to GraalVM, Native Image is a technology to ahead-of-time compile Java code to a stand-alone executable, called a native image. This executable includes the application classes, classes from its dependencies, runtime library classes, and statically linked native code from the JDK. The Native Image builder (native-image) is a utility that processes all classes of an application and their dependencies, including those from the JDK. It statically analyzes data to determine which classes and methods are reachable during the application execution.

Mandrel

Mandrel is a downstream distribution of the GraalVM community edition. Mandrel’s main goal is to provide a native-image release specifically to support Quarkus. The aim is to align the native-image capabilities from GraalVM with OpenJDK and Red Hat Enterprise Linux libraries to improve maintainability for native Quarkus applications. Mandrel can best be described as a distribution of a regular OpenJDK with a specially packaged GraalVM Native Image builder (native-image).

Docker Image

Once complied, the native Quarkus executable will run within the quarkus-micro-image:1.0 base runtime image deployed to Kubernetes. Quarkus provides this base image to ease the containerization of native executables. It has a minimal footprint (10.9 compressed/29.5 MB uncompressed) compared to other images. For example, the latest UBI (Universal Base Image) Quarkus Mandrel image (ubi-quarkus-mandrel:22.1.0.0-Final-java17) is 714 MB uncompressed, while the OpenJDK 17 image (openjdk:17-jdk) is 471 MB uncompressed. Even RedHat’s Universal Base Image Minimal image (ubi-minimal:8.6) is 93.4 MB uncompressed.

An even smaller option from Quarkus is a distroless base image (quarkus-distroless-image:1.0) is only 9.2 MB compressed / 22.7 MB uncompressed. Quarkus is careful to note that distroless image support is experimental and should not be used in production without rigorous testing.

PostgreSQL Database

For the backend data persistence tier of the Quarkus application, we will use PostgreSQL. All DDL (Data Definition Language) and DML (Data Manipulation Language) statements used in the post were tested with the most current version of PostgreSQL 14.

There are many PostgreSQL-compatible sample databases available that could be used for this post. I am using the TICKIT sample database provided by AWS and designed for Amazon Redshift, AWS’s cloud data warehousing service. The database consists of seven tables — two fact tables and five dimensions tables — in a traditional data warehouse star schema.

For this post, I have remodeled the TICKIT database’s star schema into a normalized relational data model optimized for the Quarkus application. The most significant change to the database is splitting the original Users dimension table into two separate tables — buyer and seller. This change will allow for better separation of concerns (SoC), scalability, and increased protection of Personal Identifiable Information (PII).

Source Code

Each of the six tables in the PostgreSQL TICKIT database is represented by an Entity, Repository, and Resource Java class.

Entity Class

Java Persistence is the API for managing persistence and object/relational mapping. The Java Persistence API (JPA) provides Java developers with an object/relational mapping facility for managing relational data in Java applications. Each table in the PostgreSQL TICKIT database is represented by a Java Persistence Entity, as indicated by the Entity annotation on the class declaration. The annotation specifies that the class is an entity.

Each entity class extends the PanacheEntityBase class, part of the io.quarkus.hibernate.orm.panache package. According to the Quarkus documentation, You can specify your own custom ID strategy, which is done in this post’s example, by extending PanacheEntityBase instead of PanacheEntity.

If you do not want to bother defining getters/setters for your entities, which we did not in the post’s example, extending PanacheEntityBase, Quarkus will generate them for you. Alternately, extend PanacheEntity and take advantage of the default ID it provides if you are not using a custom ID strategy.

The example SaleEntity class shown below is typical of the Quarkus application’s entities. The entity class contains several additional JPA annotations in addition to Entity, including Table, NamedQueries, Id, SequenceGenerator, GeneratedValue, and Column. The entity class also leverages Project Lombok annotations. Lombok generates two boilerplate constructors, one that takes no arguments (NoArgsConstructor) and one that takes one argument for every field (AllArgsConstructor).

The SaleEntity class also defines two many-to-one relationships, with the ListingEntity and BuyerEntity entity classes. This relationship mirrors the database’s data model, as reflected in the schema diagram above. The relationships are defined using the ManyToOne and JoinColumn JPA annotations.

	package com.tickit.sale;
	import com.tickit.buyer.BuyerEntity;
	import com.tickit.listing.ListingEntity;
	import io.quarkus.hibernate.reactive.panache.PanacheEntityBase;
	import lombok.AllArgsConstructor;
	import lombok.NoArgsConstructor;
	import javax.persistence.*;
	import java.math.BigDecimal;
	import java.time.LocalDateTime;
	@Entity
	@NoArgsConstructor
	@AllArgsConstructor
	@Table(name = "sale", schema = "public", catalog = "tickit")
	@NamedQueries({
	@NamedQuery(name = "SaleEntity.getBySellerId", query = """
	select sale, listing, seller
	from SaleEntity as sale
	join sale.listing as listing
	join listing.seller as seller
	where seller.id = ?1"""
	),
	@NamedQuery(name = "SaleEntity.getByEventId", query = """
	select sale, listing, event
	from SaleEntity as sale
	join sale.listing as listing
	join listing.event as event
	where event.id = ?1"""
	)})
	public class SaleEntity extends PanacheEntityBase {
	@Id
	@SequenceGenerator(
	name = "saleSeq",
	sequenceName = "sale_sale_id_seq",
	schema = "public",
	initialValue = 175000,
	allocationSize = 1)
	@GeneratedValue(
	strategy = GenerationType.SEQUENCE,
	generator = "saleSeq")
	@Column(name = "saleid", nullable = false)
	public int id;
	@Column(name = "qtysold", nullable = false)
	public short quantitySold;
	@Column(name = "pricepaid", nullable = false, precision = 2)
	public BigDecimal pricePaid;
	@Column(name = "commission", nullable = false, precision = 2)
	public BigDecimal commission;
	@Column(name = "saletime", nullable = false)
	public LocalDateTime saleTime;
	@ManyToOne(optional = false)
	@JoinColumn(name = "listid", referencedColumnName = "listid", nullable = false)
	public ListingEntity listing;
	@ManyToOne(optional = false)
	@JoinColumn(name = "buyerid", referencedColumnName = "buyerid", nullable = false)
	public BuyerEntity buyer;
	}

view raw SaleEntity.java hosted with ❤ by GitHub

Given the relationships between the entities, a saleEntity object, represented as a nested JSON object, would look as follows:

	{
	"id": 27,
	"quantitySold": 1,
	"pricePaid": 111,
	"commission": 16.65,
	"saleTime": "2008-10-13T01:09:47",
	"listing": {
	"id": 28,
	"numTickets": 1,
	"pricePerTicket": 111,
	"totalPrice": 111,
	"listTime": "2008-10-08T03:56:33",
	"seller": {
	"id": 32241,
	"username": "VRV70PKM",
	"firstName": "Olga",
	"lastName": "Sharpe",
	"city": "Yuma",
	"state": "DC",
	"email": "Aliquam.adipiscing@urnanecluctus.org",
	"phone": "(377) 405-5662",
	"taxIdNumber": "265116930"
	},
	"event": {
	"id": 1820,
	"name": "The Farnsworth Invention",
	"startTime": "2008-11-03T20:00:00",
	"venue": {
	"id": 220,
	"name": "Lunt-Fontanne Theatre",
	"city": "New York City",
	"state": "NY",
	"seats": 1500
	},
	"category": {
	"id": 7,
	"group": "Shows",
	"name": "Plays",
	"description": "All non-musical theatre"
	}
	}
	},
	"buyer": {
	"id": 4695,
	"username": "DRU13CBT",
	"firstName": "Tamekah",
	"lastName": "Frye",
	"city": "Washington",
	"state": "NB",
	"email": "tempus.risus@vulputate.edu",
	"phone": "(969) 804-4123",
	"likeSports": false,
	"likeTheatre": true,
	"likeConcerts": true,
	"likeJazz": false,
	"likeClassical": true,
	"likeOpera": false,
	"likeRock": false,
	"likeVegas": false,
	"likeBroadway": true,
	"likeMusicals": false
	}
	}

view raw sales.json hosted with ❤ by GitHub

Repository Class

Each table in the PostgreSQL TICKIT database also has a corresponding repository class, often referred to as the ‘repository pattern.’ The repository class implements the PanacheRepositoryBase interface, part of the io.quarkus.hibernate.orm.panache package. The PanacheRepositoryBase Java interface represents a Repository for a specific type of Entity. According to the documentation, if you are using repositories and have a custom ID strategy, then you will want to extend PanacheRepositoryBase instead of PanacheRepository and specify your ID type as an extra type parameter. Implementing the PanacheRepositoryBase will give you the same methods on the PanacheEntityBase.

The repository class allows us to leverage the methods already available through PanacheEntityBase and add additional custom methods. For example, the repository class contains a custom method listWithPaging. This method retrieves (GET) a list of SaleEntity objects with the added benefit of being able to indicate the page number, page size, sort by field, and sort direction.

Since there is a many-to-one relationship between the SaleEntity class and the ListingEntity and BuyerEntity entity classes, we also have two custom methods that retrieve all SaleEntity objects by either the BuyerEntity ID or the EventEntity ID. These two methods call the SQL queries in the SaleEntity, annotated with the JPA NamedQueries/NamedQuery annotations on the class declaration.

SmallRye Mutiny

Each method defined in the repository class returns a SmallRye Mutiny Uni<T>. According to the website, Mutiny is an intuitive, event-driven Reactive programming library for Java. Mutiny provides a simple but powerful asynchronous development model that lets you build reactive applications. Mutiny can be used in any Java application exhibiting asynchrony, including reactive microservices, data streaming, event processing, API gateways, and network utilities.

Uni

Again, according to Mutiny’s documentation, a Uni represents a stream that can only emit either an item or a failure event. A Uni<T> is a specialized stream that emits only an item or a failure. Typically, Uni<T> are great for representing asynchronous actions such as a remote procedure call, an HTTP request, or an operation producing a single result. A Uni represents a lazy asynchronous action. It follows the subscription pattern, meaning that the action is only triggered once a UniSubscriber subscribes to the Uni.

	package com.tickit.sale;
	import io.quarkus.hibernate.reactive.panache.PanacheRepositoryBase;
	import io.quarkus.panache.common.Sort;
	import io.smallrye.mutiny.Uni;
	import javax.enterprise.context.ApplicationScoped;
	import java.util.List;
	import java.util.Objects;
	@ApplicationScoped
	public class SaleRepository implements PanacheRepositoryBase<SaleEntity, Integer> {
	public Uni<List<SaleEntity>> listWithPaging(String sortBy, String orderBy, Integer page, Integer size) {
	if (page < 1) page = 1;
	if (size < 1) size = 5;
	page = page – 1; // zero-based
	if (sortBy == null) sortBy = "id";
	Sort.Direction direction = Sort.Direction.Ascending;
	if (Objects.equals(orderBy, "desc")) direction = Sort.Direction.Descending;
	return SaleEntity.findAll(Sort.by(sortBy).direction(direction)).page(page, size).list();
	}
	public Uni<List<SaleEntity>> getBySellerId(Integer id) {
	return SaleEntity.find("#SaleEntity.getBySellerId", id).list();
	}
	public Uni<List<SaleEntity>> getByEventId(Integer id) {
	return SaleEntity.find("#SaleEntity.getByEventId", id).list();
	}
	}

view raw SaleRepository.java hosted with ❤ by GitHub

Resource Class

Lastly, each table in the PostgreSQL TICKIT database has a corresponding resource class. According to the Quarkus documentation, all the operations defined within PanacheEntityBase are available on your repository, so using it is exactly the same as using the active record pattern, except you need to inject it. We inject the corresponding repository class into the resource class, exposing all the available methods of the repository and PanacheRepositoryBase. For example, note the custom listWithPaging method below, which was declared in the SaleRepository class.

Similar to the repository class, each method defined in the resource class also returns a SmallRye Mutiny (io.smallrye.mutiny) Uni<T>.

The repository defines HTTP methods (POST, GET, PUT, and DELETE) corresponding to CRUD operations on the database (Create, Read, Update, and Delete). The methods are annotated with the corresponding javax.ws.rs annotation, indicating the type of HTTP request they respond to. The javax.ws.rs package contains high-level interfaces and annotations used to create RESTful service resources, such as our Quarkus application.

The POST, PUT, and DELETE annotated methods all have the io.quarkus.hibernate.reactive.panache.common.runtime package’s ReactiveTransactional annotation associated with them. We use this annotation on methods to run them in a reactive Mutiny.Session.Transation. If the annotated method returns a Uni, which they do, this has precisely the same behavior as if the method was enclosed in a call to Mutiny.Session.withTransaction(java.util.function.Function). If the method call fails, the complete transaction is rolled back.

	package com.tickit.sale;
	import io.quarkus.hibernate.reactive.panache.common.runtime.ReactiveTransactional;
	import io.smallrye.mutiny.Uni;
	import org.jboss.resteasy.reactive.ResponseStatus;
	import javax.inject.Inject;
	import javax.ws.rs.*;
	import javax.ws.rs.core.MediaType;
	import java.util.List;
	@Path("sales")
	@Produces(MediaType.APPLICATION_JSON)
	@Consumes(MediaType.APPLICATION_JSON)
	public class SaleResource {
	@Inject
	SaleRepository saleRepository;
	@GET
	public Uni<List<SaleEntity>> list(
	@QueryParam("sort_by") String sortBy,
	@QueryParam("order_by") String orderBy,
	@QueryParam("page") int page,
	@QueryParam("size") int size
	) {
	return saleRepository.listWithPaging(sortBy, orderBy, page, size);
	}
	@GET
	@Path("{id}")
	public Uni<SaleEntity> get(Integer id) {
	return SaleEntity.findById(id);
	}
	@POST
	@ResponseStatus(201)
	@ReactiveTransactional
	public Uni<SaleEntity> create(SaleEntity sale) {
	return SaleEntity.persist(sale).replaceWith(sale);
	}
	@PUT
	@Path("{id}")
	@ReactiveTransactional
	public Uni<SaleEntity> update(Integer id, SaleEntity sale) {
	return SaleEntity.<SaleEntity>findById(id).onItem().ifNotNull().invoke(
	entity -> {
	entity.quantitySold = sale.quantitySold;
	entity.pricePaid = sale.pricePaid;
	entity.commission = sale.commission;
	entity.saleTime = sale.saleTime;
	entity.listing = sale.listing;
	entity.buyer = sale.buyer;
	}
	);
	}
	@DELETE
	@Path("{id}")
	@ReactiveTransactional
	public Uni<Void> delete(Integer id) {
	return SaleEntity.deleteById(id).replaceWithVoid();
	}
	@GET
	@Path("/event/{id}")
	public Uni<List<SaleEntity>> getByEventId(Integer id) {
	return saleRepository.getByEventId(id);
	}
	@GET
	@Path("/listing/{id}")
	public Uni<List<SaleEntity>> getByListingId(Integer id) {
	return SaleEntity.list("listid", id);
	}
	@GET
	@Path("/buyer/{id}")
	public Uni<List<SaleEntity>> getByBuyerId(Integer id) {
	return SaleEntity.list("buyerid", id);
	}
	@GET
	@Path("/seller/{id}")
	public Uni<List<SaleEntity>> getBySellerId(Integer id) {
	return saleRepository.getBySellerId(id);
	}
	@GET
	@Path("/count")
	public Uni<Long> count() {
	return SaleEntity.count();
	}
	}

view raw SaleResource.java hosted with ❤ by GitHub

Developer Experience

Quarkus has several features to enhance the developer experience. Features include Dev Services, Dev UI, live reload of code without requiring a rebuild and restart of the application, continuous testing where tests run immediately after code changes have been saved, configuration profiles, Hibernate ORM, JUnit, and REST Assured integrations. Using these Quarkus features, it’s easy to develop and test Quarkus applications.

Configuration Profiles

Similar to Spring, Quarkus works with configuration profiles. According to RedHat, you can use different configuration profiles depending on your environment. Configuration profiles enable you to have multiple configurations in the same application.properties file and select between them using a profile name. Quarkus recognizes three default profiles:

• dev: Activated in development mode
• test: Activated when running tests
• prod: The default profile when not running in development or test mode

In the application.properties file, the profile is prefixed using %environment. format. For example, when defining Quarkus’ log level as INFO, you add the common quarkus.log.level=INFO property. However, to change only the test environment’s log level to DEBUG, corresponding to the test profile, you would add a property with the %test. prefix, such as %test.quarkus.log.level=DEBUG.

Dev Services

Quarkus supports the automatic provisioning of unconfigured services in development and test mode, referred to as Dev Services. If you include an extension and do not configure it, then Quarkus will automatically start the relevant service using Test containers behind the scenes and wire up your application to use this service.

When developing your Quarkus application, you could create your own local PostgreSQL database, for example, with Docker:

	docker run –name postgres-dev \
	-p 5432:5432 \
	-e POSTGRES_DB=tickit \
	-e POSTGRES_USER=postgres \
	-e POSTGRES_PASSWORD=postgres123 \
	-d postgres:14.2-alpine3.15

view raw docker-postgres.sh hosted with ❤ by GitHub

And the corresponding application configuration properties:

	quarkus.datasource.username=postgres
	quarkus.datasource.password=postgres123
	quarkus.datasource.reactive.url=vertx-reactive:postgresql://localhost:5432/tickit

view raw application.properties hosted with ❤ by GitHub

Zero-Config Database

Alternately, we can rely on Dev Services, using a feature referred to as zero config setup. Quarkus provides you with a zero-config database out of the box; no database configuration is required. Quarkus takes care of provisioning the database, running your DDL and DML statements to create database objects and populate the database with test data, and finally, de-provisioning the database container when the development or test session is completed. The database Dev Services will be enabled when a reactive or JDBC datasource extension is present in the application and the database URL has not been configured.

Using the quarkusDev Gradle task, we can start the application running, as shown in the video below. Note the two new Docker containers that are created. Also, note the project’s import.sql SQL script is run automatically, executing all DDL and DML statements to prepare and populate the database.

Bootstrapping the TICKIT Database

When using Hibernate ORM with Quarkus, we have several options regarding how the database is handled when the Quarkus application starts. These are defined in the application.properties file. The quarkus.hibernate-orm.database.generation property determines whether the database schema is generated or not. drop-and-create is ideal in development mode, as shown above. This property defaults to none, however, if Dev Services is in use and no other extensions that manage the schema are present, this will default to drop-and-create. Accepted values: none, create, drop-and-create, drop, update, validate. For development and testing modes, we are using Dev Services with the default value of drop-and-create. For this post, we assume the database and schema already exist in production.

A second property, quarkus.hibernate-orm.sql-load-script, provides the path to a file containing the SQL statements to execute when Hibernate ORM starts. In dev and test modes, it defaults to import.sql. Simply add an import.sql file in the root of your resources directory, Hibernate will be picked up without having to set this property. The project contains an import.sql script to create all database objects and a small amount of test data. You can also explicitly set different files for different profiles and prefix the property with the profile (e.g., %dev. or %test.).

%dev.quarkus.hibernate-orm.database.generation=drop-and-create
%dev.quarkus.hibernate-orm.sql-load-script=import.sql

Another option is Flyway, the popular database migration tool commonly used in JVM environments. Quarkus provides first-class support for using Flyway.

Dev UI

According to the documentation, Quarkus now ships with a new experimental Dev UI, which is available in dev mode (when you start Quarkus with Gradle’s quarkusDev task) at /q/dev by default. It allows you to quickly visualize all the extensions currently loaded, see their status and go directly to their documentation. In addition to access to loaded extensions, you can review logs and run tests in the Dev UI.

Configuration

From the Dev UI, you can access and modify the Quarkus application’s application configuration.

You also can view the configuration of Dev Services, including the running containers and no-config database config.

Quarkus REST Score Console

With RESTEasy Reactive extension loaded, you can access the Quarkus REST Score Console from the Dev UI. The REST Score Console shows endpoint performance through scores and color-coding: green, yellow, or red. RedHat published a recent blog that talks about the scoring process and how to optimize the performance endpoints. Three measurements show whether a REST reactive application can be optimized further.

Application Testing

Quarkus enables robust JVM-based and Native continuous testing by providing integrations with common test frameworks, such as including JUnit, Mockito, and REST Assured. Many of Quarkus’ testing features are enabled through annotations, such as QuarkusTestResource, QuarkusTest, QuarkusIntegrationTest, and TransactionalQuarkusTest.

Quarkus supports the use of mock objects using two different approaches. You can either use CDI alternatives to mock out a bean for all test classes or use QuarkusMock to mock out beans on a per-test basis. This includes integration with Mockito.

The REST Assured integration is particularly useful for testing the Quarkus microservice API application. According to their website, REST Assured is a Java DSL for simplifying testing of REST-based services. It supports the most common HTTP request methods and can be used to validate and verify the response of these requests. REST Assured uses the given(), when(), then() methods of testing made popular as part of Behavior-Driven Development (BDD).

	@Test
	void listWithQueryParams() {
	List<CategoryEntity> category = given()
	.when()
	.get("v1/categories?page=2&size=4&sort_by=id")
	.then()
	.statusCode(Response.Status.OK.getStatusCode())
	.extract()
	.as(new TypeRef<>() {});
	Assertions.assertEquals(category.size(), 4);
	Assertions.assertEquals(category.get(0).id, 5);
	}

view raw test.java hosted with ❤ by GitHub

The tests can be run using the the quarkusTest Gradle task. The application contains a small number of integration tests to demonstrate this feature.

Swagger and OpenAPI

Quarkus provides the Smallrye OpenAPI extension compliant with the MicroProfile OpenAPI specification, which allows you to generate an API OpenAPI v3 specification and expose the Swagger UI. The /q/swagger-ui resource exposes the Swagger UI, allowing you to visualize and interact with the Quarkus API’s resources without having any implementation logic in place.

Resources can be tested using the Swagger UI without writing any code.

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. The /q/openapi resource allows you to generate an OpenAPI v3 specification file. An OpenAPI file allows you to describe your entire API.

The OpenAPI v3 specification can be saved as a file and imported into applications like Postman, the API platform for building and using APIs.

GitOps with GitHub Actions

For this post, GitOps is used to continuously test, build, package, and deploy the Quarkus microservice application to Kubernetes. Specifically, the post uses GitHub Actions. GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipelines. Workflows are defined in the .github/workflows directory in a repository, and a repository can have multiple workflows, each of which can perform a different set of tasks.

Two GitHub Actions are associated with this post’s GitHub repository. The first action, build-test.yml, natively builds and tests the source code in a native Mandrel container on each push to GitHub. The second action (shown below), docker-build-push.yml, builds and containerizes the natively-built executable, pushes it to Docker’s Container Registry (docker.io), and finally deploys the application to Kubernetes. This action is triggered by pushing a new Git Tag to GitHub.

There are several Quarkus configuration properties included in the action’s build step. Alternately, these properties could be defined in the application.properties file. However, I have decided to include them as part of the Gradle build task since they are specific to the type of build and container registry and Kubernetes platform I am pushing to artifacts.

	name: Quarkus Native Docker Build, Push, Deploy
	on:
	push:
	tags:
	– "*.*.*"
	jobs:
	build:
	runs-on: ubuntu-latest
	steps:
	– name: Check out the repo
	uses: actions/checkout@v3
	– name: Set up JDK 17
	uses: actions/setup-java@v3
	with:
	java-version: '17'
	distribution: 'corretto'
	cache: 'gradle'
	– name: Set the incremental Docker image tag
	run: |
	echo "RELEASE_VERSION=${GITHUB_REF:10}" >> $GITHUB_ENV
	env | sort
	– name: Validate Gradle wrapper
	uses: gradle/wrapper-validation-action@e6e38bacfdf1a337459f332974bb2327a31aaf4b
	– name: Build and push Quarkus native Docker image
	uses: gradle/gradle-build-action@0d13054264b0bb894ded474f08ebb30921341cee
	with:
	arguments: |
	build
	-Dquarkus.package.type=native
	-Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel:22.1.0.0-Final-java17
	-Dquarkus.docker.dockerfile-native-path=src/main/docker/Dockerfile.native-micro
	-Dquarkus.native.container-build=true
	-Dquarkus.container-image.group=${GITHUB_REPOSITORY_OWNER}
	-Dquarkus.container-image.tag=${{ env.RELEASE_VERSION }}
	-Dquarkus.kubernetes.replicas=4
	-Dquarkus.kubernetes-config.secrets=tickit
	-Dquarkus.kubernetes-config.secrets.enabled=true
	-Dquarkus.kubernetes.service-type=node-port
	-Dquarkus.kubernetes.node-port=32319
	-Dquarkus.kubernetes.part-of=tickit-app
	-Dquarkus.kubernetes.version=1.0.0
	-Dquarkus.kubernetes.name=tickit-srv
	-Dquarkus.kubernetes.resources.requests.memory=64Mi
	-Dquarkus.kubernetes.resources.requests.cpu=250m
	-Dquarkus.kubernetes.resources.limits.memory=128Mi
	-Dquarkus.kubernetes.resources.limits.cpu=500m
	-Dquarkus.container-image.username=${{ secrets.DOCKERHUB_USERNAME }}
	-Dquarkus.container-image.password=${{ secrets.DOCKERHUB_PASSWORD }}
	-Dquarkus.container-image.push=true
	–info
	– name: Display Kubernetes resources
	run: cat build/kubernetes/kubernetes.yml
	– name: Configure AWS credentials
	uses: aws-actions/configure-aws-credentials@v1
	with:
	aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
	aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
	aws-region: us-east-1
	– name: Apply resources
	uses: kodermax/kubectl-aws-eks@master
	env:
	KUBE_CONFIG_DATA: ${{ secrets.KUBE_CONFIG_DATA }}
	KUBECTL_VERSION: "v1.23.6"
	IAM_VERSION: "0.5.8"
	with:
	args: apply -f build/kubernetes/kubernetes.yml -n tickit
	– name: Get Kubernetes resources
	uses: kodermax/kubectl-aws-eks@master
	env:
	KUBE_CONFIG_DATA: ${{ secrets.KUBE_CONFIG_DATA }}
	KUBECTL_VERSION: "v1.23.6"
	IAM_VERSION: "0.5.8"
	with:
	args: get all -n tickit
	– name: Upload Kubernetes artifact
	uses: actions/upload-artifact@v3
	with:
	name: kubernetes-artifact
	path: build/kubernetes/kubernetes.yml

view raw docker-build-push.yml hosted with ❤ by GitHub

Kubernetes Resources

The Kubernetes resources YAML file, created by the Quarkus build, is also uploaded and saved as an artifact in GitHub by the final step in the GitHub Action.

Quarkus automatically generates ServiceAccount, Role, RoleBinding, Service, Deployment resources.

	—
	apiVersion: v1
	kind: ServiceAccount
	metadata:
	annotations:
	app.quarkus.io/build-timestamp: 2022-06-05 – 23:49:30 +0000
	labels:
	app.kubernetes.io/part-of: tickit-app
	app.kubernetes.io/version: 1.0.0
	app.kubernetes.io/name: tickit-srv
	name: tickit-srv
	—
	apiVersion: v1
	kind: Service
	metadata:
	annotations:
	app.quarkus.io/build-timestamp: 2022-06-05 – 23:49:30 +0000
	prometheus.io/scrape: "true"
	prometheus.io/path: /q/metrics
	prometheus.io/port: "8080"
	prometheus.io/scheme: http
	labels:
	app.kubernetes.io/name: tickit-srv
	app.kubernetes.io/part-of: tickit-app
	app.kubernetes.io/version: 1.0.0
	name: tickit-srv
	spec:
	ports:
	– name: http
	nodePort: 32319
	port: 80
	targetPort: 8080
	selector:
	app.kubernetes.io/name: tickit-srv
	app.kubernetes.io/part-of: tickit-app
	app.kubernetes.io/version: 1.0.0
	type: NodePort
	—
	apiVersion: rbac.authorization.k8s.io/v1
	kind: Role
	metadata:
	name: view-secrets
	rules:
	– apiGroups:
	– ""
	resources:
	– secrets
	verbs:
	– get
	—
	apiVersion: rbac.authorization.k8s.io/v1
	kind: RoleBinding
	metadata:
	name: tickit-srv-view
	roleRef:
	kind: ClusterRole
	apiGroup: rbac.authorization.k8s.io
	name: view
	subjects:
	– kind: ServiceAccount
	name: tickit-srv
	—
	apiVersion: rbac.authorization.k8s.io/v1
	kind: RoleBinding
	metadata:
	name: tickit-srv-view-secrets
	roleRef:
	kind: Role
	apiGroup: rbac.authorization.k8s.io
	name: view-secrets
	subjects:
	– kind: ServiceAccount
	name: tickit-srv
	—
	apiVersion: apps/v1
	kind: Deployment
	metadata:
	annotations:
	app.quarkus.io/build-timestamp: 2022-06-05 – 23:49:30 +0000
	prometheus.io/scrape: "true"
	prometheus.io/path: /q/metrics
	prometheus.io/port: "8080"
	prometheus.io/scheme: http
	labels:
	app.kubernetes.io/part-of: tickit-app
	app.kubernetes.io/version: 1.0.0
	app.kubernetes.io/name: tickit-srv
	name: tickit-srv
	spec:
	replicas: 3
	selector:
	matchLabels:
	app.kubernetes.io/part-of: tickit-app
	app.kubernetes.io/version: 1.0.0
	app.kubernetes.io/name: tickit-srv
	template:
	metadata:
	annotations:
	app.quarkus.io/build-timestamp: 2022-06-05 – 23:49:30 +0000
	prometheus.io/scrape: "true"
	prometheus.io/path: /q/metrics
	prometheus.io/port: "8080"
	prometheus.io/scheme: http
	labels:
	app.kubernetes.io/part-of: tickit-app
	app.kubernetes.io/version: 1.0.0
	app.kubernetes.io/name: tickit-srv
	spec:
	containers:
	– env:
	– name: KUBERNETES_NAMESPACE
	valueFrom:
	fieldRef:
	fieldPath: metadata.namespace
	image: garystafford/tickit-srv:1.1.3
	imagePullPolicy: Always
	livenessProbe:
	failureThreshold: 3
	httpGet:
	path: /q/health/live
	port: 8080
	scheme: HTTP
	initialDelaySeconds: 0
	periodSeconds: 30
	successThreshold: 1
	timeoutSeconds: 10
	name: tickit-srv
	ports:
	– containerPort: 8080
	name: http
	protocol: TCP
	readinessProbe:
	failureThreshold: 3
	httpGet:
	path: /q/health/ready
	port: 8080
	scheme: HTTP
	initialDelaySeconds: 0
	periodSeconds: 30
	successThreshold: 1
	timeoutSeconds: 10
	resources:
	limits:
	cpu: 500m
	memory: 128Mi
	requests:
	cpu: 250m
	memory: 64Mi
	serviceAccountName: tickit-srv

view raw kubernetes.yml hosted with ❤ by GitHub

Choosing a Kubernetes Platform

The only cloud provider-specific code is in the second GitHub action.

	jobs:
	build:
	runs-on: ubuntu-latest
	steps:
	– name: Configure AWS credentials
	uses: aws-actions/configure-aws-credentials@v1
	with:
	aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
	aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
	aws-region: us-east-1
	– name: Apply resources
	uses: kodermax/kubectl-aws-eks@master
	env:
	KUBE_CONFIG_DATA: ${{ secrets.KUBE_CONFIG_DATA }}
	KUBECTL_VERSION: "v1.23.6"
	IAM_VERSION: "0.5.8"
	with:
	args: apply -f build/kubernetes/kubernetes.yml -n tickit

view raw aws_deploy_abridged.yml hosted with ❤ by GitHub

In this case, the application is being deployed to an existing Amazon Elastic Kubernetes Service (Amazon EKS), a fully managed, certified Kubernetes conformant service from AWS. These steps can be easily replaced with steps to deploy to other Cloud platforms, such as Microsoft’s Azure Kubernetes Service (AKS) or Google Cloud’s Google Kubernetes Engine (GKE).

GitHub Secrets

Some of the properties use GitHub environment variables, and others use secure GitHub repository encrypted secrets. Secrets are used to secure Docker credentials used to push the Quarkus application image to Docker’s image repository, AWS IAM credentials, and the base64 encoded contents of the kubeconfig file required to deploy to Kubernetes on AWS when using the kodermax/kubectl-aws-eks@master GitHub action.

Docker

Reviewing the configuration properties included in the action’s build step, note the Mandrel container used to build the native Quarkus application, quay.io/quarkus/ubi-quarkus-mandrel:22.1.0.0-Final-java17. Also, note the project’s Docker file is used to build the final Docker image, pushed to the image repository, and then used to provision containers on Kubernetes, src/main/docker/Dockerfile.native-micro. This Dockerfile uses the quay.io/quarkus/quarkus-micro-image:1.0 base image to containerize the native Quarkus application.

	FROM quay.io/quarkus/quarkus-micro-image:1.0
	WORKDIR /work/
	RUN chown 1001 /work \
	&& chmod "g+rwX" /work \
	&& chown 1001:root /work
	COPY –chown=1001:root build/*-runner /work/application
	EXPOSE 8080
	USER 1001
	CMD ["./application", "-Dquarkus.http.host=0.0.0.0"]

view raw Dockerfile.native-micro hosted with ❤ by GitHub

The properties also define the image’s repository name and tag (e.g., garystafford/tickit-srv:1.1.0).

Kubernetes

In addition to creating the ticket Namespace in advance, a Kubernetes secret is pre-deployed to the ticket Namespace. The GitHub Action also requires a Role and RoleBinding to deploy the workload to the Kubernetes cluster. Lastly, a HorizontalPodAutoscaler (HPA) is used to automatically scale the workload.

export NAMESPACE=tickit# Namespace
kubectl create namespace ${NAMESPACE}# Role and RoleBinding for GitHub Actions to deploy to Amazon EKS
kubectl apply -f kubernetes/github_actions_role.yml -n ${NAMESPACE}# Secret
kubectl apply -f kubernetes/secret.yml -n ${NAMESPACE}# HorizontalPodAutoscaler (HPA)
kubectl apply -f kubernetes/tickit-srv-hpa.yml -n ${NAMESPACE}

As part of the configuration properties included in the action’s build step, note the use of Kubernetes secrets.

-Dquarkus.kubernetes-config.secrets=tickit
-Dquarkus.kubernetes-config.secrets.enabled=true

This secret contains base64 encoded sensitive credentials and connection values to connect to the Production PostgreSQL database. For this post, I have pre-built an Amazon RDS for PostgreSQL database instance, created the ticket database and required database objects, and lastly, imported the sample data included in the GitHub repository, garystafford/tickit-srv-data.

	apiVersion: v1
	kind: Secret
	metadata:
	name: tickit
	type: Opaque
	data:
	DB_USERNAME: Y2hhbmdlbWU=
	DB_PASSWORD: Y2hhbmdlbWVhbHNv
	DB_HOST: Y2hhbmdlLm1lLnVzLWVhc3QtMS5yZHMuYW1hem9uYXdzLmNvbQ==
	DB_PORT: NTQzMg==
	DB_DATABASE: dGlja2l0

view raw secret.yml hosted with ❤ by GitHub

The five keys seen in the Secret are used in the application.properties file to provide access to the Production PostgreSQL database from the Quakus application.

	%prod.quarkus.datasource.username=${DB_USERNAME}
	%prod.quarkus.datasource.password=${DB_PASSWORD}
	%prod.quarkus.datasource.reactive.url=vertx-reactive:postgresql://${DB_HOST}:${DB_PORT}/${DB_DATABASE}
	%prod.quarkus.hibernate-orm.database.generation=none
	%prod.quarkus.hibernate-orm.sql-load-script=no-file

view raw prod-configuration.properties hosted with ❤ by GitHub

An even better alternative to using Kubernetes secrets on Amazon EKS is AWS Secrets and Configuration Provider (ASCP) for the Kubernetes Secrets Store CSI Driver. AWS Secrets Manager stores secrets as files mounted in Amazon EKS pods.

AWS Architecture

The GitHub Action pushes the application’s image to Docker’s Container Registry (docker.io), then deploys the application to Kubernetes. Alternately, you could use AWS’s Amazon Elastic Container Registry (Amazon ECR). Amazon EKS pulls the image from Docker as it creates the Kubernetes Pod containers.

There are many ways to route traffic from a requestor to the Quarkus application running on Kubernetes. For this post, the Quarkus application is exposed as a Kubernetes Service on a NodePort. For this post, I have registered a domain, example-api.com, with Amazon Route 53 and a corresponding TLS certificate with AWS Certificate Manager. Inbound requests to the Quarkus application are directed to a subdomain, ticket.example-api.com using HTTPS or port 443. Amazon Route 53 routes those requests to a Layer 7 application load balancer (ALB). The ALB then routes those requests to the Amazon EKS Kubernetes cluster on the NodePort using simple round-robin load balancing. Requests will be routed automatically by Kubernetes to the appropriate worker node and Kubernetes pod. The response then traverses a similar path back to the requestor.

Results

If the GitHub action is successful, any push of code changes to GitHub results in the deployment of the application to Kubernetes.

We can also view the deployed Quarkus application resources using the Kubernetes Dashboard.

Metrics

The post’s Quarkus application implements the micrometer-registry-prometheus extension. The Micrometer metrics library exposes runtime and application metrics. Micrometer defines a core library, providing a registration mechanism for metrics and core metric types.

Using the Micrometer extension, a metrics resource is exposed at /q/metrics, which can be scraped and visualized by tools such as Prometheus. AWS offers its fully-managed Amazon Managed Service for Prometheus (AMP), which easily integrates with Amazon EKS.

Using Prometheus as a datasource, we can build dashboards in Grafana to observe the Quarkus Application metrics. Similar to AMP, AWS offers its fully managed Amazon Managed Grafana (AMG).

Centralized Log Management

According to Quarkus documentation, internally, Quarkus uses JBoss Log Manager and the JBoss Logging facade. You can use the JBoss Logging facade inside your code or any of the supported Logging APIs, including JDK java.util.logging (aka JUL), JBoss Logging, SLF4J, and Apache Commons Logging. Quarkus will send them to JBoss Log Manager.

There are many ways to centralize logs. For example, you can send these logs to open-source centralized log management systems like Graylog, Elastic Stack, fka ELK (Elasticsearch, Logstash, Kibana), EFK (Elasticsearch, Fluentd, Kibana), and OpenSearch with Fluent Bit.

If you are using Kubernetes, the simplest way is to send logs to the console and integrate a central log manager inside your cluster. Since the Quarkus application in this post is running on Amazon EKS, I have chosen Amazon OpenSearch Service with Fluent Bit, an open-source and multi-platform Log Processor and Forwarder. Fluent Bit is fully compatible with Docker and Kubernetes environments. Amazon provides an excellent workshop on installing and configuring Amazon OpenSearch Service with Fluent Bit.

Conclusion

As we learned in this post, Quarkus, the ‘Supersonic Subatomic Java’ framework, is a cloud-native, Kubernetes-native, container first, microservices first framework for writing Java applications. We observed how to build, test, and deploy a RESTful Quarkus Native application to Kubernetes.

Quarkus has capabilities and features well beyond this post’s scope. In a future post, we will explore other abilities of Quarkus, including observability, GraphQL integration, caching, database proxying, tracing and debugging, message queues, data pipelines, and streaming analytics.

---

This blog represents my own viewpoints and not of my employer, Amazon Web Services (AWS). All product names, logos, and brands are the property of their respective owners. All diagrams and illustrations are property of the author.