JarCastingDropwizard Consul Bundle
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
<dependency>
<groupId>com.smoketurner.dropwizard</groupId>
<artifactId>consul-core</artifactId>
<version>2.0.7-1</version>
</dependency>
<dependency>
<groupId>com.smoketurner.dropwizard</groupId>
<artifactId>consul-ribbon</artifactId>
<version>2.0.7-1</version>
</dependency>
Usage
Add a ConsulBundle to your Application class.
@Override
public void initialize(Bootstrap<MyConfiguration> bootstrap) {
// ...
bootstrap.addBundle(new ConsulBundle<MyConfiguration>(getName()) {
@Override
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.
Configuration
For configuring the Consul connection, there is a ConsulFactory:
consul:
# 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:8500for 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": "192.168.1.100",
"Datacenter": "dc1",
"TaggedAddresses": {
"wan": "192.168.1.100",
"lan": "192.168.1.100"
},
"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:\/\/127.0.0.1:8180\/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
Credits
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
Copyright (c) 2020 Smoke Turner, LLC
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.
