Dropwizard Consul Bundle

🥝 We have now transitioned dropwizard-consul from smoketurner to kiwiproject. It is released to Maven Central. See the releases for more information. 🥝

Introduction

A bundle for using Consul in Dropwizard applications. Features:

Dropwizard health check that monitors the reachability 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

Background

This library was imported from smoketurner/dropwizard-consul, which is now a public archive and is no longer maintained by the original author.

Since we are still using this library in our services, which use Dropwizard and Consul, we decided to import the original repository and continue maintaining it for our own use, and anyone else who might want to use it. We make no guarantees whatsoever about how long we will maintain it, and also plan to make our own changes such as changing the base package name to org.kiwiproject to be consistent with our other libraries.

All other kiwiproject projects are MIT-licensed. However, because the original dropwizard-consul uses the Apache 2.0 license, we are keeping the Apache 2.0 license (otherwise to switch to MIT we would have to gain consent of all contributors, which we do not want to do).

Another thing to note is that we imported this repository from the original, so that it is a "disconnected fork". We did not want a reference to the original repository since it is a public archive and no longer maintained. Thus, while we maintain the history that this is a fork, it is completely disconnected and is now a standalone (normal) repository.

Dependency Info

In a Maven POM, use the following:

<dependencies>

    <dependency>
        <groupId>org.kiwiproject</groupId>
        <artifactId>dropwizard-consul</artifactId>
        <version>[current-version]</version>
    </dependency>

    <!-- additional dependencies... -->

</dependencies>

Use the same group, artifact and version if using other build tools like Gradle, SBT, Grape, etc.

Usage

Add a ConsulFactory to your Configuration class.

public class MyConfiguration extends Configuration {

    @NotNull
    @Valid
    @JsonProperty
    private final ConsulFactory consul = new ConsulFactory();

    public ConsulFactory getConsulFactory() {
        return consul;
    }
}

Add a ConsulBundle to your Application class.

public class MyApplication extends Application<MyConfiguration> {

    @Override
    public void initialize(Bootstrap<MyConfiguration> bootstrap) {
        // Add the bundle
        bootstrap.addBundle(new ConsulBundle<MyConfiguration>(getName()) {
            @Override
            public ConsulFactory getConsulFactory(MyConfiguration configuration) {
                return configuration.getConsulFactory();
            }
        });
    }

    @Override
    public void run(MyConfiguration configuration, Environment environment) {
        // Build a Consul instance
        var consul = configuration.getConsulFactory().build();

        // ...
    }
}

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

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

The setting with the path helloworld/template will be looked up in the Consul 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.

Configuration

For configuring the Consul connection, you can configure the ConsulFactory in your Dropwizard configuration file:

consul:
  # Optional properties
  # endpoint for consul (defaults to localhost:8500)
  endpoint: localhost:8500
  
  # service port
  servicePort: 8080

  # check interval frequency
  checkInterval: 1 second

Migrating from smoketurner/dropwizard-consul

To migrate an existing project from smoketurner/dropwizard-consul, you need to:

Change the group in your build file (i.e., Maven POM, Gradle) from com.smoketurner.dropwizard to org.kiwiproject
Change the base package in your code from com.smoketurner.dropwizard to org.kiwiproject.dropwizard

In a Maven POM, you would change:

<dependency>
    <groupId>com.smoketurner.dropwizard</groupId>
    <artifactId>consul-core</artifactId>
    <version>[version]</version>
</dependency>

<dependency>
    <groupId>org.kiwiproject</groupId>
    <artifactId>dropwizard-consul</artifactId>
    <version>[current-version]</version>
</dependency>

The class names from the original smoketurner/dropwizard-consul library are the same, so for example, importing ConsulBundle changes from:

import com.smoketurner.dropwizard.consul.ConsulBundle;

import org.kiwiproject.dropwizard.consul.ConsulBundle;

If existing code directly uses the consul-client library (which this bundle depends on), that code will need to be updated starting at version 0.8.0, because the base packages were changed from com.orbitz to org.kiwiproject.

Credits

This library comes from the dropwizard-consul library from Smoketurner. The following credits are also retained from the original library.

This bundle was inspired by an older bundle (Dropwizard 0.6.2) that Chris Gray created at https://github.com/chrisgray/dropwizard-consul. I also incorporated the configuration provider changes from https://github.com/remmelt/dropwizard-consul-config-provider

Support

Please file bug reports and feature requests in GitHub issues.

License

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

See http://www.apache.org/licenses/LICENSE-2.0.html or the LICENSE file in this repository for the full license text.

kiwiproject / dropwizard-consul