Consul Service Discovery#

Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure. It’s often used as service discovery backend to register and locate the services composing your system. Consul makes it simple for services to register themselves and to discover other services via a DNS or HTTP interface. External services can be registered as well.

As specified in the Consul documentation, if the host address is not provided, Stork will automatically use the Consul node address for the instance.

This page explains how Stork can use Consul to handle the service discovery and service registration.

Dependency#

First, you need to add the Stork Consul Service Discovery provider:

<dependency>
    <groupId>io.smallrye.stork</groupId>
    <artifactId>stork-service-discovery-consul</artifactId>
    <version>2.7.9</version>
</dependency>

Service discovery configuration#

For each service that should get the service instances from Consul, configure the service discovery type:

stork standalonestork in quarkus

stork.my-service.service-discovery.type=consul

quarkus.stork.my-service.service-discovery.type=consul

Secure communication with Consul#

Stork supports SSL/TLS encryption when connecting to a Consul server. This is useful when Consul is configured with HTTPS or when you need to authenticate using client certificates.

To enable SSL/TLS, set the ssl attribute to true and configure the trust store and optionally the key store:

stork standalonestork in quarkus

stork.my-service.service-discovery.type=consul
stork.my-service.service-discovery.consul-host=consul.example.com
stork.my-service.service-discovery.consul-port=8501
stork.my-service.service-discovery.ssl=true
stork.my-service.service-discovery.trust-store-path=/path/to/truststore.jks
stork.my-service.service-discovery.trust-store-password=changeit
stork.my-service.service-discovery.verify-host=true

quarkus.stork.my-service.service-discovery.type=consul
quarkus.stork.my-service.service-discovery.consul-host=consul.example.com
quarkus.stork.my-service.service-discovery.consul-port=8501
quarkus.stork.my-service.service-discovery.ssl=true
quarkus.stork.my-service.service-discovery.trust-store-path=/path/to/truststore.jks
quarkus.stork.my-service.service-discovery.trust-store-password=changeit
quarkus.stork.my-service.service-discovery.verify-host=true

For mutual TLS (mTLS) authentication, also configure the key store containing the client certificate:

stork standalonestork in quarkus

stork.my-service.service-discovery.key-store-path=/path/to/keystore.jks
stork.my-service.service-discovery.key-store-password=changeit

quarkus.stork.my-service.service-discovery.key-store-path=/path/to/keystore.jks
quarkus.stork.my-service.service-discovery.key-store-password=changeit

ACL Token Authentication#

If your Consul cluster has ACL enabled, you can provide an ACL token for authentication:

stork standalonestork in quarkus

stork.my-service.service-discovery.acl-token=your-consul-acl-token

quarkus.stork.my-service.service-discovery.acl-token=your-consul-acl-token

Consul service discovery is configured with the following parameters:

Attribute	Mandatory	Default Value	Description
`consul-host`	No	`localhost`	The Consul host.
`consul-port`	No	`8500`	The Consul port.
`use-health-checks`	No	`true`	Whether to use health check.
`application`	No		The application name; if not defined Stork service name will be used.
`refresh-period`	No	`5M`	Service discovery cache refresh period.
`secure`	No		whether the connection with the service should be encrypted with TLS.
`ssl`	No	`false`	Whether to enable TLS/SSL when connecting to Consul (default: false)
`trust-store-path`	No	``	Path to the trust store file used to verify the Consul server certificate
`trust-store-password`	No	``	Password of the trust store
`key-store-path`	No	``	Path to the key store file containing the client certificate and private key
`key-store-password`	No	``	Password of the key store
`verify-host`	No	`false`	Whether to enable hostname verification for the Consul TLS connection (default: false)
`acl-token`	No	``	Consul ACL token used for authentication when accessing the Consul API