jen20 / dw-consul

Tools for integrating consul with dropwizard applications.

dw-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.16</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.