Quarkus - Reading properties from Consul

This guide explains how your Quarkus application can read configuration properties at runtime from Consul.

Prerequisites

To complete this guide, you need:

• less than 15 minutes

• an IDE

• JDK 1.8+ installed with JAVA_HOME configured appropriately

• Apache Maven 3.6.2+

Solution

We recommend that you follow the instructions in the next sections and create the application step by step.

Introduction

Consul is a versatile system which among other things, provides a distributed Key-Value store that is used in many architectures as a source of configuration for services. This Key-Value store is what the quarkus-consul-config extension interacts with in order to allow Quarkus applications to read runtime configuration properties from Consul.

Starting Consul

There are various ways to start Consul that vary in complexity, but for the purposes of this guide, we elect to start a single Consul server with no persistence via Docker, like so:

docker run --rm --name consul -p 8500:8500 -p 8501:8501 consul:1.7 agent -dev -ui -client=0.0.0.0 -bind=0.0.0.0 --https-port=8501

Please consult the documentation to learn more about the various Consul installation options.

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:1.7.6.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=consul-config-quickstart \
    -DclassName="org.acme.consul.config.GreetingResource" \
    -Dpath="/greeting" \
    -Dextensions="consul-config"
cd consul-config-quickstart

This command generates a Maven project with a REST endpoint and imports the consul-config extension.

If you already have your Quarkus project configured, you can add the consul-config extension to your project by running the following command in your project base directory:

./mvnw quarkus:add-extension -Dextensions="consul-config"

This will add the following to your pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-consul-config</artifactId>
</dependency>

GreetingController

The Quarkus Maven plugin automatically generated a GreetingResource JAX-RS resource in the src/main/java/org/acme/consul/config/client/GreetingResource.java file that looks like:

package org.acme.consul.config.client;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
@Path("/hello")
public class GreetingResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "hello";
    }
}

As we want to use configuration properties obtained from the Config Server, we will update the GreetingResource to inject the message property. The updated code will look like this:

package org.acme.consul.config.client;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.eclipse.microprofile.config.inject.ConfigProperty;
@Path("/hello")
public class GreetingResource {
    @ConfigProperty(name = "message", defaultValue="Hello from default")
    String message;
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return message;
    }
}

Configuring the application

Quarkus provides various configuration knobs under the quarkus.consul-config root. For the purposes of this guide, our Quarkus application is going to be configured in application.properties as follows:

# use the same name as the application name that was configured when standing up the Config Server
quarkus.application.name=consul-test
# enable retrieval of configuration from Consul - this is off by default
quarkus.consul-config.enabled=true
# this is a key in Consul's KV store that the Quarkus application will read and try to extract properties from
quarkus.consul-config.properties-value-keys=config/${quarkus.application.name}

Add Configuration to Consul

For the previous application configuration to work, we need to add a config/consul-test key under Consul’s Key Value store. The value of this key will essentially be a properties “file” containing the application configuration. In this case we want to add the following data to the config/consul-test key:

greeting.message=Hello from Consul

When adding this configuration from the UI, Consul will automatically convert the data into the necessary base64 encoding. If you instead add the configuration via the Consul’s REST API, make sure to first encode the previous data into base64.

Package and run the application

Run the application with: ./mvnw compile quarkus:dev. Open your browser to http://localhost:8080/greeting.

The result should be: Hello from Consul as it is the value obtained from the Consul Key Value store.

Run the application as a native executable

You can of course create a native image using the instructions of the Building a native executable guide.

Configuration Reference