Automatic service registration with SmallRye Stork for Quarkus
previewThis guide explains how to enable automatic registration and deregistration of a Quarkus application using SmallRye Stork and Consul, with minimal or no configuration.
Overview
SmallRye Stork supports service registration backends like Consul and Eureka. Traditionally, developers had to explicitly configure and manually register their service instances using code. With this feature, Quarkus applications can automatically register with a supported registry (e.g., Consul) during startup and deregister during shutdown — without writing boilerplate code.
IMPORTANT: Note that automatic registration is possible only for built-in registrars such as Consul, Eureka, and Static.
If you’re using a custom registrar, registration must still be handled programmatically.
Check the stork-programmatic-custom-registration-quickstart directory example for this use case.
This integration minimizes configuration effort and adheres to Quarkus' philosophy of doing as much as possible at build time.
How it works
When the application starts and the stork-service-registration-consul dependency, besides the quarkus-smallrye-stork, is present:
-
Quarkus performs a build-time check for registration configuration.
-
If valid configuration is detected (or can be inferred), registration metadata is generated.
-
During startup, the application registers itself automatically using the detected or configured IP address and port.
-
During shutdown, the service is automatically deregistered.
The solution is located in the stork-automatic-consul-registration-quickstart directory.
Use cases/configuration options
The registration system uses sensible defaults but also allows for fine-grained control per service.
Case 1: implicit configuration
No configuration required at all:
<dependency>
<groupId>io.smallrye.stork</groupId>
<artifactId>stork-service-registration-consul</artifactId>
</dependency>Quarkus automatically uses:
-
Application name
-
Detected IP address
-
HTTP port
The service is registered and unregistered automatically.
Case 2: minimal explicit configuration
Only override what’s necessary:
quarkus.stork.my-service.service-registrar.ip-address=192.168.0.42No quarkus.stork.my-service.service-registrar.type is needed because there’s only one registrar configuration in application.properties.
Case 3: multiple services registrars
When multiple services are configured, you must specify the quarkus.stork.<service-name>.service-registrar.type:
quarkus.stork.red-service.service-registrar.type=consul
quarkus.stork.red-service.service-registrar.port=8083
quarkus.stork.blue-service.service-registrar.type=consul
quarkus.stork.blue-service.service-registrar.port=8084Case 4: disabling registration
Automatic registration is enabled by default. If you want to disable registration, you can do it per service using the following property:
quarkus.stork.red-service.service-registrar.enabled=falseCase 5: advanced health check configuration
Customize how Consul polls service health:
quarkus.stork.my-service.service-registrar.parameters.health-check-url=/q/health/live
quarkus.stork.my-service.service-registrar.parameters.health-check-interval=10s
quarkus.stork.my-service.service-registrar.parameters.health-check-deregister-after=1mIP detection
By default, Quarkus attempts to determine the IP address using the first available, non-loopback network interface.
If this fails, it falls back to localhost.
Note that in Docker/Kubernetes environments, this detection may result in internal IPs that are not externally reachable. In such cases, it’s recommended to explicitly set the IP and port.
Summary
-
Minimal or zero config to get service registration working
-
Seamless integration with Consul via build-time processing
-
Per-service override support
-
Auto-deregistration on shutdown
-
Easily extendable to support other backends
Configuration reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
Type |
Default |
|
Configures the service discovery type, e.g. "consul". ServiceDiscoveryProvider for the type has to be available Environment variable: Show more |
string |
required |
ServiceDiscovery parameters. Check the documentation of the selected service discovery type for available parameters. Environment variable: Show more |
Map<String,String> |
|
Configures load balancer type, e.g. "round-robin". A LoadBalancerProvider for the type has to be available Environment variable: Show more |
string |
|
Load Balancer parameters. Check the documentation of the selected load balancer type for available parameters Environment variable: Show more |
Map<String,String> |
|
Whether automatic registration and deregistration of service instances is enabled. Environment variable: Show more |
boolean |
|
Configures service registrar type, e.g. "consul". A ServiceRegistrarProvider for the type has to be available Environment variable: Show more |
string |
|
Service Registrar parameters. Check the documentation of the selected registrar type for available parameters Environment variable: Show more |
Map<String,String> |
