Table of Contents
This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration and binding to the Spring Environment and other Spring programming model idioms. With a few simple annotations you can quickly enable and configure the common patterns inside your application and build large distributed systems with Zookeeper based components. The patterns provided include Service Discovery and Configuration. Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker (Hystrix) are provided by integration with Spring Cloud Netflix.
Please see the installation documentation for instructions on how to install Zookeeper.
Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Curator(A java library for Zookeeper) provides Service Discovery services via Service Discovery Extension. Spring Cloud Zookeeper leverages this extension for service registration and discovery.
Including a dependency on org.springframework.cloud:spring-cloud-starter-zookeeper-discovery
will enable auto-configuration that will setup Spring Cloud Zookeeper Discovery.
![]() | Note |
---|---|
You still need to include |
When a client registers with Zookeeper, it provides meta-data about itself such as host and port, id and name.
Example Zookeeper client:
@SpringBootApplication @RestController public class Application { @RequestMapping("/") public String home() { return "Hello world"; } public static void main(String[] args) { new SpringApplicationBuilder(Application.class).web(true).run(args); } }
(i.e. utterly normal Spring Boot app). If Zookeeper is located somewhere other than localhost:2181
, the configuration is required to locate the server. Example:
application.yml.
spring: cloud: zookeeper: connect-string: localhost:2181
![]() | Caution |
---|---|
If you use Spring Cloud Zookeeper Config, the above values will need to be placed in |
The default service name, instance id and port, taken from the Environment
, are ${spring.application.name}
, the Spring Context ID and ${server.port}
respectively.
Having spring-cloud-starter-zookeeper-discovery
on the classpath makes the app into both a Zookeeper "service" (i.e. it registers itself) and a "client" (i.e. it can query Zookeeper to locate other services).
If you would like to disable the Zookeeper Discovery Client you can set spring.cloud.zookeeper.discovery.enabled
to false
.
Spring Cloud has support for Feign (a REST client builder) and also Spring RestTemplate
using the logical service names instead of physical URLs.
You can also use the org.springframework.cloud.client.discovery.DiscoveryClient
which provides a simple API for discovery clients that is not specific to Netflix, e.g.
@Autowired private DiscoveryClient discoveryClient; public String serviceUrl() { List<ServiceInstance> list = discoveryClient.getInstances("STORES"); if (list != null && list.size() > 0 ) { return list.get(0).getUri().toString(); } return null; }
Spring Cloud Netflix supplies useful tools that work regardless of which DiscoveryClient
implementation is used. Feign, Turbine, Ribbon and Zuul all work with Spring Cloud Zookeeper.
Spring Cloud Zookeeper implements the ServiceRegistry
interface allowing developers to register arbitrary service in a programmatic way.
The ServiceInstanceRegistration
class offers a builder()
method to create a Registration
object that can be used by the ServiceRegistry
.
@Autowired private ZookeeperServiceRegistry serviceRegistry; public void registerThings() { ZookeeperRegistration registration = ServiceInstanceRegistration.builder() .defaultUriSpec() .address("anyUrl") .port(10) .name("/a/b/c/d/anotherservice") .build(); this.serviceRegistry.register(registration); }
Netflix Eureka supports having instances registered with the server that are OUT_OF_SERVICE
and not returned as active service instances. This is very useful for behaviors such as blue/green deployments. The Curator Service Discovery recipe does not support this behavior. Taking advantage of the flexible payload has let Spring Cloud Zookeeper implement OUT_OF_SERVICE
by updating some specific metadata and then filtering on that metadata in the Ribbon ZookeeperServerList
. The ZookeeperServerList
filters out all non-null instance statuses that do not equal UP
. If the instance status field is empty, it is considered UP
for backwards compatibility. To change the status of an instance POST OUT_OF_SERVICE
to the ServiceRegistry
instance status actuator endpoint.
---- $ echo -n OUT_OF_SERVICE | http POST http://localhost:8081/service-registry/instance-status ----
NOTE: The above example uses the `http` command from https://httpie.org
Spring Cloud Zookeeper gives you a possibility to provide dependencies of your application as properties. As dependencies you can understand other applications that are registered
in Zookeeper and which you would like to call via Feign (a REST client builder)
and also Spring RestTemplate
.
You can also benefit from the Zookeeper Dependency Watchers functionality that lets you control and monitor what is the state of your dependencies and decide what to do with that.
org.springframework.cloud:spring-cloud-starter-zookeeper-discovery
will enable auto-configuration that will setup Spring Cloud Zookeeper Dependencies.spring.cloud.zookeeper.dependencies
section properly set up - check the subsequent section for more details then the feature is activespring.cloud.zookeeper.dependency.enabled
to false (defaults to true
).Let’s take a closer look at an example of dependencies representation:
application.yml.
spring.application.name: yourServiceName spring.cloud.zookeeper: dependencies: newsletter: path: /path/where/newsletter/has/registered/in/zookeeper loadBalancerType: ROUND_ROBIN contentTypeTemplate: application/vnd.newsletter.$version+json version: v1 headers: header1: - value1 header2: - value2 required: false stubs: org.springframework:foo:stubs mailing: path: /path/where/mailing/has/registered/in/zookeeper loadBalancerType: ROUND_ROBIN contentTypeTemplate: application/vnd.mailing.$version+json version: v1 required: true
Let’s now go through each part of the dependency one by one. The root property name is spring.cloud.zookeeper.dependencies
.
Below the root property you have to represent each dependency has by an alias due to the constraints of Ribbon (the application id has to be placed in the URL
thus you can’t pass any complex path like /foo/bar/name). The alias will be the name that you will use instead of serviceId for DiscoveryClient
, Feign
or RestTemplate
.
In the aforementioned examples the aliases are newsletter
and mailing
. Example of Feign usage with newsletter
would be:
@FeignClient("newsletter") public interface NewsletterService { @RequestMapping(method = RequestMethod.GET, value = "/newsletter") String getNewsletters(); }
Represented by path
yaml property.
Path is the path under which the dependency is registered under Zookeeper. Like presented before Ribbon operates on URLs thus this path is not compliant with its requirement. That is why Spring Cloud Zookeeper maps the alias to the proper path.
Represented by loadBalancerType
yaml property.
If you know what kind of load balancing strategy has to be applied when calling this particular dependency then you can provide it in the yaml file and it will be automatically applied. You can choose one of the following load balancing strategies
Represented by contentTypeTemplate
and version
yaml property.
If you version your api via the Content-Type
header then you don’t want to add this header to each of your requests. Also if you want to call a new version of the API you don’t want to
roam around your code to bump up the API version. That’s why you can provide a contentTypeTemplate
with a special $version
placeholder. That placeholder will be filled by the value of the
version
yaml property. Let’s take a look at an example.
Having the following contentTypeTemplate
:
application/vnd.newsletter.$version+json
and the following version
:
v1
Will result in setting up of a Content-Type
header for each request:
application/vnd.newsletter.v1+json
Represented by headers
map in yaml
Sometimes each call to a dependency requires setting up of some default headers. In order not to do that in code you can set them up in the yaml file.
Having the following headers
section:
headers: Accept: - text/html - application/xhtml+xml Cache-Control: - no-cache
Results in adding the Accept
and Cache-Control
headers with appropriate list of values in your HTTP request.
Represented by required
property in yaml
If one of your dependencies is required to be up and running when your application is booting then it’s enough to set up the required: true
property in the yaml file.
If your application can’t localize the required dependency during boot time it will throw an exception and the Spring Context will fail to set up. In other words your application won’t be able to start if the required dependency is not registered in Zookeeper.
You can read more about Spring Cloud Zookeeper Presence Checker in the following sections.
You can provide a colon separated path to the JAR containing stubs of the dependency. Example
stubs: org.springframework:foo:stubs
means that for a particular dependencies can be found under:
org.springframework
foo
stubs
- this is the default valueThis is actually equal to
stubs: org.springframework:foo
since stubs
is the default classifier.
There is a bunch of properties that you can set to enable / disable parts of Zookeeper Dependencies functionalities.
spring.cloud.zookeeper.dependencies
- if you don’t set this property you won’t benefit from Zookeeper Dependenciesspring.cloud.zookeeper.dependency.ribbon.enabled
(enabled by default) - Ribbon requires explicit global configuration or a particular one for a dependency. By turning on this property
runtime load balancing strategy resolution is possible and you can profit from the loadBalancerType
section of the Zookeeper Dependencies. The configuration that needs this property
has an implementation of LoadBalancerClient
that delegates to the ILoadBalancer
presented in the next bulletspring.cloud.zookeeper.dependency.ribbon.loadbalancer
(enabled by default) - thanks to this property the custom ILoadBalancer
knows that the part of the URI passed to Ribbon might
actually be the alias that has to be resolved to a proper path in Zookeeper. Without this property you won’t be able to register applications under nested paths.spring.cloud.zookeeper.dependency.headers.enabled
(enabled by default) - this property registers such a RibbonClient
that automatically will append appropriate headers and content
types with version as presented in the Dependency configuration. Without this setting of those two parameters will not be operational.spring.cloud.zookeeper.dependency.resttemplate.enabled
(enabled by default) - when enabled will modify the request headers of @LoadBalanced
annotated RestTemplate
so that it passes
headers and content type with version set in Dependency configuration. Wihtout this setting of those two parameters will not be operational.The Dependency Watcher mechanism allows you to register listeners to your dependencies. The functionality is in fact an implementation of the Observator
pattern. When a dependency changes
its state (UP or DOWN) then some custom logic can be applied.
Spring Cloud Zookeeper Dependencies functionality needs to be enabled to profit from Dependency Watcher mechanism.
In order to register a listener you have to implement an interface org.springframework.cloud.zookeeper.discovery.watcher.DependencyWatcherListener
and register it as a bean.
The interface gives you one method:
void stateChanged(String dependencyName, DependencyState newState);
If you want to register a listener for a particular dependency then the dependencyName
would be the discriminator for your concrete implementation. newState
will provide you with information
whether your dependency has changed to CONNECTED
or DISCONNECTED
.
Bound with Dependency Watcher is the functionality called Presence Checker. It allows you to provide custom behaviour upon booting of your application to react accordingly to the state of your dependencies.
The default implementation of the abstract org.springframework.cloud.zookeeper.discovery.watcher.presence.DependencyPresenceOnStartupVerifier
class is the
org.springframework.cloud.zookeeper.discovery.watcher.presence.DefaultDependencyPresenceOnStartupVerifier
which works in the following way.
required
and it’s not in Zookeeper then upon booting your application will throw an exception and shutdownrequired
the org.springframework.cloud.zookeeper.discovery.watcher.presence.LogMissingDependencyChecker
will log that application is missing at WARN
levelThe functionality can be overriden since the DefaultDependencyPresenceOnStartupVerifier
is registered only when there is no bean of DependencyPresenceOnStartupVerifier
.
Zookeeper provides a hierarchical namespace that allows clients to store arbitrary data, such as configuration data. Spring Cloud Zookeeper Config is an alternative to the Config Server and Client. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the /config
namespace by default. Multiple PropertySource
instances are created based on the application’s name and the active profiles that mimicks the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:
config/testApp,dev config/testApp config/application,dev config/application
The most specific property source is at the top, with the least specific at the bottom. Properties is the config/application
namespace are applicable to all applications using zookeeper for configuration. Properties in the config/testApp
namespace are only available to the instances of the service named "testApp".
Configuration is currently read on startup of the application. Sending a HTTP POST to /refresh
will cause the configuration to be reloaded. Watching the configuration namespace (which Zookeeper supports) is not currently implemented, but will be a future addition to this project.
Including a dependency on org.springframework.cloud:spring-cloud-starter-zookeeper-config
will enable auto-configuration that will setup Spring Cloud Zookeeper Config.
Zookeeper Config may be customized using the following properties:
bootstrap.yml.
spring: cloud: zookeeper: config: enabled: true root: configuration defaultContext: apps profileSeparator: '::'
enabled
setting this value to "false" disables Zookeeper Configroot
sets the base namespace for configuration valuesdefaultContext
sets the name used by all applicationsprofileSeparator
sets the value of the separator used to separate the profile name in property sources with profilesYou can add authentication information for Zookeeper ACLs by calling the addAuthInfo method of a CuratorFramework bean. One way to accomplish this is by providing your own CuratorFramework bean:
@BoostrapConfiguration public class CustomCuratorFrameworkConfig { @Bean public CuratorFramework curatorFramework() { CuratorFramework curator = new CuratorFramework(); curator.addAuthInfo("digest", "user:password".getBytes()); return curator; } }
Consult the ZookeeperAutoConfiguration class to see how the CuratorFramework bean is configured by default.
Alternatively, you can add your credentials from a class that depends on the existing CuratorFramework bean:
@BoostrapConfiguration public class DefaultCuratorFrameworkConfig { public ZookeeperConfig(CuratorFramework curator) { curator.addAuthInfo("digest", "user:password".getBytes()); } }
This must occur during the boostrapping phase. You can register configuration classes to run
during this phase by annotating them with @BootstrapConfiguration
and including them in a
comma-separated list set as the value of the property
org.springframework.cloud.bootstrap.BootstrapConfiguration
in the file
resources/META-INF/spring.factories
:
resources/META-INF/spring.factories.
org.springframework.cloud.bootstrap.BootstrapConfiguration=\ my.project.CustomCuratorFrameworkConfig,\ my.project.DefaultCuratorFrameworkConfig