JarCastingdw-consul
Tools for integrating consul with dropwizard applications.
Current implementation allows quick configuration and setup of a managed Consul client, registration of multiple service endpoints hooked into the dropwizard app life cycle, and a dropwizard-friendly load balancer using consul healthClient for service discovery.
Motivation
Provide a shared, consistent method to make use of consul within dropwizard applications for service registration and discovery.
Installation
Maven
<dependency>
<groupId>com.boundary.dropwizard.consul</groupId>
<artifactId>registration</artifactId>
<version>0.19</version>
</dependency>
Current implementation allows quick configuration and setup of a managed Consul client, registration of multiple service endpoints hooked into the dropwizard app life cycle, and a dropwizard-friendly load balancer using consul healthClient for service discovery.
Usage
These examples build upon each other - use of either loadbalancer or registration modules requires the client module.
For a more complete example, take a look at the example-app, which demonstrates service registration and client usage.
Client example
@Valid
@NotNull
@JsonProperty("consul")
private ConsulClientConfig consul = new ConsulClientConfig();
public ConsulClientConfig getConsul() {
return consul;
}
In your application class:
// get a consul-client object. see https://github.com/OrbitzWorldwide/consul-client for more info
Consul consul = configuration.getConsul().build();
Configuration:
consul:
agent: localhost:8500
Registration example:
In your configuration class:
@Valid
@NotNull
@JsonProperty("consul")
private ConsulClientConfig consul = new ConsulClientConfig();
public ConsulClientConfig getConsul() {
return consul;
}
@Valid
@NotNull
@JsonProperty("registration")
private ConsulRegistrationConfig registration = new ConsulRegistrationConfig();
public ConsulRegistrationConfig getRegistration() {
return registration;
}
In your application class:
Consul consul = configuration.getConsul().build();
// register your configured application services in consul
configuration.getRegistration().register(environment, consul.agentClient());
Configuration:
registration:
serviceName: serviceName
tagSeparator: _
services:
- serviceTag: service
port: {servicePort}
healthCheckUrl: http://localhost:{adminServicePort}/healthcheck
- serviceTag: admin
port: {adminServicePort}
Load balancer example
In your configuration class:
@Valid
@NotNull
@JsonProperty("consul")
private ConsulClientConfig consul = new ConsulClientConfig();
public ConsulClientConfig getConsul() {
return consul;
}
@JsonProperty
@Valid
@NotNull
private LBFactory loadBalancer;
public LBFactory getLoadBalancer() {
return loadBalancer;
}
In your application class:
Consul consul = configuration.getConsul().build(environment);
// create typed ClientFactory instance
// that will create a client of your choosing
// based on a ServiceHealth (https://github.com/OrbitzWorldwide/consul-client/blob/master/src/main/java/com/orbitz/consul/model/health/ServiceHealth.java) instance
final ClientFactory<CLIENT>> clientFactory = // call your clientFactory code
final LoadBalancer<CLIENT> lb = configuration.getLoadBalancer().build(env, consul.healthClient(), clientFactory);
// now call lb.getClient() each time you need to make a request to the target service
Configuration:
loadBalancer:
type: round-robin
serviceName: {targetServicName}
serviceTag: {optional service tag}
all config options
consul:
agent: localhost:8500
registration:
serviceName: serviceName
tagSeparator: _
services:
- serviceTag: service
port: {servicePort}
healthCheckUrl: http://localhost:11601/healthcheck
- serviceTag: admin
port: {adminServicePort}
- serviceTag: other
port: {otherServicePort}
loadBalancer:
type: round-robin
serviceName: {targetServicName}
serviceTag: {optional service tag}
watchSeconds: 30
registration format
Using the registration module, here's an example of you you might get under the suggested config, registering a service named 'sasquatch':
[
{
"Node": "premium.local",
"Address": "172.16.9.138",
"ServiceID": "sasquatch_jmx",
"ServiceName": "sasquatch",
"ServiceTags": [
"jmx"
],
"ServiceAddress": "",
"ServicePort": 11502
},
{
"Node": "premium.local",
"Address": "172.16.9.138",
"ServiceID": "sasquatch_service",
"ServiceName": "sasquatch",
"ServiceTags": [
"service"
],
"ServiceAddress": "",
"ServicePort": 11500
},
{
"Node": "premium.local",
"Address": "172.16.9.138",
"ServiceID": "sasquatch_admin",
"ServiceName": "sasquatch",
"ServiceTags": [
"admin"
],
"ServiceAddress": "",
"ServicePort": 11501
}
]
You can query these healthy nodes based on tags as curl 127.0.0.1:8500/v1/health/service/sasquatch?tag=jmx. See the consul api docs for more info.
Tests
To run the tests, clone the repo and run mvn test from the parent directory.
LICENSE
© Copyright 2015-2016 BMC SOFTWARE, INC.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
