Antora migration (#323)

* Updates maven to 3.9.0

* Migrate Structure

* Insert explicit ids for headers

* Remove unnecessary asciidoc attributes

* Copy default antora files

* Fix indentation for all pages

* Split files

* Generate a default navigation

* Remove includes

* Fix cross references

* Enable Section Summary TOC for small pages

* More antora customization

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,10 @@
+* xref:index.adoc[]
+* xref:quickstart.adoc[]
+* xref:install.adoc[]
+* xref:discovery.adoc[]
+* xref:other-componentes.adoc[]
+* xref:service-registry.adoc[]
+* xref:dependencies.adoc[]
+* xref:dependency-watcher.adoc[]
+* xref:config.adoc[]
+* xref:appendix.adoc[]

docs/modules/ROOT/pages/_attributes.adoc

@@ -0,0 +1,14 @@
+
+:doctype: book
+:idprefix:
+:idseparator: -
+:tabsize: 4
+:numbered:
+:sectanchors:
+:sectnums:
+:icons: font
+:hide-uri-scheme:
+:docinfo: shared,private
+
+:sc-ext: java
+:project-full-name: Spring Cloud Zookeeper

docs/modules/ROOT/pages/appendix.adoc

@@ -0,0 +1,14 @@
+:numbered!:
+[appendix]
+[[common-application-properties]]
+= Common application properties
+:page-section-summary-toc: 1
+
+
+Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
+This appendix provides a list of common Spring Cloud Zookeeper properties and references to the underlying classes that consume them.
+
+NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
+Also, you can define your own properties.
+
+include::partial$_configprops.adoc[]

docs/modules/ROOT/pages/config.adoc

@@ -0,0 +1,143 @@
+[[spring-cloud-zookeeper-config]]
+= Distributed Configuration with Zookeeper
+
+Zookeeper provides a
+https://zookeeper.apache.org/doc/current/zookeeperOver.html#sc_dataModelNameSpace[hierarchical namespace]
+that lets clients store arbitrary data, such as configuration data. Spring Cloud Zookeeper
+Config is an alternative to the
+https://github.com/spring-cloud/spring-cloud-config[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, to mimic the Spring Cloud Config order of resolving properties. For example, an
+application with a name of `testApp` and with the `dev` profile has the following property
+sources created for it:
+
+* `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 in the `config/application` namespace apply to all applications that use
+zookeeper for configuration. Properties in the `config/testApp` namespace are available
+only to the instances of the service named `testApp`.
+
+Configuration is currently read on startup of the application. Sending a HTTP `POST`
+request to `/refresh` causes the configuration to be reloaded. Watching the configuration
+namespace (which Zookeeper supports) is not currently implemented.
+
+[[activating]]
+== Activating
+
+Including a dependency on
+`org.springframework.cloud:spring-cloud-starter-zookeeper-config` enables
+autoconfiguration that sets up Spring Cloud Zookeeper Config.
+
+CAUTION: When working with version 3.4 of Zookeeper you need to change
+the way you include the dependency as described xref:install.adoc[here].
+
+[[config-data-import]]
+== Spring Boot Config Data Import
+
+Spring Boot 2.4 introduced a new way to import configuration data via the `spring.config.import` property. This is now the default way to get configuration from Zookeeper.
+
+To optionally connect to Zookeeper for configuration set the following in application.properties:
+
+.application.properties
+[source,properties]
+----
+spring.config.import=optional:zookeeper:
+----
+
+This will connect to Zookeeper at the default location of "localhost:2181". Removing the `optional:` prefix will cause Zookeeper Config to fail if it is unable to connect to Zookeeper. To change the connection properties of Zookeeper Config either set `spring.cloud.zookeeper.connect-string` or add the connect string to the `spring.config.import` statement such as, `spring.config.import=optional:zookeeper:myhost:2818`. The location in the import property has precedence over the `connect-string` property.
+
+Zookeeper Config will try to load values from four automatic contexts based on `spring.cloud.zookeeper.config.name` (which defaults to the value of the `spring.application.name` property) and `spring.cloud.zookeeper.config.default-context` (which defaults to `application`). If you want to specify the contexts rather than using the computed ones, you can add that information to the `spring.config.import` statement.
+
+.application.properties
+[source,properties]
+----
+spring.config.import=optional:zookeeper:myhost:2181/contextone;/context/two
+----
+
+This will optionally load configuration only from `/contextone` and `/context/two`.
+
+NOTE: A `bootstrap` file (properties or yaml) is *not* needed for the Spring Boot Config Data method of import via `spring.config.import`.
+
+[[customizing]]
+== Customizing
+
+Zookeeper Config may be customized by setting the following properties:
+
+[source,yml,indent=0]
+----
+spring:
+  cloud:
+    zookeeper:
+      config:
+        enabled: true
+        root: configuration
+        defaultContext: apps
+        profileSeparator: '::'
+----
+
+* `enabled`: Setting this value to `false` disables Zookeeper Config.
+* `root`: Sets the base namespace for configuration values.
+* `defaultContext`: Sets the name used by all applications.
+* `profileSeparator`: Sets the value of the separator used to separate the profile name in
+property sources with profiles.
+
+CAUTION: If you have set `spring.cloud.bootstrap.enabled=true` or `spring.config.use-legacy-processing=true`, or included `spring-cloud-starter-bootstrap`, then the above values will need to be placed in `bootstrap.yml` instead of `application.yml`.
+
+[[access-control-lists-acls]]
+== Access Control Lists (ACLs)
+
+You can add authentication information for Zookeeper ACLs by calling the `addAuthInfo`
+method of a `CuratorFramework` bean. One way to accomplish this is to provide your own
+`CuratorFramework` bean, as shown in the following example:
+
+[source,java,indent=0]
+----
+@BoostrapConfiguration
+public class CustomCuratorFrameworkConfig {
+
+  @Bean
+  public CuratorFramework curatorFramework() {
+    CuratorFramework curator = new CuratorFramework();
+    curator.addAuthInfo("digest", "user:password".getBytes());
+    return curator;
+  }
+
+}
+----
+Consult
+https://github.com/spring-cloud/spring-cloud-zookeeper/blob/main/spring-cloud-zookeeper-core/src/main/java/org/springframework/cloud/zookeeper/ZookeeperAutoConfiguration.java[the ZookeeperAutoConfiguration class]
+to see how the `CuratorFramework` bean's default configuration.
+
+Alternatively, you can add your credentials from a class that depends on the existing
+`CuratorFramework` bean, as shown in the following example:
+
+[source,java,indent=0]
+----
+@BoostrapConfiguration
+public class DefaultCuratorFrameworkConfig {
+
+  public ZookeeperConfig(CuratorFramework curator) {
+    curator.addAuthInfo("digest", "user:password".getBytes());
+  }
+
+}
+----
+
+The creation of this bean 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 that you set as the
+value of the `org.springframework.cloud.bootstrap.BootstrapConfiguration` property in the
+`resources/META-INF/spring.factories` file, as shown in the following example:
+
+.resources/META-INF/spring.factories
+----
+org.springframework.cloud.bootstrap.BootstrapConfiguration=\
+my.project.CustomCuratorFrameworkConfig,\
+my.project.DefaultCuratorFrameworkConfig
+----

docs/modules/ROOT/pages/configprops.adoc

@@ -0,0 +1,6 @@
+[[configuration-properties]]
+= Configuration Properties
+
+Below you can find a list of configuration properties.
+
+include::partial$_configprops.adoc[]

docs/modules/ROOT/pages/dependencies.adoc

@@ -0,0 +1,205 @@
+[[spring-cloud-zookeeper-dependencies]]
+= Zookeeper Dependencies
+
+The following topics cover how to work with Spring Cloud Zookeeper dependencies:
+
+* xref:dependencies.adoc#spring-cloud-zookeeper-dependencies-using[Using the Zookeeper Dependencies]
+* xref:dependencies.adoc#spring-cloud-zookeeper-dependencies-activating[Activating Zookeeper Dependencies]
+* xref:dependencies.adoc#spring-cloud-zookeeper-dependencies-setting-up[Setting up Zookeeper Dependencies]
+* xref:dependencies.adoc#spring-cloud-zookeeper-dependencies-configuring[Configuring Spring Cloud Zookeeper Dependencies]
+
+[[spring-cloud-zookeeper-dependencies-using]]
+== Using the Zookeeper Dependencies
+
+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 through
+https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/[OpenFeign]
+(a REST client builder), `RestTemplate` and `WebClient` via https://docs.spring.io/spring-cloud-commons/reference/spring-cloud-commons/loadbalancer.html#spring-cloud-loadbalancer-integrations[Spring Cloud Loadbalancer].
+
+You can also use the Zookeeper Dependency Watchers functionality to control and monitor
+the state of your dependencies.
+
+[[spring-cloud-zookeeper-dependencies-activating]]
+== Activating Zookeeper Dependencies
+
+Including a dependency on
+`org.springframework.cloud:spring-cloud-starter-zookeeper-discovery` enables
+autoconfiguration that sets up Spring Cloud Zookeeper Dependencies. Even if you provide
+the dependencies in your properties, you can turn off the dependencies. To do so, set the
+`spring.cloud.zookeeper.dependency.enabled` property to false (it defaults to `true`).
+
+[[spring-cloud-zookeeper-dependencies-setting-up]]
+== Setting up Zookeeper Dependencies
+
+Consider the following example of dependency representation:
+
+[source,yml,indent=0]
+.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
+----
+
+The next few sections go through each part of the dependency one by one. The root property
+name is `spring.cloud.zookeeper.dependencies`.
+
+[[spring-cloud-zookeeper-dependencies-setting-up-aliases]]
+=== Aliases
+
+Below the root property you have to represent each dependency as an alias.
+This is due to the constraints of Spring Cloud LoadBalancer, which requires that the application ID be placed in the URL.
+Consequently, you cannot pass any complex path, suchas  `/myApp/myRoute/name`).
+The alias is the name you use instead of the `serviceId` for `DiscoveryClient`, `Feign`, or
+`RestTemplate`.
+
+In the previous examples, the aliases are `newsletter` and `mailing`.
+The following example shows Feign usage with a `newsletter` alias:
+
+[source,java,indent=0]
+----
+@FeignClient("newsletter")
+public interface NewsletterService {
+        @RequestMapping(method = RequestMethod.GET, value = "/newsletter")
+        String getNewsletters();
+}
+----
+
+[[path]]
+=== Path
+
+The path is represented by the `path` YAML property and is the path under which the dependency is registered under Zookeeper.
+As described in the
+xref:dependencies.adoc#spring-cloud-zookeeper-dependencies-setting-up-aliases[previous section], Spring Cloud LoadBalancer operates on URLs.
+As a result, this path is not compliant with its requirement.
+That is why Spring Cloud Zookeeper maps the alias to the proper path.
+
+[[load-balancer-type]]
+=== Load Balancer Type
+
+The load balancer type is represented by `loadBalancerType` YAML property.
+
+If you know what kind of load-balancing strategy has to be applied when calling this particular dependency, you can provide it in the YAML file, and it is automatically applied.
+You can choose one of the following load balancing strategies:
+
+* STICKY: Once chosen, the instance is always called.
+* RANDOM: Picks an instance randomly.
+* ROUND_ROBIN: Iterates over instances over and over again.
+
+[[content-type-template-and-version]]
+=== `Content-Type` Template and Version
+
+The `Content-Type` template and version are represented by the `contentTypeTemplate` and
+`version` YAML properties.
+
+If you version your API in the `Content-Type` header, you do not want to add this header
+to each of your requests. Also, if you want to call a new version of the API, you do not
+want to roam around your code to bump up the API version. That is why you can provide a
+`contentTypeTemplate` with a special `$version` placeholder. That placeholder will be filled by the value of the
+`version` YAML property. Consider the following example of a `contentTypeTemplate`:
+
+----
+application/vnd.newsletter.$version+json
+----
+
+Further consider the following `version`:
+
+----
+v1
+----
+
+The combination of `contentTypeTemplate` and version results in the creation of a
+`Content-Type` header for each request, as follows:
+
+----
+application/vnd.newsletter.v1+json
+----
+
+[[default-headers]]
+=== Default Headers
+
+Default headers are represented by the `headers` map in YAML.
+
+Sometimes, each call to a dependency requires setting up of some default headers. To not
+do that in code, you can set them up in the YAML file, as shown in the following example
+`headers` section:
+
+[source,yml,indent=0]
+----
+headers:
+    Accept:
+        - text/html
+        - application/xhtml+xml
+    Cache-Control:
+        - no-cache
+----
+
+That `headers` section results in adding the `Accept` and `Cache-Control` headers with
+appropriate list of values in your HTTP request.
+
+[[required-dependencies]]
+=== Required Dependencies
+
+Required dependencies are represented by `required` property in YAML.
+
+If one of your dependencies is required to be up when your application boots, you can set
+the `required: true` property in the YAML file.
+
+If your application cannot localize the required dependency during boot time, it throws an
+exception, and the Spring Context fails to set up. In other words, your application cannot
+start if the required dependency is not registered in Zookeeper.
+
+You can read more about Spring Cloud Zookeeper Presence Checker
+xref:dependency-watcher.adoc#spring-cloud-zookeeper-dependency-watcher-presence-checker[later in this document].
+
+[[stubs]]
+=== Stubs
+
+You can provide a colon-separated path to the JAR containing stubs of the dependency, as
+shown in the following example:
+
+`stubs: org.springframework:myApp:stubs`
+
+where:
+
+* `org.springframework` is the `groupId`.
+* `myApp` is the `artifactId`.
+* `stubs` is the classifier. (Note that `stubs` is the default value.)
+
+Because `stubs` is the default classifier, the preceding example is equal to the following
+example:
+
+`stubs: org.springframework:myApp`
+
+[[spring-cloud-zookeeper-dependencies-configuring]]
+== Configuring Spring Cloud Zookeeper Dependencies
+
+You can set the following properties to enable or disable parts of Zookeeper Dependencies functionalities:
+
+* `spring.cloud.zookeeper.dependencies`: If you do not set this property, you cannot use Zookeeper Dependencies.
+* `spring.cloud.zookeeper.dependency.loadbalancer.enabled` (enabled by default): Turns on Zookeeper-specific custom load-balancing strategies, including `ZookeeperServiceInstanceListSupplier` and dependency-based load-balanced `RestTemplate` setup.
+* `spring.cloud.zookeeper.dependency.headers.enabled` (enabled by default): This property registers a `FeignBlockingLoadBalancerClient` that automatically appends appropriate headers and content types with their versions, as presented in the Dependency configuration.
+Without this setting, those two parameters do not work.
+* `spring.cloud.zookeeper.dependency.resttemplate.enabled` (enabled by default): When enabled, this property modifies the request headers of a `@LoadBalanced`-annotated
+`RestTemplate` such that it passes headers and content type with the version set in dependency configuration.
+Without this setting, those two parameters do not work.
+

docs/modules/ROOT/pages/dependency-watcher.adoc

@@ -0,0 +1,53 @@
+[[spring-cloud-zookeeper-dependency-watcher]]
+= Spring Cloud Zookeeper Dependency Watcher
+
+The Dependency Watcher mechanism lets you register listeners to your dependencies. The
+functionality is, in fact, an implementation of the `Observator` pattern. When a
+dependency changes, its state (to either UP or DOWN), some custom logic can be applied.
+
+[[activating]]
+== Activating
+
+Spring Cloud Zookeeper Dependencies functionality needs to be enabled for you to use the
+Dependency Watcher mechanism.
+// TODO: How can the reader do that?
+
+[[registering-a-listener]]
+== Registering a Listener
+
+To register a listener, you must implement an interface called
+`org.springframework.cloud.zookeeper.discovery.watcher.DependencyWatcherListener` and
+register it as a bean. The interface gives you one method:
+
+[source,java,indent=0]
+----
+void stateChanged(String dependencyName, DependencyState newState);
+----
+
+If you want to register a listener for a particular dependency, the `dependencyName` would
+be the discriminator for your concrete implementation. `newState` provides you with
+information about whether your dependency has changed to `CONNECTED` or `DISCONNECTED`.
+
+[[spring-cloud-zookeeper-dependency-watcher-presence-checker]]
+== Using the Presence Checker
+
+Bound with the Dependency Watcher is the functionality called Presence Checker. It lets
+you provide custom behavior when your application boots, to react according 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.
+
+. If the dependency is marked us `required` and is not in Zookeeper, when your application
+boots, it throws an exception and shuts down.
+. If the dependency is not `required`, the
+`org.springframework.cloud.zookeeper.discovery.watcher.presence.LogMissingDependencyChecker`
+logs that the dependency is missing at the `WARN` level.
+
+Because the `DefaultDependencyPresenceOnStartupVerifier` is registered only when there is
+no bean of type `DependencyPresenceOnStartupVerifier`, this functionality can be
+overridden.
+

docs/modules/ROOT/pages/discovery.adoc

@@ -0,0 +1,102 @@
+[[spring-cloud-zookeeper-discovery]]
+= Service Discovery with 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 difficult to do and can be
+brittle. https://curator.apache.org[Curator](A Java library for Zookeeper) provides Service
+Discovery through a https://curator.apache.org/curator-x-discovery/[Service Discovery
+Extension]. Spring Cloud Zookeeper uses this extension for service registration and
+discovery.
+
+[[activating]]
+== Activating
+
+Including a dependency on
+`org.springframework.cloud:spring-cloud-starter-zookeeper-discovery` enables
+autoconfiguration that sets up Spring Cloud Zookeeper Discovery.
+
+NOTE: For web functionality, you still need to include
+`org.springframework.boot:spring-boot-starter-web`.
+
+CAUTION: When working with version 3.4 of Zookeeper you need to change
+the way you include the dependency as described xref:install.adoc[here].
+
+[[registering-with-zookeeper]]
+== Registering with Zookeeper
+
+When a client registers with Zookeeper, it provides metadata (such as host and port, ID,
+and name) about itself.
+
+The following example shows a Zookeeper client:
+
+[source,java,indent=0]
+----
+@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);
+    }
+
+}
+----
+
+NOTE: The preceding example is a normal Spring Boot application.
+
+If Zookeeper is located somewhere other than `localhost:2181`, the configuration must
+provide the location of the server, as shown in the following example:
+
+[source,yml,indent=0]
+.application.yml
+----
+spring:
+  cloud:
+    zookeeper:
+      connect-string: localhost:2181
+----
+
+CAUTION: If you use xref:config.adoc[Spring Cloud Zookeeper Config], the
+values shown in the preceding example need to be in `bootstrap.yml` instead of
+`application.yml`.
+
+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`" (that is, it registers itself) and a "`client`" (that is, 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`.
+
+[[using-the-discoveryclient]]
+== Using the DiscoveryClient
+
+Spring Cloud has support for
+https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/[OpenFeign]
+(a REST client builder), `RestTemplate` and `WebClient` via https://docs.spring.io/spring-cloud-commons/reference/spring-cloud-commons/loadbalancer.html#spring-cloud-loadbalancer-integrations[Spring Cloud Loadbalancer], using 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, as shown in
+the following example:
+
+[source,java,indent=0]
+----
+@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;
+}
+----
+

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1 @@
+include::intro.adoc[]

docs/modules/ROOT/pages/install.adoc

@@ -0,0 +1,8 @@
+[[spring-cloud-zookeeper-install]]
+= Working with Zookeeper
+
+See the https://zookeeper.apache.org/doc/current/zookeeperStarted.html[installation
+documentation] for instructions on how to install Zookeeper.
+
+// TODO: describe Testcontainers and zk
+

docs/modules/ROOT/pages/intro.adoc

@@ -0,0 +1,9 @@
+[[spring-cloud-gateway-intro]]
+= Introduction
+
+This project provides Zookeeper integrations for Spring Boot applications through
+autoconfiguration and binding to the Spring Environment and other Spring programming model
+idioms. With a few annotations, you can quickly enable and configure the common patterns
+inside your application and build large distributed systems with Zookeeper based
+components. The provided patterns include Service Discovery and Configuration. The project
+also provides client-side load-balancing via integration with Spring Cloud LoadBalancer.

docs/modules/ROOT/pages/other-componentes.adoc

@@ -0,0 +1,16 @@
+[[spring-cloud-zookeeper-other-componentes]]
+= Using Spring Cloud Zookeeper with Spring Cloud Components
+:page-section-summary-toc: 1
+
+Feign, Spring Cloud Gateway and Spring Cloud LoadBalancer all work with Spring Cloud Zookeeper.
+
+[[spring-cloud-loadbalancer-with-zookeeper]]
+== Spring Cloud LoadBalancer with Zookeeper
+
+Spring Cloud Zookeeper provides an implementation of Spring Cloud LoadBalancer `ServiceInstanceListSupplier`.
+When you use the  `spring-cloud-starter-zookeeper-discovery`, Spring Cloud LoadBalancer is autoconfigured to use the
+`ZookeeperServiceInstanceListSupplier` by default.
+
+TIP: If you were previously using the StickyRule in Zookeeper, its replacement in the current stack
+is the `SameInstancePreferenceServiceInstanceListSupplier` in SC LoadBalancer. You can read on how to set it up in the https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer[Spring Cloud Commons documentation].
+

docs/modules/ROOT/pages/quickstart.adoc

@@ -0,0 +1,237 @@
+[[quick-start]]
+= Quick Start
+
+This quick start walks through using Spring Cloud Zookeeper for Service Discovery and Distributed Configuration.
+
+First, run Zookeeper on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Zookeeper.
+
+[[discovery-client-usage]]
+== Discovery Client Usage
+
+To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-zookeeper-core` and `spring-cloud-zookeeper-discovery`.
+The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-zookeeper-discovery`.
+We recommend using dependency management and `spring-boot-starter-parent`.
+The following example shows a typical Maven configuration:
+
+[source,xml,indent=0]
+.pom.xml
+----
+<project>
+<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>{spring-boot-version}</version>
+    <relativePath/> <!-- lookup parent from repository -->
+  </parent>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.cloud</groupId>
+      <artifactId>spring-cloud-starter-zookeeper-discovery</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-dependencies</artifactId>
+        <version>${spring-cloud.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+The following example shows a typical Gradle setup:
+
+[source,groovy,indent=0]
+.build.gradle
+----
+plugins {
+  id 'org.springframework.boot' version ${spring-boot-version}
+  id 'io.spring.dependency-management' version ${spring-dependency-management-version}
+  id 'java'
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-discovery'
+  testImplementation 'org.springframework.boot:spring-boot-starter-test'
+}
+dependencyManagement {
+  imports {
+    mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+  }
+}
+----
+
+WARNING: Depending on the version you are using, you might need to adjust Apache Zookeeper version used in your project.
+You can read more about it in the xref:install.adoc[Install Zookeeper section].
+
+Now you can create a standard Spring Boot application, such as the following HTTP server:
+
+----
+@SpringBootApplication
+@RestController
+public class Application {
+
+    @GetMapping("/")
+    public String home() {
+        return "Hello World!";
+    }
+
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+
+}
+----
+
+When this HTTP server runs, it connects to Zookeeper, which runs on the default local port (2181).
+To modify the startup behavior, you can change the location of Zookeeper by using `application.properties`, as shown in the following example:
+
+----
+spring:
+  cloud:
+    zookeeper:
+      connect-string: localhost:2181
+----
+
+You can now use `DiscoveryClient`, `@LoadBalanced RestTemplate`, or `@LoadBalanced WebClient.Builder` to retrieve services and instances data from Zookeeper, as shown in the following example:
+
+[source,java,indent=0]
+----
+@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;
+}
+----
+
+[[distributed-configuration-usage]]
+== Distributed Configuration Usage
+
+To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-zookeeper-core` and `spring-cloud-zookeeper-config`.
+The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-zookeeper-config`.
+We recommend using dependency management and `spring-boot-starter-parent`.
+The following example shows a typical Maven configuration:
+
+[source,xml,indent=0]
+.pom.xml
+----
+<project>
+<parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>{spring-boot-version}</version>
+    <relativePath/> <!-- lookup parent from repository -->
+  </parent>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.cloud</groupId>
+      <artifactId>spring-cloud-starter-zookeeper-config</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>org.springframework.cloud</groupId>
+        <artifactId>spring-cloud-dependencies</artifactId>
+        <version>${spring-cloud.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+</project>
+----
+
+The following example shows a typical Gradle setup:
+
+[source,groovy,indent=0]
+.build.gradle
+----
+plugins {
+  id 'org.springframework.boot' version ${spring-boot-version}
+  id 'io.spring.dependency-management' version ${spring-dependency-management-version}
+  id 'java'
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation 'org.springframework.cloud:spring-cloud-starter-zookeeper-config'
+  testImplementation 'org.springframework.boot:spring-boot-starter-test'
+}
+dependencyManagement {
+  imports {
+    mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
+  }
+}
+----
+
+WARNING: Depending on the version you are using, you might need to adjust Apache Zookeeper version used in your project.
+You can read more about it in the xref:install.adoc[Install Zookeeper section].
+
+Now you can create a standard Spring Boot application, such as the following HTTP server:
+
+----
+@SpringBootApplication
+@RestController
+public class Application {
+
+    @GetMapping("/")
+    public String home() {
+        return "Hello World!";
+    }
+
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+
+}
+----
+
+The application retrieves configuration data from Zookeeper.
+
+WARNING: If you use Spring Cloud Zookeeper Config, you need to set the `spring.config.import` property in order to bind to Zookeeper.
+You can read more about it in the xref:config.adoc#config-data-import[Spring Boot Config Data Import section].

docs/modules/ROOT/pages/service-registry.adoc

@@ -0,0 +1,45 @@
+[[spring-cloud-zookeeper-service-registry]]
+= Spring Cloud Zookeeper and Service Registry
+
+Spring Cloud Zookeeper implements the `ServiceRegistry` interface, letting developers
+register arbitrary services in a programmatic way.
+
+The `ServiceInstanceRegistration` class offers a `builder()` method to create a
+`Registration` object that can be used by the `ServiceRegistry`, as shown in the following
+example:
+
+[source,java,indent=0]
+----
+@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);
+}
+----
+
+[[instance-status]]
+== Instance Status
+
+Netflix Eureka supports having instances that are `OUT_OF_SERVICE` registered with the server.
+These instances are not returned as active service instances.
+This is useful for behaviors such as blue/green deployments.
+(Note that 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 Spring Cloud LoadBalancer `ZookeeperServiceInstanceListSupplier`.
+The `ZookeeperServiceInstanceListSupplier` filters out all non-null instance statuses that do not equal `UP`.
+If the instance status field is empty, it is considered to be `UP` for backwards compatibility.
+To change the status of an instance, make a `POST` with `OUT_OF_SERVICE` to the `ServiceRegistry`
+instance status actuator endpoint, as shown in the following example:
+
+[source,sh,indent=0]
+----
+$ http POST http://localhost:8081/service-registry status=OUT_OF_SERVICE
+----
+
+NOTE: The preceding example uses the `http` command from https://httpie.org.
+

docs/modules/ROOT/partials/_configprops.adoc

@@ -0,0 +1,35 @@
+|===
+|Name | Default | Description
+
+|spring.cloud.zookeeper.base-sleep-time-ms | `+++50+++` | Initial amount of time to wait between retries.
+|spring.cloud.zookeeper.block-until-connected-unit |  | The unit of time related to blocking on connection to Zookeeper.
+|spring.cloud.zookeeper.block-until-connected-wait | `+++10+++` | Wait time to block on connection to Zookeeper.
+|spring.cloud.zookeeper.config.default-context | `+++application+++` | The name of the default context.
+|spring.cloud.zookeeper.config.enabled | `+++true+++` | 
+|spring.cloud.zookeeper.config.fail-fast | `+++true+++` | Throw exceptions during config lookup if true, otherwise, log warnings.
+|spring.cloud.zookeeper.config.name |  | Alternative to spring.application.name to use in looking up values in zookeeper.
+|spring.cloud.zookeeper.config.profile-separator | `+++,+++` | Separator for profile appended to the application name.
+|spring.cloud.zookeeper.config.root | `+++config+++` | Root folder where the configuration for Zookeeper is kept.
+|spring.cloud.zookeeper.connect-string | `+++localhost:2181+++` | Connection string to the Zookeeper cluster.
+|spring.cloud.zookeeper.connection-timeout |  | The configured connection timeout in milliseconds.
+|spring.cloud.zookeeper.dependencies |  | Mapping of alias to ZookeeperDependency. From LoadBalancer perspective the alias is actually serviceID since SC LoadBalancer can't accept nested structures in serviceID.
+|spring.cloud.zookeeper.dependency-configurations |  | 
+|spring.cloud.zookeeper.dependency-names |  | 
+|spring.cloud.zookeeper.discovery.enabled | `+++true+++` | 
+|spring.cloud.zookeeper.discovery.initial-status |  | The initial status of this instance (defaults to {@link StatusConstants#STATUS_UP}).
+|spring.cloud.zookeeper.discovery.instance-host |  | Predefined host with which a service can register itself in Zookeeper. Corresponds to the {code address} from the URI spec.
+|spring.cloud.zookeeper.discovery.instance-id |  | Id used to register with zookeeper. Defaults to a random UUID.
+|spring.cloud.zookeeper.discovery.instance-port |  | Port to register the service under (defaults to listening port).
+|spring.cloud.zookeeper.discovery.instance-ssl-port |  | Ssl port of the registered service.
+|spring.cloud.zookeeper.discovery.metadata |  | Gets the metadata name/value pairs associated with this instance. This information is sent to zookeeper and can be used by other instances.
+|spring.cloud.zookeeper.discovery.order | `+++0+++` | Order of the discovery client used by `CompositeDiscoveryClient` for sorting available clients.
+|spring.cloud.zookeeper.discovery.register | `+++true+++` | Register as a service in zookeeper.
+|spring.cloud.zookeeper.discovery.root | `+++/services+++` | Root Zookeeper folder in which all instances are registered.
+|spring.cloud.zookeeper.discovery.uri-spec | `+++{scheme}://{address}:{port}+++` | The URI specification to resolve during service registration in Zookeeper.
+|spring.cloud.zookeeper.enabled | `+++true+++` | Is Zookeeper enabled.
+|spring.cloud.zookeeper.max-retries | `+++10+++` | Max number of times to retry.
+|spring.cloud.zookeeper.max-sleep-ms | `+++500+++` | Max time in ms to sleep on each retry.
+|spring.cloud.zookeeper.prefix |  | Common prefix that will be applied to all Zookeeper dependencies' paths.
+|spring.cloud.zookeeper.session-timeout |  | The configured/negotiated session timeout in milliseconds. Please refer to <a href='https://cwiki.apache.org/confluence/display/CURATOR/TN14'>Curator's Tech Note 14</a> to understand how Curator implements connection sessions. @see <a href='https://cwiki.apache.org/confluence/display/CURATOR/TN14'>Curator's Tech Note 14</a>
+
+|===