Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Dropwizard Consul Bundle

Build Status Maven Central GitHub license Become a Patron

A bundle for using Consul in Dropwizard applications. Features:

  • Integrated client-side load balancer based on Ribbon
  • Dropwizard health check that monitors reachablility of Consul
  • The Dropwizard service is registered as a Consul service with a Consul-side health check querying the Dropwizard health check
  • Ability to resolve configuration properties from Consul's KV store
  • Admin task to toggle Consul's maintenance mode

Dependency Info



Add a ConsulBundle to your Application class.

public void initialize(Bootstrap<MyConfiguration> bootstrap) {
    // ...
    bootstrap.addBundle(new ConsulBundle<MyConfiguration>(getName()) {
        public ConsulFactory getConsulFactory(MyConfiguration configuration) {
            return configuration.getConsulFactory();

The bundle also includes a ConsulSubsitutor to retrieve configuration values from the Consul KV store. You can define settings in your YAML configuration file:

template: ${helloworld/template:-Hello, %s!}
defaultName: ${helloworld/defaultName:-Stranger}

The setting with the path helloworld/template will be looked up in the KV store and will be replaced in the configuration file when the application is started. You can specify a default value after the :-. This currently does not support dynamically updating values in a running Dropwizard application.


For configuring the Consul connection, there is a ConsulFactory:

  # Optional properties
  # endpoint for consul (defaults to localhost:8500)
  endpoint: localhost:8500
  # service port
  servicePort: 8080
  # check interval frequency
  checkInterval: 1 second

Example Application

This bundle includes a modified version of the HelloWorldApplication from Dropwizard's Getting Started documentation.

You can execute this application by first starting Consul on your local machine then running:

mvn clean package
java -jar consul-example/target/consul-example-2.0.7-4-SNAPSHOT.jar server consul-example/hello-world.yml

This will start the application on port 8080 (admin port 8180). This application demonstrations the following Consul integration points:

  • The application is registered as a service with Consul (with the service port set to the applicationConnectors port in the configuration file.
  • The application will lookup any variables in the configuration file from Consul upon startup (it defaults to connecting to a Consul agent running on localhost:8500 for this functionality)
  • The application exposes an additional HTTP endpoint for querying Consul for available healthy services:
curl -X GET localhost:8080/consul/hello-world -i
HTTP/1.1 200 OK
Date: Mon, 25 Jan 2016 03:42:10 GMT
Content-Type: application/json
Vary: Accept-Encoding
Content-Length: 870

        "Node": {
            "Node": "mac",
            "Address": "",
            "Datacenter": "dc1",
            "TaggedAddresses": {
                "wan": "",
                "lan": ""
            "Meta": {
                "consul-network-segment": ""
        "Service": {
            "ID": "test123",
            "Service": "hello-world",
            "EnableTagOverride": false,
            "Tags": [],
            "Address": "",
            "Meta": {
                "scheme": "http"
            "Port": 8080,
            "Weights": {
                "Passing": 1,
                "Warning": 1
        "Checks": [
                "Node": "mac",
                "CheckID": "serfHealth",
                "Name": "Serf Health Status",
                "Status": "passing",
                "Notes": "",
                "Output": "Agent alive and reachable",
                "ServiceID": "",
                "ServiceName": "",
                "ServiceTags": []
                "Node": "mac",
                "CheckID": "service:test123",
                "Name": "Service 'hello-world' check",
                "Status": "passing",
                "Notes": "",
                "Output": "HTTP GET http:\/\/\/healthcheck: 200 OK Output: {\"consul\":{\"healthy\":true},\"deadlocks\":{\"healthy\":true}}",
                "ServiceID": "test123",
                "ServiceName": "hello-world",
                "ServiceTags": []
  • The application will periodically checkin with Consul every second to notify the service check that it is still alive
  • Upon shutdown, the application will deregister itself from Consul


This bundle was inspired by an older bundle (Dropwizard 0.6.2) that Chris Gray created at I also incorporated the configuration provider changes from


Please file bug reports and feature requests in GitHub issues.


Copyright (c) 2020 Smoke Turner, LLC

This library is licensed under the Apache License, Version 2.0.

See or the LICENSE file in this repository for the full license text.