The typical way to deploy and run applications on K8S is to provide YAML manifest files defining the kind of K8S controllers to be used, for example pods, deployments, services, etc. It’s quite common that, in order to deploy and run a simple Spring Boot application that does “hello world”, one needs a half dozen of YAML manifest files. And the fact that these files could be concatenated in a single one doesn’t change much to the fact that, at the end of the day, almost 100 YAML lines are required for such a simple operation.

The good news is that, using Cloud Native Buildpacks, you don’t need to provide anymore all these YAML files and to bother with K8S details, because the spring -boot-maven-plugin is able to generate the Docker image of the application, by simply leveraging its build-image goal.

Here is the plugin configuration:

  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
      <image>
        <name>nicolasduminil/k8s-sb:buildpacks</name>
        <env>
          <BP_JVM_VERSION>25</BP_JVM_VERSION>
        </env>
        <publish>true</publish>
      </image>
    </configuration>
  </plugin>

The name element above overrides the Docker image name that will be generated while the env element defines the JVM version. The generated image is published on DockerHub registry. By default, Spring Boot uses Packeto Bellsoft Liberica Java Buildpack, which is a Cloud Native Buildpacks provider. If you prefer to use another one, you need then to override the buildpacks list in the Maven plugin configuration, for example:

  <plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
      <image>
        <name>nicolasduminil/k8s-sb:buildpacks</name>
        <buildpack>
          <buildpack>gcr.io/packeto-buildpacks/adoptium:latest<buldpack>
          <buildpack>urn:cnb:builder:paketo-buildpacks/java</buildpack>
        </env>
        <publish>true</publish>
      </image>
    </configuration>
  </plugin>

The configuration above allows to use Eclipse Temurin instead of Bellsoft Liberica OpenJDK.

Building, deploying and running

In order to build the application execute the following command:

$ mvn clean package spring-boot:build-image

This will create the application JAR and the Docker image associated to it. You should see something like:

INFO] Successfully built image 'docker.io/nicolasduminil/k8s-sb:buildpacks'
[INFO]
[INFO]  > Pushing image 'docker.io/nicolasduminil/k8s-sb:buildpacks' 11%
[INFO]  > Pushing image 'docker.io/nicolasduminil/k8s-sb:buildpacks' 15%
[INFO]  > Pushing image 'docker.io/nicolasduminil/k8s-sb:buildpacks' 15%
[INFO]  > Pushing image 'docker.io/nicolasduminil/k8s-sb:buildpacks' 100%
[INFO]  > Pushed image 'docker.io/nicolasduminil/k8s-sb:buildpacks'

Now, start minikube if not already done:

$ minikube start
😄  minikube v1.32.0 on Ubuntu 24.04  
✨  Using the docker driver based on user configuration
📌  Using Docker driver with root privileges
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🔥  Creating docker container (CPUs=2, Memory=7900MB) ...
🐳  Preparing Kubernetes v1.28.3 on Docker 24.0.7 ...
▪ Generating certificates and keys ...
▪ Booting up control plane ...
▪ Configuring RBAC rules ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🔎  Verifying Kubernetes components...
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Next, you need to create a deployment:

$ kubectl create deployment k8s-sb --image nicolasduminil/k8s-sb:buildpacks

and to expose the associated service:

$ kubectl expose deployment k8s-sb --type=NodePort --port=8080

In order to invoke the REST endpoint, you need to have its public URL. The following command will show it to you:

$ minikube service list
|-------------|------------|--------------|---------------------------|
|  NAMESPACE  |    NAME    | TARGET PORT  |            URL            |
|-------------|------------|--------------|---------------------------|
| default     | k8s-sb     |         8080 | http://192.168.49.2:30809 |
| default     | kubernetes | No node port |                           |
| kube-system | kube-dns   | No node port |                           |
|-------------|------------|--------------|---------------------------|

All you need to do now is to send a HTTP GET request to the endpoint, as follows:

curl http://192.168.49.2:30809/hello/nicolas
Hello nicolas

As you can see, as a proof a goodwill the endpoint greets you.

You’ve succeeded to release a Spring Boot application on Kubernetes without having to write a line of YAML. Congratulations. Now, stay tuned to see what comes next.

The Strategy

This design pattern belongs to the behavioral category and its purpose is to define a family of algorithms, encapsulate each one of them and make them interchangeable, such that the algorithm may vary independently of its consumer. Where the decorator asked what else should happen to this object ?, the strategy asks which one of these algorithms should be applied ?.

We keep the same Product domain and we compute a shipping cost for it. Three interchangeable algorithms are provided:

• Standard: a flat 4.99 fee.
• Express: 9.99 plus 2% of the product price.
• FreeOver: the familiar “free delivery over 50.00” commercial rule. It is parameterized by a price threshold and by the strategy to apply when the threshold isn’t reached. Should the product price be greater than or equal to the threshold, the shipping is free, otherwise the product doesn’t qualify and the cost is the one computed by that other strategy.

For our 100.00 book, the standard shipping costs 4.99, the express one costs 11.99 and, with a 50.00 threshold, the free-over one costs 0.00, since 100.00 is above the threshold. Raising that same threshold to 150.00 falls back to the standard shipping and, hence, to 4.99. Notice that, unlike the visitor, nothing here varies per product type: what varies is the algorithm and it is the caller that picks it.

The object-oriented approach

The figure below shows the class diagram of the object-oriented strategy:

The classic Gang of Four Strategy declares an interface for the family of the algorithms and one class per algorithm:

public interface ShippingStrategy
{
  BigDecimal cost(Product product);
}

public class ExpressShipping implements ShippingStrategy
{
  private static final BigDecimal FEE = new BigDecimal("9.99");
  private static final BigDecimal RATE = new BigDecimal("0.02");

  public BigDecimal cost(Product product)
  {
    return FEE.add(product.price().multiply(RATE).setScale(2, RoundingMode.HALF_UP));
  }
}

An algorithm that needs to be parameterized becomes a class with state. Here FreeOverShipping holds its threshold and the strategy to fall back to:

public FreeOverShipping(BigDecimal threshold, ShippingStrategy otherwise) { ... }

public BigDecimal cost(Product product)
{
  return product.price().compareTo(threshold) >= 0 ? FREE : otherwise.cost(product);
}

Last but not least, the ShippingCalculator class, as the context, is the object that uses the algorithm without knowing which one it is. It only holds a reference to the interface, which is what allows the algorithm to be replaced at runtime:

ShippingCalculator calculator = new ShippingCalculator(new StandardShipping());
BigDecimal cost = calculator.cost(book);      // 4.99

calculator.setStrategy(new ExpressShipping());
cost = calculator.cost(book);                 // 11.99

Contrary to the visitor and to the decorator, the strategy doesn’t require anything at all from the elements it processes: no accept method and no shared component interface. Consequently, and this is the first time it happens on the object-oriented side, the module reuses the sealed common.Product directly, with neither its own hierarchy, nor any adapter.

The functional approach

Look now at the class diagram of the functional style implementation:

Of all the patterns seen so far, this is the one where the functional answer is the most radical. The interface ShippingStrategy in the OO implementation declares one single method and, like any interface, holds no state, such that everything it tells us is a Product comes in, a BigDecimal comes out.

In functional terms, this is nothing more than a Function<Product, BigDecimal> type. So each algorithm becomes a plain value of the function type, for example:

public static final Function<Product, BigDecimal> EXPRESS = product ->
  EXPRESS_FEE.add(product.price().multiply(EXPRESS_RATE).setScale(2, RoundingMode.HALF_UP));

As opposed to the OO side which required the FreeOverShipping class holding the threshold and the shipping strategy, the FP side captures them in a closure. So this class on the OO side becomes on the FP side a higher-order function, i.e. a function returning the strategy itself:

public static Function<Product, BigDecimal> freeOver(BigDecimal threshold,
  Function<Product, BigDecimal> otherwise)
{
  return product -> product.price().compareTo(threshold) >= 0 ? FREE : otherwise.apply(product);
}

The very same happens to ShippingCalculator, the context class on the OOP side. Its whole reason to exist was to hold a strategy in a field, such that its cost() and total() operations could delegate to it. But a context is just an operation parameterized by an algorithm and this, once again, is precisely a higher-order function. Hence, the ShippingCalculator.total() method on the OO side becomes on the FP one:

public static Function<Product, BigDecimal> totalWith(Function<Product, BigDecimal> strategy)
{
  return product -> product.price().add(strategy.apply(product));
}

such that the following call on the OO side, shown above:

ShippingCalculator calculator = new ShippingCalculator(new StandardShipping());
...
BigDecimal total = calculator.total(book);

becomes on the FP side:

BigDecimal total = totalWith(STANDARD).apply(book);

There is no property to hold the strategy anymore and, consequently, no setStrategy() method either. Here the strategy is an argument which doesn’t need to be stored in the context, just call the function with the right value and that’s all.

But the real advantage of the strategies as ordinary values is that they can be combined. Picking the cheapest of several shipping options requires yet another class on the OO side, while here it’s a simple combinator:

Function<Product, BigDecimal> best = cheapest(STANDARD, EXPRESS);   // 4.99

And as usual, they compose with andThen, for example to apply a promotion to whatever cost has been computed:

Function<Product, BigDecimal> promo =
  EXPRESS.andThen(cost -> cost.divide(TWO, 2, RoundingMode.HALF_UP));   // 6.00

The OO Strategy encapsulates each algorithm in a class implementing a common interface and injects the chosen one into a context object, while the functional one observes that such an interface describes nothing but a function type which the JDK already provides and, consequently, keeps only the algorithms themselves. “Turtles all the way down”, and both compute the same cost.

Project structure

The code is organized as a multi-module Maven project. The product domain lives in its own common module: a sealed Product interface, the three product records and the ProductType enumerated which already carries the FP factory function seen above. Everything that can reuse that domain does:

oop-fp-design-patterns        (parent POM)
├── common                    sealed Product, the records, ProductType(+factory)
├── factory   (→ common)      ProductFactory (OOP); the FP factory *is* common.ProductType
├── visitor   (→ common)      FP: operations over the common records (switch + lambda bundle)
│                             OOP: its own element hierarchy (see below)
├── builder   (→ common)      immutable Order over the common records; OOP: fluent
│                             OrderBuilder; FP: composed UnaryOperator<Order> steps
├── decorator (→ common)      FP: composed UnaryOperator<Product> decorations over the
│                             common records; OOP: its own Product interface (see below)
└── strategy  (→ common)      shipping algorithms over the common records; OOP: the
                              ShippingStrategy hierarchy + context; FP: plain
                              Function<Product, BigDecimal> values

The FP factory, the FP visitor and the FP decorator all operate directly on the common records, so nothing is duplicated there, and the Strategy does so on both of its sides. The two exceptions are the object-oriented Visitor and the object-oriented Decorator.

The Visitor needs an accept method on every element (double dispatch); the Decorator needs a non-sealed Product interface that its wrappers can implement. In both cases common.Product is sealed and cannot be extended from another module, so each owns its own element/component types and reuses only the ProductType enumerated - the OOP decorator bridges back to common through a small BaseProduct adapter. This asymmetry is not accidental.

The classic Visitor requires every element to expose an accept method and the classic Decorator requires every component to share the wrappers’ interface; both couple the elements to the pattern’s abstraction, so they cannot be the sealed records defined in common. The functional approach has no such coupling: it operates over the sealed type from the outside - pattern-matching for the visitor, rebuilding through the factory for the decorator - so the elements know nothing about the operations applied to them and, hence, can be the shared common records.

The Strategy confirms the rule the other way around: it doesn’t couple the elements to its abstraction either, only the client to it, and this is precisely why it is the only pattern here whose object-oriented implementation reuses common as freely as its functional one.

The full code of these examples, including the associated unit tests, can be found here.

The Decorator

This design pattern belongs to the structural category and its purpose is to attach additional responsibilities to an object dynamically, by wrapping it in another object that shares the same interface. It is the flexible alternative to subclassing for extending behavior: rather than a combinatorial explosion of DiscountedTaxedGiftWrappedProduct subclasses, you wrap a product in as many independent decorators as you need, and they stack.

We reuse the same Product domain. Each decorator changes the price() and the description() while leaving everything else untouched. To keep the pattern visibly distinct from the visitor, whose rules varied per product type, the decorators here apply the same rule to every product:

• Discounted: 10% off the wrapped price.
• Taxed: adds 20% VAT to the wrapped price.
• GiftWrapped: adds a flat 5.00 wrapping fee.

Because they stack, a 100.00 book decorated Discounted → Taxed → GiftWrapped goes 100.00 → 90.00 → 108.00 → 113.00, and its description reads "A book (discounted) (VAT incl.) (gift-wrapped)".

The object-oriented approach

The figure below shows the class diagram of the object-oriented decorator:

The classic Gang of Four Decorator is an object that implements the component interface and holds a reference to another component, delegating the untouched operations and overriding the ones it enhances. An abstract ProductDecorator captures the delegation once:

public abstract class ProductDecorator implements Product
{
  protected final Product product;

  protected ProductDecorator(Product product)
  {
    this.product = Objects.requireNonNull(product, "Product is null");
  }

  public String name() { return product.name(); }
  public String description() { return product.description(); }
  public BigDecimal price() { return product.price(); }
  public ProductType type() { return product.type(); }
}

Each concrete decorator then overrides only what it changes:

public class Discounted extends ProductDecorator
{
  private static final BigDecimal RATE = new BigDecimal("0.10");

  public Discounted(Product product) { super(product); }

  public BigDecimal price()
  {
    return product.price().subtract(amount(product.price(), RATE));
  }

  public String description()
  {
    return product.description() + " (discounted)";
  }
}

Since a decorator is a Product, decorators wrap decorators and the enhancements compose by nesting:

Product wrapped = new GiftWrapped(new Taxed(new Discounted(new BaseProduct(book))));
BigDecimal price = wrapped.price();   // 113.00

The leaf being wrapped is a BaseProduct, a small record that adapts a shared common.Product into the decorator’s own interface. This is necessary because common.Product is sealed and so, exactly like the object-oriented visitor, the decorator cannot make the common records implement its interface directly.

The functional approach

Look now at the class diagram of the functional style implementation:

The functional counterpart of a decorator is simply a function whicg maps a product to an enhanced product and implemented as an UnaryOperator<Product>. Because the common records are immutable, “enhancing” one means rebuilding it through the ProductType factory, already seen at the very beginning, which is why the FP side reuses common directly with no adapter:

public static final UnaryOperator<Product> DISCOUNTED = product ->
  product.type().newInstance(product.name(),
    product.description() + " (discounted)",
    product.price().subtract(amount(product.price(), "0.10")));

Being ordinary values, the decorations compose with andThen, exactly as the factory composed its factory function, the visitor composed its operations and the builder composed its steps:

UnaryOperator<Product> decorate = DISCOUNTED.andThen(TAXED).andThen(GIFT_WRAPPED);
Product wrapped = decorate.apply(book);   // price 113.00

And, just like the functional builder step, a decoration is a reusable first-class value. For example, the same discount could be applied twice:

Product wrapped = DISCOUNTED.andThen(DISCOUNTED).apply(book);   // 100 -> 90 -> 81

The object-oriented Decorator wraps the component in a stack of objects sharing its interface, while the functional one expresses the very same stacking as the composition of pure Product to Product functions. “Turtles all the way down”, and both land on the same enhanced product.

Project structure

The code is organized as a multi-module Maven project. The product domain lives in its own common module: a sealed Product interface, the three product records and the ProductType enumerated which already carries the FP factory function seen above. Everything that can reuse that domain does:

oop-fp-design-patterns        (parent POM)
├── common                    sealed Product, the records, ProductType(+factory)
├── factory   (→ common)      ProductFactory (OOP); the FP factory *is* common.ProductType
├── visitor   (→ common)      FP: operations over the common records (switch + lambda bundle)
│                             OOP: its own element hierarchy (see below)
├── builder   (→ common)      immutable Order over the common records; OOP: fluent
│                             OrderBuilder; FP: composed UnaryOperator<Order> steps
└── decorator (→ common)      FP: composed UnaryOperator<Product> decorations over the
                              common records; OOP: its own Product interface (see below)

The FP factory, the FP visitor and the FP decorator all operate directly on the common records, so nothing is duplicated there. The two exceptions are the object-oriented Visitor and the object-oriented Decorator. The Visitor needs an accept method on every element (double dispatch); the Decorator needs a non-sealed Product interface that its wrappers can implement. In both cases common.Product is sealed and cannot be extended from another module, so each owns its own element/component types and reuses only the ProductType enumerated - the OOP decorator bridges back to common through a small BaseProduct adapter. This asymmetry is not accidental. The classic Visitor requires every element to expose an accept method and the classic Decorator requires every component to share the wrappers’ interface; both couple the elements to the pattern’s abstraction, so they cannot be the sealed records defined in common. The functional approach has no such coupling: it operates over the sealed type from the outside - pattern-matching for the visitor, rebuilding through the factory for the decorator - so the elements know nothing about the operations applied to them and, hence, can be the shared common records.

The full code of these examples, including the associated unit tests, can be found here.

The Builder

This design pattern belongs to the creational category, like the factory, but it solves a different problem. The factory hides which concrete type gets instantiated while the Builder assembles a single, complex object step by step, separating its construction from its representation. It is the classic answer to the telescoping-constructor problem: an object with many parameters, among which some required, most optional, whose constructor would otherwise explode into a combinatorial set of overloads.

Our Product records have only three required fields, so they don’t motivate a builder. We therefore introduce an Order: a customer order that aggregates the common products as line items and adds several optional attributes - a coupon code, a gift-wrap flag and a free-text note. Whatever the style, the target is the same immutable value:

public record Order(
  String customer,
  String currency,
  List<Product> items,
  Optional<String> coupon,
  boolean giftWrapped,
  Optional<String> note)
{
  public Order
  {
    Objects.requireNonNull(customer, "Customer is null");
    Objects.requireNonNull(currency, "Currency is null");
    items = items == null ? List.of() : List.copyOf(items);
    coupon = coupon == null ? Optional.empty() : coupon;
    note = note == null ? Optional.empty() : note;
  }

  public BigDecimal subtotal() { ... }
}

The object-oriented approach

The figure below shows the class diagram of the object-oriented builder:

The classic Gang of Four Builder is a mutable accumulator. The required arguments are captured up front, the optional ones are added through fluent calls that all return this, and build() freezes the accumulated state into the immutable Order:

public final class OrderBuilder
{
  private final String customer;
  private final String currency;
  private final List<Product> items = new ArrayList<>();
  private String coupon;
  private boolean giftWrapped;
  private String note;

  public static OrderBuilder of(String customer, String currency) { ... }

  public OrderBuilder addItem(Product item) { items.add(item); return this; }
  public OrderBuilder coupon(String coupon) { this.coupon = coupon; return this; }
  public OrderBuilder giftWrap() { this.giftWrapped = true; return this; }
  public OrderBuilder note(String note) { this.note = note; return this; }

  public Order build()
  {
    return new Order(customer, currency, items,
      Optional.ofNullable(coupon), giftWrapped, Optional.ofNullable(note));
  }
}

Building an order reads as a sentence, and you only mention the parts you actually need:

Order order = OrderBuilder.of("Alice", "EUR")
  .addItem(book).addItem(phone)
  .coupon("SUMMER").giftWrap()
  .build();

The functional approach

Look now at the class diagram of the functional style implementation:

The functional counterpart keeps the same immutable Order target but drops the mutable accumulator. Each build step becomes a first-class UnaryOperator<Order> value - a pure function mapping one immutable Order to the next by returning a modified copy:

public static UnaryOperator<Order> addItem(Product item)
{
  return order -> new Order(order.customer(), order.currency(),
    Stream.concat(order.items().stream(), Stream.of(item)).toList(),
    order.coupon(), order.giftWrapped(), order.note());
}

Because the steps are ordinary values, they are not called on a builder, but they are composed with andThen, exactly as the factory composed its factory function and the visitor composed its operations:

Function<Order, Order> config = addItem(book)
  .andThen(addItem(phone))
  .andThen(coupon("SUMMER"))
  .andThen(giftWrap());

Order order = config.apply(OrderBuilder.empty("Alice", "EUR"));

This is more than a stylistic variation. In the OOP version a step is a method call that exists only for the duration of the chain. In the FP version a step is a value which can be stored it in a variable, passed to another method, kept in a list of steps and applied later, or reused the very same step twice:

UnaryOperator<Order> addBook = addItem(book);
Order order = addBook.andThen(addBook).apply(OrderBuilder.empty("Alice", "EUR"));

The object-oriented Builder wraps a stateful object around the immutable target while the functional one expresses construction as the composition of pure copy functions over it. “Turtles all the way down”, and both land on the same Order.

Project structure

The code is organized as a multi-module Maven project. The product domain lives in its own common module: a sealed Product interface, the three product records and the ProductType enumerated - which already carries the FP factory function seen above. Everything that can reuse that domain does:

oop-fp-design-patterns        (parent POM)
├── common                    sealed Product, the records, ProductType(+factory)
├── factory   (→ common)      ProductFactory (OOP); the FP factory *is* common.ProductType
├── visitor   (→ common)      FP: operations over the common records (switch + lambda bundle)
│                             OOP: its own element hierarchy (see below)
└── builder   (→ common)      immutable Order over the common records; OOP: fluent
                              OrderBuilder; FP: composed UnaryOperator<Order> steps

The FP factory and the FP visitor both operate directly on the common records, so nothing is duplicated there. The one exception is the object-oriented Visitor which needs an accept method on every element (double dispatch), and since common.Product is sealed it cannot be extended from another module. The OOP visitor therefore owns its element hierarchy and reuses only the ProductType enumerated. This asymmetry is not accidental. The classic Visitor requires every element to expose an accept method, which couples the elements to the visitor abstraction. These elements must be defined together with the visitor abstraction, and so cannot be the sealed records defined in common. The functional approach has no such coupling: it pattern-matches over the sealed type from the outside, so the elements know nothing about the operations applied to them and, hence, can be the shared common records.

The full code of these examples, including the associated unit tests, can be found here.

The Visitor

This design pattern belongs to the behavioral category and its purpose is to add new operations to an existing object hierarchy without modifying the classes of that hierarchy. It is the classic answer to the expression problem: when the set of types is stable but the set of operations grows, the Visitor lets you keep adding operations cheaply.

We reuse the same domain as the factory: a Product implemented by BookProduct, ElectronicProduct and FashionProduct. To give the visitor a reason to exist, each operation now behaves differently per product type:

• VAT: a reduced 5.5% rate for books, the standard 20% rate otherwise.
• Shipping: 10.00 + 2% of the price for fragile, insured electronics, a flat 3.00 for books and a flat 5.00 for fashion.
• Discount: 10% for electronics, 5% for books, 15% for fashion.

The object-oriented approach

The classic Visitor relies on double dispatch. Each Product accepts a visitor and calls back the overloaded visit(...) matching its own type

public interface Product
{
  ...
  <R> R accept(ProductVisitor<R> visitor);
}

public record BookProduct (String name, String description, BigDecimal price) implements Product
{
  ...
  public <R> R accept(ProductVisitor<R> visitor)
  {
    return visitor.visit(this);
  }
}

The operation lives in a generic visitor, one visit(...) overload per concrete type:

public interface ProductVisitor<R>
{
  R visit(ElectronicProduct product);
  R visit(BookProduct product);
  R visit(FashionProduct product);
}

Computing the VAT of any product is then a matter of applying a concrete visitor:

BigDecimal vat = book.accept(new VatVisitor());

Adding a new operation only requires a new ProductVisitor class while the Product implementation ones never change. However, we need to notice that, as the reverse of the trade-off the factory made, adding a new operation is easy but adding a new product type is expansive since it requires to edit its central switch. The visitor makes adding a new operation free but shifts that same cost onto types, because a new product type now forces every visitor to be updated. This is the classic expression problem: you can make types cheap to add or operations cheap to add, but not both.

The following figure below shows the object-oriented implementation class diagram:

The functional approach

Look now at the class diagram of the Vistor functional style implemntation:

In modern Java the functional counterpart of the Visitor is exhaustive pattern matching over a sealed type. We first seal the hierarchy:

public sealed interface Product permits ElectronicProduct, BookProduct, FashionProduct
{
  ...
}

An operation is then just a Function<Product, R> built on a switch that deconstructs each record. Because Product is sealed, the compiler proves the switch is exhaustive - no default branch, no double dispatch, no accept:

public static final Function<Product, BigDecimal> VAT = product -> switch (product)
{
  case BookProduct(String name, String description, BigDecimal price) -> amount(price, "0.055");
  case ElectronicProduct(String name, String description, BigDecimal price) -> amount(price, "0.20");
  case FashionProduct(String name, String description, BigDecimal price) -> amount(price, "0.20");
};

Being ordinary functions, these operations can be composed:

ProductOperations.DISCOUNT.andThen(amount -> "discount=" + amount).apply(fashion);

Between the classic Visitor and pure pattern matching sits an intermediate step: the visitor as a bundle of functions, one lambda per type, instead of an interface with one method per type:

public record ProductVisitor<R>(
  Function<ElectronicProduct, R> onElectronic,
  Function<BookProduct, R> onBook,
  Function<FashionProduct, R> onFashion)
{
  public R visit(Product product)
  {
    return switch (product)
    {
      case ElectronicProduct e -> onElectronic.apply(e);
      case BookProduct b -> onBook.apply(b);
      case FashionProduct f -> onFashion.apply(f);
    };
  }
}

Which makes an operation a value you can assemble on the fly:

ProductVisitor<BigDecimal> vat = new ProductVisitor<>(
  e -> ..., b -> ..., f -> ...);
BigDecimal amount = vat.visit(book);

Of course, you may find these examples in the same GitHub repository as the previous factory pattern. It has been reorganized as a multi-module Maven project.

The product domain lives now in its own common module containing a sealed Product interface, the three product records and the ProductType enumerated which already carries the FP factory function seen above. Everything that can reuse that domain does:

oop-fp-design-patterns        (parent POM)
├── common                    sealed Product, the records, ProductType(+factory)
├── factory   (→ common)      ProductFactory (OOP); the FP factory *is* common.ProductType
└── visitor   (→ common)      FP: operations over the common records (switch + lambda bundle)
                              OOP: its own element hierarchy (see below)

The FP factory and the FP visitor both operate directly on the common records, so nothing is duplicated there. The one exception is the object-oriented Visitor which needs an accept method on every product type, for the double dispatch. Since common.Product is sealed it cannot be extended from another module. The OOP visitor therefore owns its product hierarchy and reuses only the ProductType enumerated. That asymmetry is not accidental. The classic Visitor requires every product type to expose an accept method, which couples them to the visitor abstraction. Accordingly, each product type must be defined in sync with it and so cannot be the sealed common records. The functional approach has no such coupling. It pattern-matches over the sealed type from the outside, so the products know nothing about the operations applied to them and can stay the shared common records.

This is an aphorism which origin is credited to Richard Feynman. In his book, Surely You’re Joking, Mr. Feynman !, published in 1985, he tells the story of one of his conferences on the nature on the universe, where he has been challenged by someone in the audience, saying that the universe rests on a turtle. Feynman asked then what the turtle is resting on and the answer was: “another bigger turtle”. And when he smugly asked what the bigger turtle is resting on, the attendee said: “It’s turtles all the way down, you can’t trick me !”

This metaphor is often used in the context of the Functional Programming to describe an infinite series of entities governed by a recursive principle. And it’s also the answer of the Functional Programming to developers coming from an Object-Oriented mindset: “just do functional all the way down”. But, in order to adopt a more systematic approach of combining object-oriented principles in a functional style, a more practical answer is required and this is what I’m trying to do here.

We, as developers, fortunatelly don’t have to reinvent the wheel. All the problems are solved nowadays, especially since the LLM agents became the most common digital infrastructure. But as surprizing as it might seem to our younger colleagues, who can’t live 48 hours without AI, even before LLMs, a general approach fitting solutions to problems existed, in the form of design patterns.

As a matter of fact, the Object-Oriented Programming proposes repeatable solutions tested, proven and formalized, called design patterns, that you most likely already used, even if you aren’t mandatory aware that you did.

The Gang of Four classified these patterns in three groups:

• Behavioral patterns which deal with responsibilities and communication between objects.
• Creational patterns that abstract the objects creation / instantiation process.
• Structural patterns that compose objects such that to form larger or enhanced ones.

Let’s take one of the most commonly used patterns in each category and see how to combine their object-oriented inherent nature to a more functional approach.

The Factory

This design pattern belongs to the creational category and its purpose is to instantiate objects without exposing implementation details.

The object-oriented approach

The figure below shows the class diagram of a factory design pattern:

Our scenario here is a simple one: a Product interface implemented by three classes: BookProduct, ElectronicProduct and FashionProduct. They can be created through the ProductFactory class, as follows:

public class ProductFactory
{
  public static Product newProduct (String name, String description, BigDecimal price, ProductType productType)
  {
    Objects.requireNonNull(name, "Name is null");
    ...
    return switch (productType)
    {
      case BOOK -> new BookProduct(name, description, price);
      case ELECTRONIC -> new ElectronicProduct(name, description, price);
      case FASHION -> new FashionProduct(name, description, price);
      default -> throw new IllegalArgumentException ("Unknown type: %s".formatted(productType));
    };
  }
}

Using this factory, it’s very easy to create a BookProduct, for example, while avoiding to expose implementation details:

    ...
    Product product = ProductFactory.newProduct("Book1", "A book",
      new BigDecimal("20.50"), ProductType.BOOK);
    ...

As you probably noticed, the ProductType enumerated defines the three categories. If a new product is to be introduced, the factory has to be modified such that to reflect this business changement. And this interdependence of the factory and the enumerated makes the whole approach fragile.

In order to reduce this fragility, we need to introduce a compile-time validation with a more functional approach.

The functional approach

Our example is an over-simplified case of a product management system. The presented factory instantiate different simple records having the same arguments. These identical constructors give us the possibility to move the factory directly into the ProductType enumerated, such that any new product automatically requires a correspondent factory.

Java enum types are based on constant names, but we can attach to each one its correspondent value. Or, even better, a factory function for creating discrete products. Look at that:

public enum ProductType
{
  ELECTRONIC(ElectronicProduct::new),
  FASHION(FashionProduct::new),
  BOOK(BookProduct::new);

  public final TriFunction<String, String, BigDecimal, Product> factory;

  ProductType (TriFunction<String, String, BigDecimal, Product> factory)
  {
    this.factory = factory;
  }

  public Product newInstance (String name, String description, BigDecimal price)
  {
    Objects.requireNonNull(name, "Name is null");
    ...
    return this.factory.apply (name, description, price);
  }
}

Now, creating a new Product instance is easier:

Product product = ProductType.BOOK.newInstance("Book1",
  "A book", new BigDecimal("20.45"));

The public property factory seems redundant now that a dedicated method for the instance creation is available. But it provides a very convenient functional way to interact further with the factory. For example:

ProductType.BOOK.factory.andThen(showThePrice).apply("Book1",
  "A book", new BigDecimal("20.45"));

as shown in the TestProductFactory class, in the fp_design_paterns.factory package. Of course, given that our products need three arguments constructors and since Java doesn’t provide an equivalent of the BiFunction class, but with three input arguments, you will need to craft a TriFunction class, as shown below:

@FunctionalInterface
public interface TriFunction<A, B, C, R>
{
  R apply(A a, B b, C c);
  default <K> TriFunction<A, B, C, K> andThen(Function<? super R, ? extends K> f)
  {
    Objects.requireNonNull(f);
    return (A a, B b, C c) -> f.apply(apply(a, b, c));
  }
}

You can do that or, if like me, you prefer to use a reliable library, then Vavr already defines a Function3 interface that has the behavior you want. Just include the following Maven dependency:

<dependency>
  <groupId>io.vavr</groupId>
  <artifactId>vavr</artifactId>
  <version>1.0.1</version>
</dependency>

This library is the good choice if you need to define functions with up to 8 arguments. Then, you just need to replace, in ProductType, the following definition:

public final TriFunction<String, String, BigDecimal, Product> factory;

ProductType (TriFunction<String, String, BigDecimal, Product> factory)
{
  this.factory = factory;
}

bvy this one:

public final Function3<String, String, BigDecimal, Product> factory;

ProductType (Function3<String, String, BigDecimal, Product> factory)
{
  this.factory = factory;
}

The full code of these examples, including the associated unit tests, can be found here: https://github.com/nicolasduminil/oop-fp-design-patterns.

Command Query Responsibility Segregation (CQRS) separates the write model from the read model. A command expresses intent to change state, for example PlaceOrder, AddItem, ShipOrder. A query reads state without modifying it. The two sides use separate models, separate logic, and, in a full implementation, separate storage.

CQRS and Event Sourcing are complementary: the event stream is the write side’s source of truth, while one or more projections (read models) are derived from those events for fast querying.

This article aims at showing how to apply, in practice, these concepts, using for illustration purposes a modified version of one of Markus Eisele’s article, from the 27th of December 2025 on Substack. In his article, Markus shows a Quarkus based project implementing a simplified order management system. Here, I’m presenting the Spring Boot implementation of this same system, to change. You can find it here: https://github.com/nicolasduminil/cqrs-showcase.

Introduction

In a classical order management system, by analyzing the associated data model, we can gather a lot of information about orders and their flow in the organization. But while we would be able to account about any order’s current status, the data and the data model analysis wouldn’t allow us to reconstitute the story of how each order got to its current state.

Event sourcing

The event sourcing pattern introduces the dimension of time into the data model. Instead of a schema reflecting the orders’ current state, an event sourcing based system persists events documenting every change in the orders’ lifecycle. Then, by querying these events, we can reconstitute the whole story od a given order, or any other general aggregate, from its initial creation until its current status.

CQRS

The only problem here is that querying a single aggregate instance event story at a time doesn’t allow us to retrieve and consolidate data relative to other aggregates in the data model. Hence, the CQRS pattern closely related to the event sourcing one, designed such that to provide the possibility of materializing projected models into logical data structures, reliable enough to support flexible querying options.

Commands

CQRS dedicates commands to execute operations that modify the system state. The command based execution model is then the only one able to implement business logic, to validate rules and to enforce invariants.

Projections

The system can define as many models as required to provide data to users or to other systems. Thus, a read model is a fast, denormalized and shaped pre-cached projection containing read-only data that the application needs to answer queries. The system project changes from the command execution model to all its read models. The projection notion is similar to the one of materialized view in relational databases, meaning that whenever the source tables are updated, the changes have to be reflected in all the read model views.

Model segregation

In a CQRS architecture, the responsibilities of the system’s models are segregated according to their type. A command can only operate on its only execution model, while a query cannot directly modify any of the system’s persisted state.

How this project illustrates event sourcing and CQRS

This is a true CQRS implementation (not just a naming convention) because:

1. The write path never reads from the read model. CommandHandler reconstructs state exclusively by replaying events from the event store via EventProjection.replayEvents(). It never touches OrderReadModel or OrderRepository.
2. The read path never touches the event store. OrderResource.getOrderReadModel() reads directly from the denormalized ORDERS table. It is a pure query with no business logic.
3. There are two physically distinct storage tables: EVENT_STORE (write side) and ORDERS (read side).
4. The read model is a projection, not a view. OrderProjection listens to domain events and rebuilds the read model incrementally. The ORDERS table could be dropped and rebuilt from scratch by replaying the event store.
5. Commands return CommandResult, a sealed type that communicates success or failure without leaking state. The caller must query the read model separately if it needs current state.

Let’s look now at the project’s key implemntation details:

Modeling State with Records

OrderState is a Java record immutable by construction. No setters, no mutation. Every command produces a new state object:

  public record OrderState(
      UUID orderId,
      String customerEmail,
      List<OrderLine> items,
      OrderStatus status,
      BigDecimal total
  ) {                                                                                                                                                                                                                                       
      public static OrderState initial(UUID orderId, String email) { ... }
      public static OrderState empty() { ... }                                                                                                                                                                                              
  }               

OrderLine is likewise a record with a derived field:

  public record OrderLine(String productName, int quantity, BigDecimal price) {
      public BigDecimal lineTotal() {
          return price.multiply(BigDecimal.valueOf(quantity));
      }                                                                                                                                                                                                                                     
  }

lineTotal() is a derived record component: it is computed, not stored, demonstrating that records can carry behavior alongside data.

Events as a Sealed Type Hierarchy

OrderEvent is a sealed interface, restricting all permitted implementations to a known, closed set:

  public sealed interface OrderEvent
      permits OrderEvent.OrderPlaced,
              OrderEvent.ItemAdded,                                                                                                                                                                                                         
              OrderEvent.ItemRemoved,
              OrderEvent.OrderCancelled,                                                                                                                                                                                                    
              OrderEvent.OrderShipped {

      UUID orderId();
      OrderState applyTo(OrderState current);
                                                                                                                                                                                                                                            
      record OrderPlaced(UUID orderId, String customerEmail) implements OrderEvent {
          public OrderState applyTo(OrderState s) {                                                                                                                                                                                         
              return OrderState.initial(orderId, customerEmail);                                                                                                                                                                            
          }
      }                                                                                                                                                                                                                                     
      // ... other event types
  }                                                                                                                                                                                                                                         

Using a sealed interface means the compiler enforces exhaustiveness in switch expressions. Adding a new event type without handling it is a compile error, not a runtime surprise.

Each event carries only the data it needs and knows how to apply itself to the current state via applyTo(OrderState). This is the self-describing event pattern.

The Fold (Event Replay)

A fold, also known as left reduction, is the process of reconstructing state from a list of events over the event stream:

  // EventProjection.java
  public OrderState replayEvents(List<OrderEvent> events) {                                                                                                                                                                                 
      return events.stream()
          .reduce(OrderState.empty(), this::apply, (a, b) -> b);                                                                                                                                                                            
  }                                                                                                                                                                                                                                         
   
  private OrderState apply(OrderState state, OrderEvent event) {                                                                                                                                                                            
      return event.applyTo(state);                                                                                                                                                                                                          
  }

OrderState.empty() is the identity element or the seed. Each event is a step function that transforms one immutable state into the next. This is pure functional programming: no side effects, no shared mutable state, entirely deterministic and testable in isolation.

Commands as Sealed Records

Commands are sealed records grouped in a container interface:

  public sealed interface Command
      permits Command.PlaceOrderCommand,
              Command.AddItemCommand,                                                                                                                                                                                                       
              Command.ShipOrderCommand,
              Command.CancelOrderCommand {                                                                                                                                                                                                  
                  
      record PlaceOrderCommand(String customerEmail) implements Command {}
      record AddItemCommand(UUID orderId, String productName,
                            int quantity, BigDecimal price) implements Command {}                                                                                                                                                           
      // ...
  }                                                                                                                                                                                                                                         

Sealed records give commands value semantics, (equality by content, toString for free. and type safety (exhaustive pattern matching in the handler).

Command Results as Sealed Types

CommandResult is a sealed interface expressing all possible outcomes without exceptions:

  public sealed interface CommandResult
      permits CommandResult.Success,
              CommandResult.InvalidState,
              CommandResult.NotFound,
              CommandResult.ValidationError {

      record Success(UUID aggregateId) implements CommandResult {}
      record InvalidState(String message) implements CommandResult {}                                                                                                                                                                       
      record NotFound(String message) implements CommandResult {}
      record ValidationError(String message) implements CommandResult {}                                                                                                                                                                    
  }               

The caller can switch on the result exhaustively. There are no checked exceptions, no nullable returns, and the type system documents all possible failure modes.

The Event Store

EventStore is the write-side infrastructure. It does two things atomically:

1. Persists the event to EVENT_STORE (JPA via EventRepository).
2. Publishes the event to the Spring application event bus.

  public void append(UUID aggregateId, String aggregateType, OrderEvent event) {
      int version = nextVersion(aggregateId);                                                                                                                                                                                               
      String json = objectMapper.writeValueAsString(event);
      StoredEvent entity = new StoredEvent(aggregateId, aggregateType,                                                                                                                                                                      
                                           version, eventType, json);
      eventRepository.save(entity);                                                                                                                                                                                                         
      applicationEventPublisher.publishEvent(event);
  }                                                                                                                                                                                                                                         

Versioning provides a lightweight optimistic concurrency guard, by preventing concurrent writes from corrupting the stream, based on the unique value aggregateId + version.

The Read-Side Projection

OrderProjection is a Spring component that listens for domain events and updates the read model:

  @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
  public void on(OrderEvent event) {
      OrderReadModel model = orderRepository.findByOrderId(event.orderId())
          .orElse(new OrderReadModel());                                                                                                                                                                                                    
      // update fields from event ...
      orderRepository.save(model);                                                                                                                                                                                                          
  }               

@TransactionalEventListener(phase = AFTER_COMMIT) ensures the read model is only updated after the event store transaction commits successfully, preventing this way phantom updates if the write-side transaction rolls back.

Running the Application

Prerequisites: Java 21, Maven, Docker (for PostgreSQL via TestContainers in tests).

  # Build and run all tests (requires Docker)
  ./mvnw clean package
                                                                                                                                                                                                                                            
  # Run the application (requires a running PostgreSQL instance)
  ./mvnw spring-boot:run                                                                                                                                                                                                                    
                  
  # Skip tests
  ./mvnw clean package -DskipTests

API Reference

Place an order:

  POST /orders                                                                                                                                                                                                                              
  { "customerEmail": "alice@example.com" }

Add an item:

  POST /orders/{id}/items                                                                                                                                                                                                                   
  { "productName": "Widget", "quantity": 3, "price": 9.99 }

Ship an order:

  POST /orders/{id}/ship
  { "trackingNumber": "TRACK-001" }

Do enterprise grade Java Applications really need heavy JavaScript libraries ? This is the question to which we’ll be trying to answer here.

Modern Java enterprise applications tend to follow a familiar pattern: a Java backend exposing REST APIs and a JavaScript/TypeScript frontend built with some library like Angular, React, or Vue. This architecture has become so standard that we rarely question it.

But is this always the most natural choice ? Certainly not, given that the Java ecosystem already provides a mature, productive, and integrated web UI framework: Jakarta Faces.

In former times, when dinosaurs still populated the Earth, the enterprise-grade Java applications development only required the knowledge of a single technology: Java with possibly its enterprise extensions, appointed successively as J2EE, Java EE, and finally Jakarta EE. Unless it was Spring, the applications and services were deployed on Jakarta EE-compliant application servers, like Glassfish, Payara, Wildfly, JBoss, WebLogic, WebSphere, etc. These application servers were providing out-of-the-box all the required implementations of the above-mentioned specifications. Among these specifications, Jakarta Faces (formerly called JSF: Java Server Faces) was meant to offer a framework that facilitates and standardizes the development of web applications in Java.

The Jakarta Faces history goes back to 2001 to its initial JSR (Java Specifications Request) 127. At that time, another web framework, known under the name of Struts and available under an Apache open-source license, was widely popular. As it sometimes happens in the web frameworks space, the advent of Jakarta Faces was perceived by the Apache community as being in conflict with Struts and, this alleged conflict was resolved through a long and heavy negotiation process of several years, between Sun Microsystems and the Apache community. Finally, Sun agreed to lift the restrictions preventing JSRs from being independently implemented under an open-source license, and the first implementation (RI Reference Implementation), was provided in 2003.

Jakarta Faces was generally well received despite a market crowded with competitors. Its RI was followed by other implementations over the years, starting with Apache MyFaces in early 2004 and continuing with RedHat RichFaces in 2005, PrimeTek PrimeFaces in 2008, ICEsoft ICEfaces and Oracle ADF Faces in 2009, OmniFaces in 2012, etc. The specifications have evolved as well, from the 1.0 released in 2001 to the 4.1 released in 2024. Hence, more than 20 years of history to advent to the last Jakarta Faces release 4.1, a part of the Jakarta EE 11 specifications, named Mojara.

The software history is sometimes convoluted. In 2010, Oracle acquired Sun Microsystems and became the owner of the Java trademark. All along the time period that they were under the Oracle stewardship, the Java EE specifications were in a kind of status quo before becoming Eclipse Jakarta EE. The company didn’t really manage to set up a dialogue with users, communities, work groups, and all those involved in the recognition and promotion of the Java enterprise-grade services. Their evolution requests and expectations were ignored by the editor, who didn’t know how to deal with their new responsibility as the Java/Jakarta EE owner. In such a way that, little by little, this has led to a guarded reaction from software architects and developers, who began to prefer and adopt alternative technological solutions.

While trying to find alternative solutions to Jakarta EE and to remedy issues like the apparent heaviness and the expensive prices of application servers, many software professionals have adopted Spring Boot as a development platform. Other solutions, closer to real Jakarta EE alternatives, have emerged as well and, among them, Netty, Quarkus, Micronaut, Helidon are the best-known and most popular. All these solutions were based on a couple of software design principles, like single concern, discrete boundaries, transportability across runtimes, auto-discovery, etc., which were known since the dawn of time. But because the software industry continuously needs new names, the new name that has been found for these alternative solutions was “microservices.”

More and more microservice architecture-based applications have appeared during the next few years, to such an extent that the word “microservice” became one of the most common buzzwords in the software industry. In order to optimize and standardize the microservices technology, the Eclipse Foundation decided to apply to microservices the same process that was used to design the Jakarta EE specifications. The Eclipse MicroProfile was born.

But all these convolutions have definitely impacted the web framework technologies. While the high majority of the Java enterprise-grade applications were using Jakarta Faces for their web tier, switching from a software architecture based on Jakarta EE-compliant application servers to microservices resulted in a phasing-out of these architectures in favor of some more lightweight ones, often based on Eclipse Microprofile specifications. And since Jakarta Faces components needed an application server to be deployed on, or at least a servlet engine, other lighter alternatives, based on JavaScript or TypeScript libraries, like Angular, Vue, ExtJS, jQuery, and others, have been adopted to make up for its absence and to become the front-end preferred stack.

Such applications generally require two development teams:

• A front-end team specialized in JavaScript / TypeScript, Angular, CSS, and HTML development, using Node.js as a deployment platform, NPM as a build tool, Bower as a dependency management, Gulp as a streaming system, Karma and Jasmine for testing, WebPack as a code bundler, and probably many others.
• A back-end team specialized in Java development with Jakarta EE / Eclipse Microprofile specifications, including but not limited to MP Config, MP REST Client, MP OpenAPI, MP Health, etc. or Jakarta REST, Jakarta Persistence, Jakarta Messaging, Jakarta Security, Jakarta JSON Binding, etc.

Building enterprise-grade project teams became too difficult as it required at least two categories of profiles and, given the technology’s complexity, the mentioned profiles should have better been seniors. Hence, the software industry has been facing a shortage of qualified developers which determined several organizations to favor full-stack JavaScript / TypeScript enterprise applications. This has lead to kind of unnatural and convoluted architectures, where the back-ends were written in a browser dedicated programming language, with all the issues that this choice implied, like performance, security, maintainability, etc.

This situation sharply contrasts with what happened in the former times when the front-end could have been implemented using Jakarta Faces and, hence, a single Java development team was able to take charge of such an enterprise-grade project. Jakarta Faces is a great web framework whose implementations offer hundreds of ready-to-use widgets and other visual controls. Compared with Angular, where the visual components are a part of external libraries, like Material, NG-Bootstrap, Clarity, Kendo, Nebular, and many others, Jakarta Faces implementations not only provide ways more widgets and features but also are part of the official JSR 372 specifications and, in this respect, they are standard, as opposed to the mentioned libraries, which evolve with their authors prevailing moods, without any guarantee of consistency and stability.

The figure below shows a two typical architectures:

• an SPA (Single Page Application) architecture based on a JavaScript front-end, and a Java backend exposing REST APIs. As you can see, it requires two codebases and, probably, two separate development teams, one for the front-end and one for the back-end, and it also requires a lot of different technologies and tools.
• a classical Java enterprise-grade application built with Jakarta Faces and Quarkus. The frontend is implemented using Jakarta Faces, which provides a rich set of components and features for building complex web applications. The backend is implemented using Quarkus, which provides excellent support for Jakarta Faces, via its PrimeFaces extension, and allows for fast development and efficient performance.

One of the criteria that has formed many organizations’ decision basis to switch from Jakarta Faces web applications to JavaScript/TypeScript frameworks was client-side rendering. It was considered that the server-side rendering, which is the way the Jakarta Faces works, is less performant than the client-side rendering, provided by the browser-based applications. This argument has to be taken with a grain of salt:

• Client-side rendering means rendering pages directly in the browser with JavaScript. All logic, data fetching, templating, and routing are handled by the client. The primary downside of this rendering type is that the amount of JavaScript required tends to grow as an application grows, which can have negative effects on a page’s capacity to consistently respond to user inputs. This becomes especially difficult with the addition of new JavaScript libraries, polyfills, and third-party code, which compete for processing power and must often be processed before a page’s content can be rendered.
• Server-side rendering generates the full HTML for a page on the server in response to navigation. This avoids additional round-trips for data fetching and templating on the client since it’s handled before the browser gets a response.
• Server-side rendering generally reduces the time required for the page content to become visible. It makes it possible to avoid sending lots of JavaScript to the client. This helps to reduce a page’s TBT (Total Blocking Time), which can also lead to a lower average response time as the main thread is not blocked as often during page load. When the main thread is blocked less often, user interactions will have more opportunities to run sooner.
• With server-side rendering, users are less likely to be left waiting for CPU-bound JavaScript to run before they can access a page.
• Server‑side rendering often has a better Time to First Byte (TTFB) and avoids large JavaScript bundles, which can improve perceived performance for many business use‑cases.

Accordingly, the argument consisting of saying that the server-side rendering is bad while the client-side one would be better is just a myth.

Consequently, it appears clearly from this analysis that developing Java web applications using server-side rendering frameworks, like Jakarta Faces, not only leads to more performant applications, but it’s also much simpler and less expensive. This approach doesn’t require so many different technology stacks as its JavaScript/TypeScript-based alternatives. The development teams don’t need several categories of profiles, and the same developer can directly contribute to both the front end and the back end without having to operate any paradigm switch. This last argument is all the more important as Java developers, concerned by things like multi-threading, transaction management, security, etc., aren’t comfortable when it comes to command programming languages that have been designed to run in a browser.

The following table summarizes the main differences between the two approaches:

So the good news here is that, if like me, you’re a nostalgic of Jakarta Faces, from now on, you can start implementing your front-ends with it, without the need for any Jakarta EE-compliant application server. That’s because Quarkus, our famous Supersonic Subatomic Java platform, provides a Jakarta Faces extension, allowing you to write beautiful front-ends like in the old good times.

Quarkus offers fast development mode, cloud‑native performance, and optional native compilation, making Jakarta Faces viable even in microservices‑centric environments. At Melloware Inc., they provide a PrimeFaces extension for Quarkus, as described here. You’ll find in the mentioned GIT repository a showcase application that demonstrates, with consistent code examples, how to use every single PrimeFaces widget. Please follow the guide in the README.md file to build and run the showcase on both an application server, like Wildfly, and in Quarkus.

I’ve tested it recently. Those of you having used in the past Jakarta Faces must certainly remember the book “Primefaces Cookbook”, by Mert Caliskan and Oleg Varaskin, published in 2013, with a 2nd edition in 2015. This book is one of the most comprehensive and detailed resources about Jakarta Faces and PrimeFaces. So, I refactored all the code examples of this book to make them work with the latest versions of Quarkus and PrimeFaces. If you’re interested, you’ll find the project here.

If you want to give it a try, proceed as follows:

$ git clone https://github.com/nicolasduminil/primefaces-showcase.git
$ cd primefaces-showcase
$ mvn package
$ java -jar target/quarkus-app/quarkus-run.jar

Then, go to http://localhost:8080 and the following screen will be displayed in your browser:

Here, you are given the chance to exercice most of Jakarta Faces and its implementation Mojara and PrimeFaces, and to see how they work in a modern Java web application built with Quarkus. Just unfold the different nodes in the left-hand tree and click on the different samples to see them in action. You may change the current theme as well by clicking on the “Change Theme” button at the top right of the page.

You’ll tell me what it feels like there!

In the continuity of this previous post, the current one will try to go a bit further and replace ECS by EKS (Elastic Kubernetes Service) as the environment for running containerized workloads. Additionally, an automated CI/CD pipeline, using AWS CodePipeline and AWS CodeBuild, is provided.

Architecture Overview

The solution that you’re about to look at implements a complete production-ready architecture consisting of:

• Presentation Layer: A Quarkus REST API with OpenAPI/Swagger implementing the customer management solution. This implementation is exactly the same used in the previous project which leverages ECS.
• Application Layer: Business logic with Quarkus Panache for data access
• Data Layer: PostgreSQL (RDS) for persistence, Redis (ElastiCache) for caching
• Container Orchestration: AWS EKS with Fargate for serverless container execution
• Infrastructure as Code: AWS CDK implemented in Quarkus
• CI/CD: Automated pipeline with AWS CodePipeline, CodeBuild, and GitHub integration

Before starting, a couple of explanations are probably required. As you probably know, EKS can be used with two compute engines: EC2 or Fargate. In this example we’ve chosen to use Fargate, as it was also the case of our previous, ECS-based project.

Fargate is a serverless compute engine for containers that provisions and manages the underlying infrastructure and provides automatic scaling. It is designed to make it easy to run containers without having to manage servers or clusters. It’s a great fit for workloads that don’t have long-running connections or require frequent scaling. This project uses Fargate because it needs a continuously running containerized application. Fargate provides the serverless operational model (no server management) while maintaining the traditional container execution model your Quarkus API requires.

The figure below shows the project’s architecture diagram:

Please notice that, as mentioned above, several layers like: presentation, application and data are the same ones used in the previous ECS-based example. Hence, we created a new module, called customer-service-eks, in the current Maven multi-module project. This module is similar to the customer-service-ecs one and they both share the same presentation, application and data layers, that have been moved in a shared Maven module, called customer-service-cdk-common.

Prerequisites

The following prerequisites are required to run this project:

• Java 21+
• Maven 3.9+
• Docker
• AWS CLI installed and configured with appropriate credentials
• kubectl installed
• AWS CDK CLI installed
• GitHub account with OAuth token stored in AWS Secrets Manager

Project Structure

The project is structured as follows:

customer-service-eks/
├── src/main/java/
│ └── fr/simplex_software/workshop/customer_service_eks/
    │ └── config/
      │ └── CiCdConfig.java # CI/CD Pipeline configuration
    │ ├── CiCdPipelineStack.java # CDK Quarkus CI/CD pipeline infrastructure
    │ ├── CustomerManagementEksApp.java # Quarkus CDK application
    │ ├── CustomerManagementEksMain.java # Quarkus main application
    │ ├── CustomerManagementEksProducer.java # Quarkus CDI producer
    │ ├── EksClusterStack.java # Quarkus CDK EKS cluster infrastructure
    │ ├── MonitoringStack.java # Quarkus CDK monitoring stack infrastructure
    │ ├── VpcStack.java # Quarkus CDK VPC stack infrastructure
├── src/main/resources/
│ ├── buildspecs/
│ │ ├── build-spec.yaml # CodeBuild build specification
│ │ └── deploy-spec.yaml # CodeBuild deploy specification
│ ├── k8s/
│ │ └── customer-service.yaml # Kubernetes manifests
│ ├── scripts/  #several shell scripts
      ...
│ └── application.properties # Configuration
└── src/test/java/
    └── fr/simplex_software/workshop/customer_service_eks/tests/
        └── CustomerServiceE2EIT.java # End-to-end integration tests

Configuration

The project’s configuration is stored in two files:

• the env.properties file
• the src/main/resources/application.propertiesfile.

The env.properties file contains environment variables that are used by the Maven build process. Its structure is reproduced below:

CONTAINER_IMAGE_GROUP=nicolasduminil
CONTAINER_IMAGE_NAME=customers-api
CDK_DEFAULT_ACCOUNT=...
CDK_DEFAULT_REGION=eu-west-3
CDK_DEFAULT_USER=nicolas

The properties CONTAINER_IMAGE_GROUP and CONTAINER_IMAGE_NAME are used to build the container image and push it to the ECR repository. They are used by the JIB Quarkus extension to build the container image. The other properties are used by the CDK application to deploy the infrastructure and their meanings don’t require any explicit explanation.

The project uses AWS Secrets Manager to store sensitive data like GitHub OAuth token which is used by the CI/CD pipeline. In order to create the secret, you can use the script setup-github-token.sh reproduced below:

#!/bin/bash
set -e
echo "=== GitHub Token Setup for CI/CD Pipeline ==="

# Read token from stdin or argument
if [ $# -eq 0 ]; then
  if [ -t 0 ]; then
    # No arguments and no piped input
    echo "Usage:"
    echo "  $0 <github-personal-access-token>"
    ...
    exit 1
  else
    # Read from stdin
    GITHUB_TOKEN=$(cat | tr -d '\n\r')
  fi
else
  # Read from argument
  GITHUB_TOKEN=$1
fi

SECRET_NAME="github-oauth-token"

echo "Creating secret in AWS Secrets Manager..."

# Check if secret already exists
if aws secretsmanager describe-secret --secret-id "$SECRET_NAME" >/dev/null 2>&1; then
  echo "Secret already exists. Updating..."
  aws secretsmanager update-secret \
    --secret-id "$SECRET_NAME" \
    --secret-string "$GITHUB_TOKEN"
else
  echo "Creating new secret..."
  aws secretsmanager create-secret \
    --name "$SECRET_NAME" \
    --description "GitHub OAuth token for CI/CD pipeline" \
    --secret-string "$GITHUB_TOKEN"
fi

echo "✅ GitHub token stored successfully!"
echo "You can now run: cdk deploy --all"

This script takes a parameter which could be either an argument or a piped input. The GIT OAuth token should already be acquired from GitHub. In order to do that, proceed as follows:

1. Go to: https://github.com/settings/tokens”.
2. Click Generate new token (classic)
3. Select repo scope
4. Copy the generated token.

The othe configuration file, src/main/resources/application.properties, contains the following key properties:

# CI/CD Configuration
cdk.cicd.repository.name=${CONTAINER_IMAGE_GROUP}/${CONTAINER_IMAGE_NAME}
cdk.cicd.github.owner=${CONTAINER_IMAGE_GROUP}
cdk.cicd.github.repo=aws-cdk-quarkus
cdk.cicd.github.token-secret=github-oauth-token

# EKS Configuration
cdk.infrastructure.eks.namespace=customer-service
cdk.infrastructure.eks.cluster-name=customer-service-cluster
cdk.infrastructure.eks.service-account-name=customer-service-account
...

In addition to these configuration files and scripts, the class CiCdConfig uses the MP Config API to define properties relative to different services and stages of the CI/CD pipeline.

@ConfigMapping(prefix = "cdk.cicd")
public interface CiCdConfig
{
  RepositoryConfig repository();
  GitHubConfig github();
  BuildConfig build();
  PipelineConfig pipeline();
  ...
}

As we can see, CiCdConfig is an interface which contains several sub-interfaces, one for each service or stage. Each sub-interface defines a set of properties that are used to configure the corresponding service or stage, for exzmple:

...
interface RepositoryConfig
{
  @WithDefault("customer-service")
  String name();
}

interface GitHubConfig
{
  @WithDefault("your-github-user")
  String owner();
  @WithDefault("customer-service")
  String repo();
  @WithDefault("github-token")
  String tokenSecret();
}
...

The CDK Stacks

The IaC code is organized into several CDK stacks, each responsible for a specific aspect of the infrastructure.

The VpcStack

This stack creates the foundational networking infrastructure for the entire solution. It provisions a VPC (Virtual Private Cloud) with multi-AZ (Availability Zone) support for high availability. The VPC is configured with both public and private subnets across multiple availability zones, as specified by the maxAzs configuration property (default: 2). The stack also creates NAT Gateways to enable outbound internet access for resources in private subnets, with the number controlled by the natGateways property (default: 1). This VPC serves as the network foundation for all other stacks, including the EKS cluster, RDS database, and ElastiCache Redis instances. The implementation is minimal, as shown below:

vpc = Vpc.Builder.create(this, "EksVpc")
  .maxAzs(config.vpc().maxAzs())           // Default: 2 AZs
  .natGateways(config.vpc().natGateways()) // Default: 1 NAT Gateway
  .build();

The code above uses the software.amazon.awscdk.services.ec2.Vpc CDK construct that automatically creates 6 subnets across two AZs:

• 2 public subnets (one per AZ) connected to an IGW (Internet Gateway). An IGW is a horizontally scaled, redundant AWS-managed component that allows bidirectional communication between resources in the VPC and the internet. It enables resources with public IP addresses to receive inbound traffic from the internet and send outbound traffic to the internet. In our case, it is used as an NLB (Network Load Balancer) which receives external traffic.

• 2 private subnets with “egress” (one per AZ) connected to a NAT Gateway. A Nat Gateway is a managed service that enables resources in private subnets to initiate outbound connections to the internet (for software updates, API calls, etc.) while preventing unsolicited inbound connections from the internet. In this context, “egress” means outbound-only traffic flow. These 2 private subnets are used for EKS Fargate pods, RDS database and ElastiCache Redis which require all outbound internet access but should not be directly accessible from the internet.

• 2 isolated subnets (one per AZ). These subnets have neither IGW, nor NatGateway and, hence, they don’t have internet connectivity. They are created by default by the Vpc construct but they aren’t used in this project as they are typically dedicated to highly sensitive resources that should never communicate with the internet.

The maxAzs property (default: 2) determines how many availability zones to span for high availability. The natGateways property (default: 1) controls the number of NAT Gateways - using 1 instead of 2 reduces costs but creates a single point of failure for outbound internet connectivity.

This VPC serves as the network foundation for all other stacks, including the EKS cluster, RDS database, and ElastiCache Redis instances. We need to mention that any AWS account has a default VPC and that we could have used it here, instead of creating another one. While this alternative would have been much simpler with no additional network cost, having a dedicated VPC is a more “production ready” solution, as it provides better isolation, customized CIDR blocks and more subnets.

The EksClusterStack

This is the core infrastructure stack that creates and configures the EKS cluster with a Fargate compute profile. The stack performs the following several critical operations:

1. creates an EKS cluster (version 1.34) with API authentication mode and public endpoint access. The cluster is deployed in the private subnets of the VPC for enhanced security.

2. adds to the previous created cluster a Fargate profile that targets the customer-service namespace, ensuring all pods in this namespace run on Fargate serverless compute. The profile’s pod execution role is granted CloudWatch Logs permissions for centralized logging.

3. sets up a Kubernetes ServiceAccount with IRSA (IAM Roles for Service Accounts), granting the pods secure access to AWS services without embedding credentials. The service account is granted permissions to connect to the RDS database and read secrets from AWS Secrets Manager.

4. programmatically creates Kubernetes manifests including a namespace for workload isolation, a ConfigMap containing database and Redis connection strings, a deployment and a service resource, loaded from the YAML file in the resources/k8s directory.

public void initStack() throws IOException
{
  createCluster();
  KubernetesManifest namespace = createNamespace();
  addFargateProfile();
  ServiceAccount serviceAccount = setupServiceAccountWithIAM();
  serviceAccount.getNode().addDependency(namespace);
  KubernetesManifest configMap = addConfigMap();
  configMap.getNode().addDependency(serviceAccount);
  addDeploymentAndService(configMap);
}

The stack establishes dependencies to ensure resources are created in the correct order, with the ConfigMap depending on the ServiceAccount, and the Deployment depending on the ConfigMap.

@SuppressWarnings("unchecked")
private void addDeploymentAndService(KubernetesManifest configMap) throws IOException
{
  List<Map<String, Object>> manifests = loadYamlManifests("k8s/customer-service.yaml");
  KubernetesManifest previous = configMap;
  for (int i = 0; i < manifests.size(); i++)
  {
    KubernetesManifest current =
      cluster.addManifest("CustomerService-%d".formatted(i), manifests.get(i));
    current.getNode().addDependency(previous);
    previous = current;
  }
}

The code above shows how the file customer-service.yaml, containing the ServiceAccount and the Deployment manifests, is parsed and the manifests added to the cluster, each one being dependent of the previous one, in order to prevent possible cyclic dependencies.

The CiCdPipelineStack

This stack implements a complete CI/CD pipeline using AWS native services to automate the build and deployment process. It consists of three stages:

1. Source Stage: integrates with GitHub using a webhook trigger. When code is pushed to the repository, the pipeline automatically retrieves the source code using a GitHub OAuth token stored in AWS Secrets Manager.

2. Build Stage: Uses AWS CodeBuild with a Standard 7.0 Linux image to build the Quarkus application, create a Docker image using the JIB Maven plugin and push the image to Amazon ECR (Elastic Container Registry). The build project has privileged mode enabled for Docker operations and is granted necessary IAM permissions for ECR operations.

3. Deploy Stage: Uses a separate CodeBuild project to update the kubeconfig to access the EKS cluster and apply the updated Kubernetes manifests with the new container image. The deploy project is granted EKS cluster access through IAM role assumption.

The pipeline uses build specifications defined in buildspecs/build-spec.yaml and buildspecs/deploy-spec.yaml, and stores artifacts in S3 between stages. All configuration is externalized through the CiCdConfig interface using MicroProfile Config.

  public void initStack()
  {
    IRepository ecrRepo = Repository.fromRepositoryName(this,
      "CustomerServiceRepo", cicdConfig.repository().name());

    Project buildProject = Project.Builder.create(this, "CustomerServiceBuild")
      .source(Source.gitHub(GitHubSourceProps.builder()
      ...
      .build();
    ecrRepo.grantPullPush(buildProject);
    buildProject.addToRolePolicy(PolicyStatement.Builder.create()
      .actions(List.of("ecr:GetAuthorizationToken"))
      .resources(List.of("*"))
      .build());
    buildProject.addToRolePolicy(PolicyStatement.Builder.create()
      .actions(List.of("secretsmanager:GetSecretValue"))
      .resources(List.of("arn:aws:secretsmanager:eu-west-3:" + this.getAccount() + ":secret:redhat-registry-credentials-*"))
      .build());

    Project deployProject = Project.Builder.create(this, "CustomerServiceDeploy")
      ....
      build();
    deployProject.getRole().addManagedPolicy(
      ManagedPolicy.fromAwsManagedPolicyName("AmazonEKSClusterPolicy"));
    eksStack.getCluster().getRole().grantAssumeRole(deployProject.getRole());
    deployProject.addToRolePolicy(PolicyStatement.Builder.create()
      .actions(List.of("eks:DescribeCluster"))
      .resources(List.of(eksStack.getCluster().getClusterArn()))
      .build());

    GitHubSourceAction sourceAction = GitHubSourceAction.Builder.create()
      .actionName(cicdConfig.pipeline().actions().source())
      ...
     .build();

    CodeBuildAction buildAction = CodeBuildAction.Builder.create()
      .actionName(cicdConfig.pipeline().actions().build())
      ...
      .build();

    CodeBuildAction deployAction = CodeBuildAction.Builder.create()
      .actionName(cicdConfig.pipeline().actions().deploy())
      ...
      .build();

    Pipeline pipeline = Pipeline.Builder.create(this, cicdConfig.pipeline().name())
      .build();
    pipeline.addStage(StageOptions.builder()
      .stageName(cicdConfig.pipeline().stages().source())
      .actions(List.of(sourceAction))
      .build());
    pipeline.addStage(StageOptions.builder()
      .stageName(cicdConfig.pipeline().stages().build())
      .actions(List.of(buildAction))
      .build());
    pipeline.addStage(StageOptions.builder()
      .stageName(cicdConfig.pipeline().stages().deploy())
      .actions(List.of(deployAction))
      .build());
  }

The code above create two CodeBuild projects: a build and a deploy one. It assigns to them the required security policies, like AmazonEKSClusterPolicy and it creates then three actions: one GitHubSourceAction and two CodeBuildAction, one for the build and the other one for the deploy operation. Last but not least, a Pipeline is created and the three mentioned actions are added as its stages.

The MonitoringStack

This stack provides observability and monitoring capabilities for the EKS cluster and running applications. It creates a dedicated CloudWatch log group named /aws/eks/customer-service with a one-week retention policy to collect and store logs from the EKS pods and cluster components and a CloudWatch dashboard named customer-service-eks that visualizes key metrics including but not limited to pod CPU utilization from the EKS namespace.

public void initStack()
{
  LogGroup.Builder.create(this, "EksLogGroup")
    .logGroupName("/aws/eks/customer-service")
    .retention(RetentionDays.ONE_WEEK)
    .build();
  Dashboard dashboard = Dashboard.Builder.create(this, "CustomerServiceDashboard")
  .dashboardName("customer-service-eks")
  .build();
  dashboard.addWidgets(
    GraphWidget.Builder.create()
      .title("Pod CPU Utilization")
      .left(List.of(Metric.Builder.create()
        .namespace("AWS/EKS")
        .metricName("pod_cpu_utilization")
        .build()))
      .build()
  );
}

This stack depends on the EksClusterStack to ensure the cluster exists before monitoring resources are created. The monitoring infrastructure enables real-time visibility into cluster health, performance metrics, and troubleshooting capabilities through centralized log aggregation.

Building, deploying and testing

The API to be built a deployed on EKS with Fargate is the same as the one we used previously for the ECS project (see the customer-service-api module). Other shared artifacts are provided by the customer-service-cdk-common module. Here is their list:

• DatabaseConstruct: implements a CDK construct for RDS (Relational Database Service) with PostgreSQL;
• RedisCluster: implements a CDK construct for ElasticCache with Redis;
• RedisClusterProps: gropus together, in one record, several common Redis properties like the cluster ID, the number of nodes, their types, etc.
• DatabaseStack: implements a database CDK stack which includes the previous mentioned PostgreSQL and Redis constructs.

Since these common artifacts are all required in order to build and deploy our stack, they need to be installed in the local Maven repository:

$ cd aws-cdk-quarkus/customer-service-api
$ mvn clean install
$ cd aws-cdk-quarkus/customer-service-cdk-common
$ mvn clean install

The Maven build process of the customer-service-api will run 2 integration tests, one using RESTassured against the Quarkus embedded web service, the other against a full local containerized infrastructure described by a docker-compose.yaml file. This has been fully documented and explained in te 1st part of this series.

Now, we can build, deploy and test our new stack. The customer-service-eks module provides two ways to do it:

• in development mode, using minikube;
• in production mode, using AWS infrastructure;

Please notice that localstack, which is a very practical way to test AWS based IaC code without the cloud heavyness and costs, isn’t an option here, as it doesn’t support EKS, VPC, ECR, etc.

Building, deploying and testing in dev mode

As mentioned, using the dev mode, all our stacks are deployed locally, on minikube. So, this mode requires minikube to be installed and running.

The pom.xml file defines two profiles:

• a dev mode one named local;
• a prod mode one named e2e;

Here is the dev mode one, which is also the default one:

<profile>
  <id>local</id>
  <activation>
    <activeByDefault>true</activeByDefault>
  </activation>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>start-minikube</id>
            <phase>pre-integration-test</phase>
            <goals><goal>exec</goal></goals>
            <configuration>
              <executable>minikube</executable>
              <arguments>
                <argument>start</argument>
                <argument>--driver=docker</argument>
              </arguments>
            </configuration>
          </execution>
          <execution>
            <id>deploy-to-minikube</id>
            <phase>pre-integration-test</phase>
            <goals><goal>exec</goal></goals>
            <configuration>
              <executable>bash</executable>
              <arguments>
                <argument>src/main/resources/scripts/deploy-to-minikube.sh</argument>
              </arguments>
            </configuration>
          </execution>
          <execution>
            <id>stop-minikube</id>
            <phase>clean</phase>
            <goals><goal>exec</goal></goals>
            <configuration>
              <executable>minikube</executable>
              <arguments>
                <argument>delete</argument>
              </arguments>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

As you can see, here we’re using the exec-maven-plugin with 3 executions that starts minikube, deploy to minikube and, respectively, stop minikube. As already mentioned, minikube should be installed in order that the local profile be effective and, the action with ID start-minikube simply executes the start command.

Once minikube started, the action with ID deploy-to-minikube executes the deploy-to-minikube.sh script, shown below:

#!/bin/bash
set -e

echo ">>> Loading image..."
docker save nicolasduminil/customers-api:1.0-SNAPSHOT | minikube image load -

echo ">>> Creating namespace..."
kubectl create namespace customer-service --dry-run=client -o yaml | kubectl apply -f -

echo ">>> Deploying PostgreSQL and Redis..."
kubectl apply -f src/test/resources/k8s/postgres-redis.yaml

echo ">>> Waiting for database..."
for i in {1..5}; do
  if kubectl get pod -l app=postgres -n customer-service 2>/dev/null | grep -q postgres; then
    break
  fi
  echo "Waiting for postgres pod to be created... ($i/5)"
  sleep 5
done

kubectl wait --for=condition=ready pod -l app=postgres -n customer-service --timeout=60s

echo ">>> Deploying application..."
kubectl apply -f target/kubernetes/minikube.yml

echo ">>> Waiting for application..."
for i in {1..5}; do
  if kubectl get pod -l app.kubernetes.io/name=customer-service-api -n customer-service 2>/dev/null | grep -q customer-service; then
    break
  fi
  echo "Waiting for app pod to be created... ($i/5)"
  sleep 5
done
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=customer-service-api -n customer-service --timeout=120s

echo ">>> Final status:"
kubectl get all -n customer-service

echo ">>> Starting port-forward..."
kubectl port-forward -n customer-service service/customer-service-api 9090:80 > /dev/null 2>&1 &
echo "Port-forward started (PID: $!)"
sleep 2

The deploy-to-minikube.sh script above is structured for performing several operations. First, the Docker image nicolasduminil/customers-api:1.0-SNAPSHOT built during the previous step (the shared components) is loaded to minikube via the command image load. Then, the kubectl tool, which is another prerequisite, is used to create the customized namespace customer-service and to apply the two manifests: postgresql-manifest.yaml and minikube.yml. Last but not least, after having waited that all the services be on, the same kubectl is used to start the port-forward process.

At that point we’re able to test our API locally deployed on minikube using the Swagger UI. Fire your preferred browser at http://localhost:9090/q/swagger-ui to take advantage of the 80 to 9090 port-forward. You’re ready to test the API.

Please notice that the minikube.yml manifest file mentioned above is automatically generated by the JIB extension for Quarkus, while the postgres-redis.yaml was written on the purpose, to define the Kubernetes deployment and service controllers associated to the PostgreSQL databse and Redis cache. Don’t hesitate to have a look at this file and make sure you understand what everything is about there.

Building, deploying and testing in prod mode

While the Maven building process is the same and consists in running

$ mvn -Pe2e -DskipTests clean install

deploying is, this time, a much longer and heavier operation as it targets real AWS infrastructure. Look at the e2e Maven profile below:

<profile>
  <id>e2e</id>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <executions>
          <execution>
            <id>deploy-to-aws</id>
            <phase>pre-integration-test</phase>
            <goals>
              <goal>exec</goal>
            </goals>
            <configuration>
              <executable>bash</executable>
              <arguments>
                <argument>./src/main/resources/scripts/deploy-to-aws.sh</argument>
              </arguments>
              <workingDirectory>${project.basedir}</workingDirectory>
              <environmentVariables>
                <CDK_DEFAULT_ACCOUNT>${CDK_DEFAULT_ACCOUNT}</CDK_DEFAULT_ACCOUNT>
                <CDK_DEFAULT_REGION>${CDK_DEFAULT_REGION}</CDK_DEFAULT_REGION>
                <CDK_DEFAULT_USER>${CDK_DEFAULT_USER}</CDK_DEFAULT_USER>
                <CONTAINER_IMAGE_GROUP>${CONTAINER_IMAGE_GROUP}</CONTAINER_IMAGE_GROUP>
                <CONTAINER_IMAGE_NAME>${CONTAINER_IMAGE_NAME}</CONTAINER_IMAGE_NAME>
                <CONTAINER_PORT>${CONTAINER_PORT}</CONTAINER_PORT>
              </environmentVariables>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</profile>

What this profile is doing is simply running the deploy-to-aws.sh script via the exec-maven-plugin.

#!/bin/bash
set -e
...
../customer-service-cdk-common/src/main/resources/scripts/deploy-ecr.sh

echo ">>> Updating kubeconfig..."
aws eks update-kubeconfig --region $CDK_DEFAULT_REGION --name customer-service-cluster

echo ">>> Checking EKS access..."
USER_ARN=$(aws sts get-caller-identity --query 'Arn' --output text)
grant_eks_access "$USER_ARN" "current user"

echo ">>> Granting EKS access to CodeBuild deploy role..."
DEPLOY_ROLE_ARN=$(aws iam list-roles --query 'Roles[?contains(RoleName, `CustomerServiceDeployRole`)].Arn' --output text --region $CDK_DEFAULT_REGION)
if [ -n "$DEPLOY_ROLE_ARN" ]; then
  grant_eks_access "$DEPLOY_ROLE_ARN" "deploy role"
else
  echo ">>> Deploy role not found (pipeline not deployed yet)"
fi

echo ">>> Retrieving database password from Secrets Manager..."
SECRET_ARN=$(jq -r '.DatabaseStack.DatabaseSecretArn' cdk-outputs.json)
DB_PASSWORD=$(aws secretsmanager get-secret-value --secret-id $SECRET_ARN --region $CDK_DEFAULT_REGION --query SecretString --output text | jq -r .password)

echo ">>> Creating Kubernetes secret with database password..."
kubectl create secret generic db-credentials \
  --from-literal=QUARKUS_DATASOURCE_PASSWORD="$DB_PASSWORD" \
  -n customer-service --dry-run=client -o yaml | kubectl apply -f -

echo ">>> Waiting for pods to be ready..."
kubectl wait --for=condition=ready pod -l app=customer-service-api -n customer-service --timeout=300s || true

echo ">>> Deployment complete!"
echo ">>> To access the API locally, run:"
echo ">>>   ./src/main/resources/scripts/test-api.sh"
echo ">>> Then test with:"
echo ">>>   curl http://localhost:8080/q/health"

The script above contains several distinct sections. First, it runs the shared script deploy-ecr.sh, present in the customer-service-cdk-common module, which deploys to ECR (Elastic Container Registry) the image nicoladuminil/customer-service-api::1.0-SNAPSHOT, built previously, before running the cdk deploy command, which deploys to AWS all the CloudFormation stacks. This process is very complex and long and, depending on your network speed , it may take 15 - 20 minutes.

Then the script updates the .kube/config file with the EKS cluster required parameters, such that it could be handled further by kubectl. Next it grants the AmazonEKSClusterAdminPolicy to the current user and the deployer user, identified by the CustomerServiceDeployRole. Then it gets the AWS secret containing the PostgreSQL database user password and creates a Kubernetes secret to be used by the associated pod. Once that all the pods started and are healthy, the script displays instructions of how to proceed further for testing purposes.

Several tests are available, once that the deployment process has succeeded. First, an e2e test, named CustomerServiceE2EIT can be run as folowws:

$ mvn -Pe2e failsafe:integration-test

Here is the listing:

public class CustomerServiceE2EIT extends AbstractCustomerServiceE2E
{
  private static Process portForwardProcess;

  @BeforeAll
  static void setup() throws Exception
  {
    startPortForward();
    configureEndpoint("localhost:8080");
    waitForServiceReady();
  }

  @AfterAll
  static void teardown()
  {
    if (portForwardProcess != null && portForwardProcess.isAlive())
    {
      portForwardProcess.destroy();
      System.out.println(">>> Port-forward stopped");
    }
  }

  private static void startPortForward() throws Exception
  {
    System.out.println(">>> Waiting for deployment to be ready...");
    Process waitProcess = new ProcessBuilder(
      "kubectl", "wait", "--for=condition=Available",
      "deployment/customer-service-api-deployment",
      "-n", "customer-service",
      "--timeout=300s"
      ).start();

    if (waitProcess.waitFor() != 0)
      throw new RuntimeException("### Deployment not available");

    System.out.println(">>> Starting port-forward...");
    portForwardProcess = new ProcessBuilder(
      "kubectl", "port-forward",
      "deployment/customer-service-api-deployment",
      "8080:8080",
      "-n", "customer-service"
    ).start();

    Thread.sleep(3000);
    System.out.println(">>> Port-forward established on localhost:8080");
  }
}

As you can see, the test extends the AbstractCustomerServiceE2E present in the shared module customer-service-cdk-common. This abstract class defines the test case to be run as they are the same whatever the cloud runtime is, be it ECS or EKS. The only operation specific to the cloud runtime is the port-forward process start, implemented by the method startPortForward().

Of course, you can test your API using the Swagger UI, as you did before, in dev mode. The only thing you need to do is to start the port-forward and, for this, the script test-api.sh, here below, comes very handy:

#!/bin/bash
echo ">>> Starting port-forward to access API locally..."
echo ">>> API will be available at http://localhost:8080"

nohup kubectl port-forward svc/customer-service-api-service -n customer-service 8080:80 2>/dev/null &

Then fire your preferred browser, as usual, at http://localhost:8080/q/swagger-ui. Other test scripts, like load-distribution-demo.sh, perf-demo.sh, pods-monitoring.sh, scaling-demo.sh, are available as well, just run them.

Once you finished testing, please cancel the port-forwarding by running:

$ pkill -f "kubectl port-forward"

And don’t forget to clean up your cloud by running:

$ cd aws-cdk-quarkus/customer-service/eks
$ cdk destroy --all --force

A script named destroy-all.sh is also available for a more atomic destruction.

Troubleshooting in prod mode

Working in prod mode, i.e. running the API and the associated tests against real AWS infrastructure, is challenging. The environment is very complex and, at any step, dozens of issues might prevent things to happen as expected. Hence, the necessity to be able to visualize the cloud infrastructure current status and the most recent events.

While the AWS Console is a very usefull tool, designed on the purpose to optimize the visualization of the cloud infrastructure status, using the kubectl utility represents the Kubernetes most traditional way to check the cluster health. Also, AWS CLI is able to perform all the AWS Console functions, in a less intuitive way, which requires a deep knowledge, but which might be more practical, less repetitive as scriptable, and less error-prone.Accordingly, a kubectl and AWS CLI commands breviary could be helpful in order to fix issues.

Verifying the EKS cluster deployment

The following kubectl commands can be used to verify the EKS cluster deployment:

1. Check the cluster:

$ kubectl get nodes -n customer-service

1. Check the pods:

$ kubectl get pods -n customer-service

1. Check the services:

kubectl get services -n customer-service

1. View all logs from pods:

$ kubectl logs -f -l app=customer-service-api -n customer-service

1. Check rollout status:

$ kubectl rollout status deployment/customer-service-api-deployment -n customer-service

1. View deployment details:

$ kubectl describe deployment customer-service-api-deployment -n customer-service

1. Verify ECR repository exists:

$ aws ecr describe-repositories --region eu-west-3

1. Check IAM permissions

$ aws iam get-role-policy --role-name <build-role-name> --policy-name <policy-name>

1. Verify EKS cluster access

$ aws eks describe-cluster --name customer-service-cluster --region eu-west-3

1. Check pod events

$ kubectl describe pod <pod-name> -n customer-service

1. Verify RDS endpoint

$ aws rds describe-db-instances --region eu-west-3

Verifying th CI/CD Pipeline deployment

1. Get the webhook URL:

aws codepipeline list-webhooks --region eu-west-3

1. Check pipeline execution status:

$ PIPELINE=$(aws codepipeline list-pipelines --region eu-west-3 --query 'pipelines[?starts_with(name, `CiCdPipelineStack`)].name' --output text)
$ aws codepipeline get-pipeline-state --name $PIPELINE --region eu-west-3

1. List recent pipeline executions:

$ aws codepipeline list-pipeline-executions --pipeline-name $PIPELINE --region eu-west-3 --max-items 5

1. Get CodeBuild project names:

$ aws codebuild list-projects --region eu-west-3 --query 'projects[?contains(@, `CustomerService`)]'

1. Check build project status:

$ BUILD_PROJECT=$(aws codebuild list-projects --region eu-west-3 --query 'projects[?contains(@, `CustomerServiceBuild`)]' --output text)
$ aws codebuild batch-get-projects --names $BUILD_PROJECT --region eu-west-3

1. List recent builds:

$ aws codebuild list-builds-for-project --project-name $BUILD_PROJECT --region eu-west-3 --max-items 5

1. Get detailed build information:

$ BUILD_ID=$(aws codebuild list-builds-for-project --project-name $BUILD_PROJECT --region eu-west-3 --query 'ids[0]' --output text)
$ aws codebuild batch-get-builds --ids $BUILD_ID --region eu-west-3

1. View build logs:

$ aws logs tail /aws/codebuild/$BUILD_PROJECT --since 30m --follow --region eu-west-3

1. Check deploy project status:

$ DEPLOY_PROJECT=$(aws codebuild list-projects --region eu-west-3 --query 'projects[?contains(@, `CustomerServiceDeploy`)]' --output text)
$ aws codebuild list-builds-for-project --project-name $DEPLOY_PROJECT --region eu-west-3 --max-items 5

1. View deploy logs:

$ aws logs tail /aws/codebuild/$DEPLOY_PROJECT --since 30m --follow --region eu-west-3

1. Verify GitHub OAuth token secret:

$ aws secretsmanager describe-secret --secret-id github-oauth-token --region eu-west-3

1. Check CodeBuild service role permissions:

$ BUILD_ROLE=$(aws iam list-roles --query 'Roles[?contains(RoleName, `CustomerServiceBuildRole`)].RoleName' --output text)
$ aws iam list-attached-role-policies --role-name $BUILD_ROLE
$ aws iam list-role-policies --role-name $BUILD_ROLE

1. Check deploy role EKS access:

$ DEPLOY_ROLE_ARN=$(aws iam list-roles --query 'Roles[?contains(RoleName, `CustomerServiceDeployRole`)].Arn' --output text)
$ aws eks list-access-entries --cluster-name customer-service-cluster --region eu-west-3

Verifying the Monitor Pipeline

1. List the existent pipeleines

$ aws codepipeline list-pipelines --region eu-west-3 --query 'pipelines[?starts_with(name, `CiCdPipelineStack`)].name' --output text
CiCdPipelineStack-CustomerServicePipelineB3195C39-t9UMJeMAQlDN

1. Get the monitoring pipeline status

$ aws codepipeline get-pipeline --name $PIPELINE --region eu-west-3 --query 'pipeline.stages[?name==`Build`].actions[0].configuration.ProjectName' --output text
CustomerServiceBuild0A9B7C3-YIk2RDA0JP1B

1. View the monitoring pipeline log file

aws logs tail /aws/codebuild/CustomerServiceBuild0A9B7C3-YIk2RDA0JP1B --since 30m --follow --region eu-west-3

Conclusions

This project demonstrates a production-ready approach to deploying containerized Quarkus applications on AWS EKS with Fargate, leveraging Infrastructure as Code through the AWS CDK. By combining Kubernetes orchestration with serverless compute, we achieve operational simplicity without sacrificing the flexibility and portability that Kubernetes provides.

The automated CI/CD pipeline ensures consistent deployments from code commit to production, while the comprehensive monitoring and troubleshooting capabilities enable reliable operations at scale. Whether you’re migrating from ECS to EKS or building cloud-native applications from scratch, this architecture provides a solid foundation for modern microservices deployment on AWS.

Source code

While focusing on the CDK fundamentals in Java, like Stack and Construct, together with their Quarkus implementations, this series was a bit frugal as far as the infrastructure elements were concerned. Indeed, for the sake of the clarity and simplification, the infrastructure used to illustrate how to use the CDK with Java and Quarkus was inherently consensual. Hence, the idea of a new series, of which this article is the first one, a series less concerned by CDK internals and more dedicated to the infrastructure itself.

This first article demonstrates how to build and deploy a modern, cloud-native customer management system using Quarkus, AWS CDK, and ECS/Fargate. It covers the complete journey from application development to infrastructure as code, containerization and comprehensive testing strategies. Once again, it doesn’t emphasise on the exposed API and its possible business value, but rather on the infrastructure elements required in order to provide the global solution in practice.

Architecture Overview

The diagram below shows an overview of the project’s architecture:

This presented solution implements the following architecture layers:

• Presentation Layer : A Quarkus REST API exposing, as an example, a couple of simple customer management endpoints.
• Application Layer : A Quarkus main application running on ECS Fargate
• Data Layer : PostgreSQL (RDS) for persistence, Redis (ElastiCache) for caching
• Infrastructure Layer (Iaas): The AWS CDK-managed cloud infrastructure implemented in Quarkus

Let’s try now to look in more details at these layers.

The Presentation Layer

This layer is a Quarkus REST API which exposes a couple os simple endpoints to CRUD customers. More than a real business API, this one is an example allowing to illustrate how containerized applications could be deployed and hosted in an AWS ECS (Elastic Container Service).

In order to separate concerns, our Maven project is structured in two modules:

• the customer-service-ecs-api module which implements the Quarkus REST API to be deployed and executed as a Docker image in the AWS ECS service;
• the customer-service-exce-cdk module which bootstraps the CDK and creates the required elements in order to implement the cloud infrastructure presented in the figure above.

The Presentation Layer is contained in the customer-service-ecs-api module. The exposed REST API is simple and consists in the following endpoints to CRUD Customer entities:

• GET /customers: returns a response containing the list of the currently existent customers;
• POST /customers: creates a new customer by persisting the entity passed in the request’s body;
• PUT /customers/{id}: updates the existent customer having the ID equal to the one passed as the id parameter. If such a customer doesn’t exist then HTTP 404 is returned.
• GET /customers/{id}: returns a response containing the customer having the ID equal to the one passed as the id parameter. If such a customer doesn’t exist then HTTP 404 is returned.
• DELETE /customers/{id}: deletes the customer having the ID equal to the one passed as the id parameter. If such a customer doesn’t exist then HTTP 404 is returned.

The endpoints above are implemented in the class CustomerResource which is a CDI (Context Dependency Injection) bean, annotated with @ApplicationScoped. This is a very realistic example of using CDI in AWS deployed infrastructure elements.

The Application Layer

This layer is the “brain” of the system, the place where the actual customer management business logic resides, separated from how it is exposed by the presentation layer. In our project it is included in the module customer-service -ecs-api as well and it consists in:

• the Customer entity which is the domain model representing the business object;
• the CustomerService class containing the core business logic to CRUD operations;
• the caching strategies using Redis;
• the transaction management;
• the business rules and validation logic;

We mentioned precedently that the CustomerResource class, as the pilar of the presentation layer, is a CDI bean and, as such, it injects another CDI bean, the CustomerService class, which performs the effective CRUD operations on Customer business objects, using Quarkus Panache. The listing below shows the Customer entity:

@Entity
@Table(name = "customers")
public class Customer extends PanacheEntity
{
  @NotBlank
  public String firstName;
  @NotBlank
  public String lastName;
  @Email
  @NotBlank
  public String email;
  public String phone;
  public String address;

  public Customer(){}
  ...
}

As you can see, the validation rules are expressed using Jakarta Validation constraints.

Given this very simplified representation of a customer, the CustomerService class uses the PanacheEntity methods to CRUD customers, as shown below:

@ApplicationScoped
public class CustomerService
{
  @Inject
  RedisDataSource redisDS;

  @Transactional
  public Customer create(Customer customer)
  {
    customer.persist();
    invalidateCache("customers:all");
    return customer;
  }

  public List<Customer> findAll()
  {
    return Customer.listAll();
  }

  public Customer findById(Long id)
  {
    ValueCommands<String, Customer> cache = redisDS.value(Customer.class);
    Customer cached = cache.get("customer:" + id);
    return Optional.ofNullable(cached).orElseGet(() -> {
      Customer customer = Customer.findById(id);
      if (customer != null)
        cache.setex("customer:" + id, 300, customer);
      return customer;
    });
  }

  @Transactional
  public Customer update(Long id, Customer updates)
  {
    return Optional.ofNullable((Customer) Customer.findById(id))
      .map(customer ->
      {
        customer.updateFrom(updates);
        invalidateCache("customer:" + id);
        invalidateCache("customers:all");
        return customer;
      })
      .orElse(null);
  }

  @Transactional
  public boolean delete(Long id)
  {
    boolean deleted = Customer.deleteById(id);
    if (deleted)
    {
      invalidateCache("customer:" + id);
      invalidateCache("customers:all");
    }
    return deleted;
  }

  private void invalidateCache(String key)
  {
    redisDS.key().del(key);
  }
}

Nothing very spectacular here, just an usual Quarkus Panache service to CRUD customers. As you can see, the transaction management that we mentioned previously are implemented on the behalf of the @Transactional annotation provided by the Jakarta Transaction specification, implemented by Quarkus.

The application layer isn’t directly invoked but through the API endpoints, in the CustomerResource class, for example:

  ...
  @POST
  public Response create(@Valid Customer customer)
  {
    return Response.status(Response.Status.CREATED)
      .entity(customerService.create(customer)).build();
  }
  ...

The endpoint above is invoked through HTTP by a REST client and, in turn, it calls CustomerService. And talking about REST clients, we also provide a MicroProfile (MP) REST Client, which aims at facilitating the integration, by giving the API consumers an easy and practical way to invoke it. Look at the interface CustomerClient below:

@RegisterRestClient(configKey = "customers-api")
@Path("/customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public interface CustomerClient
{
  @POST
  Response createCustomer(Customer customer);
  @GET
  @Path("/{id}")
  Response getCustomer(@PathParam("id") Long id);
  @GET
  public Response getCustomers();
  @PUT
  @Path("/{id}")
  Response updateCustomer(@PathParam("id") Long id, @Valid Customer customer);
  @DELETE
  @Path("/{id}")
  Response delete(@PathParam("id") Long id);
}

For those not yet familiar with the MP REST Client specification and its Quarkus implementation, this interface is all you need in order to probe your API. I’ll come back later to it when we’ll discuss testing.

Let’s look now at the infrastructure layer.

The Infrastructure Layer

This layer makes the object of the 2nd project’s module: customer-service-ecs-cdk. It consists of a Quarkus main class, named CustomerManagementMain, shown below:

@QuarkusMain
public class CustomerManagementMain
{
  public static void main(String... args)
  {
    Quarkus.run(CustomerManagementApp.class, args);
  }
}

This class is the entry point class that bootstraps the Quarkus CDK application. It uses @QuarkusMain to define the main method and delegates to Quarkus runtime to run the CustomerManagementApp class, shown below;

@ApplicationScoped
public class CustomerManagementApp implements QuarkusApplication
{
  private CustomerManagementStack customerManagementStack;
  private App app;

  @Inject
  public CustomerManagementApp (App app, CustomerManagementStack customerManagementStack)
  {
    this.app = app;
    this.customerManagementStack = customerManagementStack;
  }

  @Override
  public int run(String... args) throws Exception
  {
    Tags.of(app).add("project", "Containerized Customer Management Application on ECS/Fargate");
    Tags.of(app).add("environment", "development");
    Tags.of(app).add("application", "CustomerManagementApp");
    customerManagementStack.initStack();
    app.synth();
    return 0;
  }
}

This class is the main application class, as opposed to the Quarkus main class. It orchestrates the CDK stack creation by:

The main application class implementing QuarkusApplication. It orchestrates the CDK stack creation by:

• injecting the CDK App and CustomerManagementStack via CDI;
• adding global tags to the CDK app for project identification;
• initializing the stack infrastructure;
• synthesizing the CloudFormation templates;

The class CustomerManagementStack, too long to be reproduced here, defines the CDK stack to be deployed. This stack consists in the following AWS infrastructure:

• a VPC (Virtual Private Cloud) with a public and a private subnet across multiple AZs (Availability Zone);
• a NAT (Network Address Translation) gateway to outbound the internet access for private resources;
• an RDS (Relational Database Service) with a PostgreSQL database with automated backups and secrets’ management;
• a Redis cluster using AWS ElastiCache for in-memory caching and performance optimization;
• an ECS (Elastic Container Service) Fargate serverless container hosting platform;
• an ALB (Application Load Balancer) for the traffic distribution and health checking;
• a Secrets Manager for the secure credential store and rotation;
• all the required security groups and network level access control;
• a CloudWatch log group for monitoring;
• the required IAM (Identity and Access Management) roles for the fine-grained permission management;

The Java CDK provides the familiar pattern Builder which makes easy to instantiate complex structures and class hierarchies. The code excerpt below provides an example:

    ApplicationLoadBalancedFargateService fargateService =
      ApplicationLoadBalancedFargateService.Builder.create(this, "CustomerService")
        .cluster(cluster)
        .cpu(config.ecs().cpu())
        .memoryLimitMiB(config.ecs().memoryLimitMiB())
        .desiredCount(config.ecs().desiredCount())
        .taskImageOptions(ApplicationLoadBalancedTaskImageOptions.builder()
          .image(ContainerImage.fromRegistry(imageName))
          .containerPort(containerPort)
          .logDriver(LogDriver.awsLogs(AwsLogDriverProps.builder()
            .logGroup(logGroup)
            .streamPrefix(config.logging().streamPrefix())
            .build()))
          .environment(Map.of(
            "QUARKUS_DATASOURCE_JDBC_URL",
              "jdbc:postgresql://" + database.getInstanceEndpoint().getHostname() +
              ":5432/" + config.database().databaseName(),
            "QUARKUS_REDIS_HOSTS", "redis://" + redis.getPrimaryEndpoint() + ":6379"
          ))
          .secrets(Map.of(
            "QUARKUS_DATASOURCE_USERNAME",
              Secret.fromSecretsManager(database.getSecret(), "username"),
            "QUARKUS_DATASOURCE_PASSWORD",
              Secret.fromSecretsManager(database.getSecret(), "password")
          ))
          .build())
        .publicLoadBalancer(true)
        .healthCheckGracePeriod(Duration.seconds(config.ecs().healthCheckGracePeriodSeconds()))
        .serviceName(config.ecs().serviceName())
        .minHealthyPercent(100)
        .build();

This code sequence uses different builders in order to instantiate a full ECS Fargate serverless hosting platform. Given the high number of parameters that this process requires, the InfrastructureConfig interface, here below, provides a type-safe Quarkus @ConfigMap.

@ConfigMapping(prefix = "cdk.infrastructure")
public interface InfrastructureConfig
{
  VpcConfig vpc();
  EcsConfig ecs();
  DatabaseConfig database();
  RedisConfig redis();
  LoggingConfig logging();
  interface VpcConfig
  {
    @WithDefault("2")
    int maxAzs();
    @WithDefault("1")
    int natGateways();
  }
  interface EcsConfig
  {
    @WithDefault("256")
    int cpu();
    @WithDefault("512")
    int memoryLimitMiB();
    @WithDefault("2")
    int desiredCount();
    @WithDefault("60")
    int healthCheckGracePeriodSeconds();
    @WithDefault("customer-service")
    String serviceName();
  }
  interface DatabaseConfig
  {
    @WithDefault("BURSTABLE3")
    String instanceClass();
    @WithDefault("MICRO")
    String instanceSize();
    @WithDefault("customers")
    String databaseName();
    @WithDefault("postgres")
    String secretUsername();
    @WithDefault("false")
    boolean deletionProtection();
  }
  interface RedisConfig
  {
    @WithDefault("cache.t3.micro")
    String nodeType();
    @WithDefault("1")
    int numNodes();
    @WithDefault("customer-cache")
    String clusterId();
    @WithDefault("Redis cache for customer service")
    String description();
  }
  interface LoggingConfig
  {
    @WithDefault("/ecs/customer-service")
    String logGroupName();
    @WithDefault("ONE_WEEK")
    String retentionDays();
    @WithDefault("ecs")
    String streamPrefix();
  }
}

This @ConfigMap defines nested configuration structures for different infrastructure components and @WithDefault annotations for default values and provides compile-time configuration validation while organizing settings into logical groups like VPC, ECS, database, Redis, and logging.

CDK Configuration and Deployment

AWS CDK uses the cdk.json file as its primary configuration mechanism to define how the CDK application should be executed and deployed. This file serves as the entry point that tells the CDK toolkit how to run the infrastructure application.

Here below is the file cdk.json used for this project:

{
  "app": "java -jar target/quarkus-app/quarkus-run.jar",
  "context": {
    "aws-cdk:enableDiffNoFail": true,
    "@aws-cdk/aws-ecs:minHealthyPercent": true
  },
  "requireApproval": "never",
  "output": "cdk.out",
  "progress": "bar",
  "ci": true,
  "verbose": false,
  "acknowledgements": {
    "@aws-cdk/aws-ecs:ecrImageRequiresPolicy": true,
    "@aws-cdk/aws-ecs:minHealthyPercent": true,
    "34892": true
  },
  "notices": false
}

Looking at this file, several categories of key aspects are to be brought into focus:

• The app element: defines the command which executes the application. Our application being a Quarkus one, the app element reflects that by defining the standard way to run a Quarkus JVM application.
• The context element: stores environment specific settings. In our case:
  • "aws-cdk:enableDiffNoFail": true controls the behavior of the cdk diff command such that to continue the execution even if it encounters errors, for example missing permissions to describe resources, etc.
  • "@aws-cdk/aws-ecs:minHealthyPercent": true is an ECS specific flag that enables the minHealthyPercent property for ECS services. Here, it allows setting the minimum percentage of healthy tasks during deployments (e.g., 50% for rolling updates).
• The feature flags: control CDK behavior and enables/disables specific features. In our case:
  • "requireApproval": "never" says that the CDK will never prompt for manual approval during cdk deploy operations.
  • "output": "cdk.out" sets the directory where the CloudFormation templates, generated by the cdk synth command, will be stored.
  • "progress": "bar" shows progress bar during CDK operations instead of detailed logs.
  • "ci": true optimizes output for CI/CD environments (less interactive, more structured).
  • "verbose": false suppresses detailed debug information during execution.
  • "notices": false disables CDK notices about new features or deprecations.
• The acknowledgements:
  • "@aws-cdk/aws-ecs:ecrImageRequiresPolicy": true acknowledges that ECR images require IAM policies for access;
  • "@aws-cdk/aws-ecs:minHealthyPercent": true confirms understanding of ECS health check behavior
  • "34892": true acknowledges specific CDK issue/warning (likely related to a GitHub issue number)

This cdk.json file is used by the CDK toolkit to:

• Synthesis: execute the app command to generate CloudFormation templates in cdk.out.
• Deployment: use the synthesized templates to deploy infrastructure to AWS.
• Context Management: cache AWS account/region specific information for consistent deployments.

Running and testing

There are several test categories that come with the project, as follows:

• integration tests;
• system integration tests;
• Open API / Swagger tests;
• end-to-end tests.

As you can see, we don’t provide unit tests because we think that this category of tests is completely useless. But this is another topic which doesn’t belong to the scope of this article.

The Integration tests

These tests aim at testing the complete REST API layer with the Quarkus runtime. They use the test infrastructure automatically provide by the Quarkus Dev Services with an in-memory H2 database, in order to validate the API contracts, the requests/responses and the business logic integration.

The class CustomerResourceTest is one test in this category. It is executed by the maven-surefire-plugin in the Maven test phase, hence its naming convention: *Test.

@QuarkusTest
public class CustomerResourceTest
{
  @Test
  void testCreateCustomer()
  {
    given()
      .contentType(ContentType.JSON)
      .body("""
        {
          "firstName": "John",
          "lastName": "Doe",
          "email": "john@example.com"
        }
      """)
      .when()
      .post("/customers")
      .then()
      .statusCode(201)
      .body("firstName", equalTo("John"));
  }
  ...
}

We reproduced here only one test method, the one creating new customers. Feel free to extensively look at this class which uses the RESTassured library as REST client.

Another integration test is the class CloudFormationTemplateIT. As opposed to the previous one, this class is executed by the maven-failsafe-plugin in the Maven verify phase. The reason is that it needs to be run after the cdk synth command, executed by the exec-maven-plugin. This command synthesizes the required AWS infrastructure in the form of a CloudFormation template, stored in the directory cdk.out. Then the test class checks the files in this directory for the presence and the validity of these AWS infrastructure elements.

In order to perform the integration test:

$ cd aws-cdk-quarkus
$ mvn clean verify

The Maven command above will execute, in addition to the integration tests, the system integration tests.

The System Integration Tests

These tests are a more realistic version of the integration ones. As opposed to the former ones, which were relying on a Quarkus runtime related infrastructure, these tests are more realistic in the sense that they are performed against a local, while production similar, containerized infrastructure. During the Maven verify phase, the exec-maven-plugin executes the docker-compose.yaml file against the currently running Docker daemon and starts all the required services, as follows:

• a PostgreSQL database;
• the adminer tool to administrate the database;
• a Redis node for in-memory caching purposes;
• the redis-insight tool to administrate the local Redis instance;
• the customer management API as a Quarkus application.

Once all this infrastructure is started, the CustomerResourceIT class uses the CustomerClient to test the API running locally. The usage of the MP REST Client isn’t mandatory, of course, other REST clients, like RESTassured or simply Jakarta REST Client, can be used. However, the MP REST Client is, in my opinion, the simplest and the most effective solution.

@QuarkusTest
@TestProfile(IntegrationTestProfile.class)
public class CustomerResourceIT
{
  @Inject
  @RestClient
  CustomerClient customerClient;

  @Test
  void testCreateCustomer()
  {
    Customer customer = new Customer("John", "Doe", "john@example.com",
      "000000000000", "123 Main St");
    Response response = customerClient.createCustomer(customer);
    assertThat(response.getStatus()).isEqualTo(201);
    customer = response.readEntity(Customer.class);
    assertThat(customer.firstName).isEqualTo("John");
    assertThat(customer.lastName).isEqualTo("Doe");
    assertThat(customer.email).isEqualTo("john@example.com");
  }
  ...
}

As you can see, the test is using a Quarkus customized profile, named IntegationTestProfile, shown below:

public class IntegrationTestProfile implements QuarkusTestProfile
{
  @Override
  public Map<String, String> getConfigOverrides()
  {
    return Map.of(
      "quarkus.datasource.db-kind", "postgresql",
      "quarkus.datasource.username", "nicolas",
      "quarkus.datasource.password", "dev123",
      "quarkus.datasource.jdbc.url", "jdbc:postgresql://localhost:5432/customers",
      "quarkus.datasource.devservices.enabled", "false",
      "quarkus.redis.hosts", "redis://localhost:6379",
      "quarkus.redis.devservices.enabled", "false"
    );
  }
}

The Swagger tests

The module customer-service-ecs-api exposes a Swagger interface that you can use to manually test the API. Just fire your preferred browser at http://localhost:8080/q/swagger-ui and you’ll be presented with that:

This will allow you to probe your API.

The E2E Tests

The last test category is the end-to-end one. These tests have the particularity to be performed against the real AWS services (ECS, RDS, ElasticCache, etc.). The class CustomerServiceE2EIT is such a test. It’s similar to the integration test CustomerResourceTest in the sense that it uses RESTassured to probe the API but, instead of invoking local endpoints, it invokes endpoints onto the real API deployed on the AWS Fargate platform and executed as a Docker image.

Everything happens in the code sequence below:

  @BeforeAll
  static void setup()
  {
    cfClient = CloudFormationClient.builder()
     .region(Region.EU_WEST_3)
     .build();
    String loadBalancerUrl = getStackOutput("QuarkusCustomerManagementStack", "CustomerServiceLoadBalancerDNS");
    RestAssured.baseURI = "http://" + loadBalancerUrl;
    RestAssured.port = 80;
    System.out.println(">>> Connecting to: " + RestAssured.baseURI + ":" + RestAssured.port);
    waitForServiceReady();
  }

This method orchestrates the connection to teh AWS environment. It creates a CloudFormation client configured for the EU-WEST-3 region where the infrastructure is deployed. Then it queries the deployed CloudFormation stack to retrieve the ALB DNS name, eliminating hardcoded URLs and ensuring tests always connect to the correct deployed instance. The RESTassured client is configured with the dynamically discovered ALB URL and the standard HTTP port (80). The remaining is very similar to what we did in CustomerResourceTest and CustomerResourceIT. The method waitForServiceReady() is, however, new and ensure the the ECS service is fully operational before running the tests, preventing this way false failures due to deployment timing.

To run the E2E tests execute the following Maven command:

$ cd aws-cdk-quarkus
$ mvn -Pe2e clean verify

The workflow is as follows:

1. The module’s pom.xml file uses the exec-maven-plugin to run, in the Maven’s pre-integration-test phase, the command cdk synth. This command creates the associated CloudFormation template in the directory cdk.out.
2. Then the same exec-maven-plugin runs, in the same Maven’s pre-integration-test phase, the script deploy-ecr.sh which automates the complete container deployment workflow.
3. This script creates the ECR (Elastic Container Repository) repository if it doesn’t exist, using environment variables for dynamic naming and region configuration.
4. Then it authenticates with ECR, retags the local Docker image with the ECR registry URL, and pushes it to the remote repository.
5. If the stack already exists, due to a previous execution, then it is updated, otherwise the complete infrastructure is created from scratch.

Here is the script:

#!/bin/bash
registry=$CDK_DEFAULT_ACCOUNT.dkr.ecr.$CDK_DEFAULT_REGION.amazonaws.com
echo ">>> Creating ECR registry $registry"
aws ecr create-repository --repository-name $CONTAINER_IMAGE_GROUP/$CONTAINER_IMAGE_NAME  --region $CDK_DEFAULT_REGION 2>/dev/null || echo "### Repository already exists"
echo ">>> Logging into ECR..."
aws ecr get-login-password --region $CDK_DEFAULT_REGION | docker login --username AWS --password-stdin $registry
echo ">>> Tagging and pushing existing image..."
docker tag $CONTAINER_IMAGE_GROUP/$CONTAINER_IMAGE_NAME:1.0-SNAPSHOT $registry/$CONTAINER_IMAGE_GROUP/$CONTAINER_IMAGE_NAME:latest
docker push $registry/$CONTAINER_IMAGE_GROUP/$CONTAINER_IMAGE_NAME:latest
echo ">>> Checking if stack exists..."
if aws cloudformation describe-stacks --stack-name QuarkusCustomerManagementStack --region $CDK_DEFAULT_REGION >/dev/null 2>&1; then
  echo ">>> Stack exists - updating ECS service ..."
  CLUSTER_NAME=$(aws cloudformation describe-stack-resources --stack-name QuarkusCustomerManagementStack \
    --query 'StackResources[?ResourceType==`AWS::ECS::Cluster`].PhysicalResourceId' \
    --output text --region $CDK_DEFAULT_REGION)
  if [ -n "$CLUSTER_NAME" ]; then
    echo ">>> Found cluster: $CLUSTER_NAME - updating ECS service..."
    aws ecs update-service \
      --cluster $CLUSTER_NAME \
      --service customer-service \
      --force-new-deployment \
      --region $CDK_DEFAULT_REGION
    echo ">>> Waiting for service update to complete..."
    aws ecs wait services-stable \
      --cluster $CLUSTER_NAME \
      --services customer-service \
      --region $CDK_DEFAULT_REGION
    echo ">>> Service update complete!"
    exit 0
  fi
fi
echo ">>> Deploying full infrastructure..."
cdk deploy --all --require-approval never
echo ">>> Deployment finished !"

Beware that the deployment operation is a long-running process which can take more than 15 minutes. Also, once deployed and running, you’ll be invoiced for the cost of the associated infrastructure.

During the script execution, you can check the progression by running scripts like describe-services.sh, describe-events.sh, describe-stacks.sh, etc., or simply using in the AWS Console to look for possible error messages in the CloudWatch log groups. In order to run scripts you need to:

$ cd aws-cdk-quarkus/customer-service-ecs
$ ./customer-service-ecs-cdk/src/main/resources/scripts/<script-name>

Once the deployed successful and after having exercised your infrastructure, don’t forget to run the delete-stack.sh script, which will remove everything you deployed, avoiding you this way to be invoiced by AWS.

Enjoy !