SpringCloud/spring-cloud-consul
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Antora migration (#829)

Browse Source 
* Bump com.github.tomakehurst:wiremock-jre8-standalone

Bumps [com.github.tomakehurst:wiremock-jre8-standalone](https://github.com/wiremock/wiremock) from 2.27.2 to 2.35.1.
- [Release notes](https://github.com/wiremock/wiremock/releases)
- [Commits](https://github.com/wiremock/wiremock/compare/2.27.2...2.35.1)

---
updated-dependencies:
- dependency-name: com.github.tomakehurst:wiremock-jre8-standalone
  dependency-type: direct:development
...

Signed-off-by: dependabot[bot] <support@github.com>

* 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

* Updates maven to 3.9.0

* Antora migration

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
This commit is contained in:
Spencer Gibb
2023-09-13 17:18:02 -04:00
committed by GitHub
parent e46358b089
commit 7553c55478
28 changed files with 447 additions and 864 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/modules/ROOT/assets/images/.gitkeep Normal file
View File

8
docs/modules/ROOT/nav.adoc Normal file
View File

@@ -0,0 +1,8 @@
* xref:index.adoc[]
* xref:quickstart.adoc[]
* xref:install.adoc[]
* xref:discovery.adoc[]
* xref:config.adoc[]
* xref:retry.adoc[]
* xref:bus.adoc[]
* xref:appendix.adoc[]

14
docs/modules/ROOT/pages/_attributes.adoc Normal file
View File

@@ -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 Consul
:all: {asterisk}{asterisk}

14
docs/modules/ROOT/pages/appendix.adoc Normal file
View File

@@ -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 Consul 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[]

10
docs/modules/ROOT/pages/bus.adoc Normal file
View File

@@ -0,0 +1,10 @@
[[spring-cloud-consul-bus]]
= Spring Cloud Bus with Consul
[[how-to-activate]]
== How to activate
To get started with the Consul Bus use the starter with group `org.springframework.cloud` and artifact id `spring-cloud-starter-consul-bus`. See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
See the https://cloud.spring.io/spring-cloud-bus/[Spring Cloud Bus] documentation for the available actuator endpoints and howto send custom messages.

156
docs/modules/ROOT/pages/config.adoc Normal file
View File

@@ -0,0 +1,156 @@
[[spring-cloud-consul-config]]
= Distributed Configuration with Consul
Consul provides a https://consul.io/docs/agent/http/kv.html[Key/Value Store] for storing configuration and other metadata. Spring Cloud Consul 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` folder by default. Multiple `PropertySource` instances are created based on the application's name and the active profiles that mimics 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 in the `config/application` folder are applicable to all applications using consul for configuration. Properties in the `config/testApp` folder 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. xref:config.adoc#spring-cloud-consul-config-watch[Config Watch] will also automatically detect changes and reload the application context.
[[how-to-activate]]
== How to activate
To get started with Consul Configuration use the starter with group `org.springframework.cloud` and artifact id `spring-cloud-starter-consul-config`. See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
[[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 Consul.
To optionally connect to Consul set the following in application.properties:
.application.properties
[source,properties]
----
spring.config.import=optional:consul:
----
This will connect to the Consul Agent at the default location of "http://localhost:8500". Removing the `optional:` prefix will cause Consul Config to fail if it is unable to connect to Consul. To change the connection properties of Consul Config either set `spring.cloud.consul.host` and `spring.cloud.consul.port` or add the host/port pair to the `spring.config.import` statement such as, `spring.config.import=optional:consul:myhost:8500`. The location in the import property has precedence over the host and port propertie.
Consul Config will try to load values from four automatic contexts based on `spring.cloud.consul.config.name` (which defaults to the value of the `spring.application.name` property) and `spring.cloud.consul.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:consul:myhost:8500/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
Consul Config may be customized using the following properties:
[source,yaml]
----
spring:
cloud:
consul:
config:
enabled: true
prefix: configuration
defaultContext: apps
profileSeparator: '::'
----
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`.
* `enabled` setting this value to "false" disables Consul Config
* `prefix` sets the base folder for configuration values
* `defaultContext` sets the folder name used by all applications
* `profileSeparator` sets the value of the separator used to separate the profile name in property sources with profiles
[[spring-cloud-consul-config-watch]]
== Config Watch
The Consul Config Watch takes advantage of the ability of consul to https://www.consul.io/docs/agent/watches.html#keyprefix[watch a key prefix]. The Config Watch makes a blocking Consul HTTP API call to determine if any relevant configuration data has changed for the current application. If there is new configuration data a Refresh Event is published. This is equivalent to calling the `/refresh` actuator endpoint.
To change the frequency of when the Config Watch is called change `spring.cloud.consul.config.watch.delay`. The default value is 1000, which is in milliseconds. The delay is the amount of time after the end of the previous invocation and the start of the next.
To disable the Config Watch set `spring.cloud.consul.config.watch.enabled=false`.
The watch uses a Spring `TaskScheduler` to schedule the call to consul. By default it is a `ThreadPoolTaskScheduler` with a `poolSize` of 1. To change the `TaskScheduler`, create a bean of type `TaskScheduler` named with the `ConsulConfigAutoConfiguration.CONFIG_WATCH_TASK_SCHEDULER_NAME` constant.
[[spring-cloud-consul-config-format]]
== YAML or Properties with Config
It may be more convenient to store a blob of properties in YAML or Properties format as opposed to individual key/value pairs. Set the `spring.cloud.consul.config.format` property to `YAML` or `PROPERTIES`. For example to use YAML:
[source,yaml]
----
spring:
cloud:
consul:
config:
format: YAML
----
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`.
YAML must be set in the appropriate `data` key in consul. Using the defaults above the keys would look like:
----
config/testApp,dev/data
config/testApp/data
config/application,dev/data
config/application/data
----
You could store a YAML document in any of the keys listed above.
You can change the data key using `spring.cloud.consul.config.data-key`.
[[spring-cloud-consul-config-git2consul]]
== git2consul with Config
git2consul is a Consul community project that loads files from a git repository to individual keys into Consul. By default the names of the keys are names of the files. YAML and Properties files are supported with file extensions of `.yml` and `.properties` respectively. Set the `spring.cloud.consul.config.format` property to `FILES`. For example:
.bootstrap.yml
----
spring:
cloud:
consul:
config:
format: FILES
----
Given the following keys in `/config`, the `development` profile and an application name of `foo`:
----
.gitignore
application.yml
bar.properties
foo-development.properties
foo-production.yml
foo.properties
master.ref
----
the following property sources would be created:
----
config/foo-development.properties
config/foo.properties
config/application.yml
----
The value of each key needs to be a properly formatted YAML or Properties file.
[[spring-cloud-consul-failfast]]
== Fail Fast
It may be convenient in certain circumstances (like local development or certain test scenarios) to not fail if consul isn't available for configuration. Setting `spring.cloud.consul.config.fail-fast=false` will cause the configuration module to log a warning rather than throw an exception. This will allow the application to continue startup normally.
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`.

402
docs/modules/ROOT/pages/discovery.adoc Normal file
View File

@@ -0,0 +1,402 @@
[[spring-cloud-consul-discovery]]
= Service Discovery with Consul
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. Consul provides Service Discovery services via an https://www.consul.io/docs/agent/http.html[HTTP API] and https://www.consul.io/docs/agent/dns.html[DNS]. Spring Cloud Consul leverages the HTTP API for service registration and discovery. This does not prevent non-Spring Cloud applications from leveraging the DNS interface. Consul Agents servers are run in a https://www.consul.io/docs/internals/architecture.html[cluster] that communicates via a https://www.consul.io/docs/internals/gossip.html[gossip protocol] and uses the https://www.consul.io/docs/internals/consensus.html[Raft consensus protocol].
[[how-to-activate]]
== How to activate
To activate Consul Service Discovery use the starter with group `org.springframework.cloud` and artifact id `spring-cloud-starter-consul-discovery`. See the https://projects.spring.io/spring-cloud/[Spring Cloud Project page] for details on setting up your build system with the current Spring Cloud Release Train.
[[registering-with-consul]]
== Registering with Consul
When a client registers with Consul, it provides meta-data about itself such as host and port, id, name and tags. An https://www.consul.io/docs/discovery/checks#http-interval[HTTP Check] is created by default that Consul hits the `/actuator/health` endpoint every 10 seconds. If the health check fails, the service instance is marked as critical.
Example Consul 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);
}
}
----
(i.e. utterly normal Spring Boot app). If the Consul client is located somewhere other than `localhost:8500`, the configuration is required to locate the client. Example:
.application.yml
----
spring:
cloud:
consul:
host: localhost
port: 8500
----
CAUTION: If you use xref:config.adoc[Spring Cloud Consul Config], and you have set `spring.cloud.bootstrap.enabled=true` or `spring.config.use-legacy-processing=true` or use `spring-cloud-starter-bootstrap`, then the above values will need to be placed 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.
To disable the Consul Discovery Client you can set `spring.cloud.consul.discovery.enabled` to `false`. Consul Discovery Client will also be disabled when `spring.cloud.discovery.enabled` is set to `false`.
To disable the service registration you can set `spring.cloud.consul.discovery.register` to `false`.
[[registering-management-as-a-separate-service]]
=== Registering Management as a Separate Service
When management server port is set to something different than the application port, by setting `management.server.port` property, management service will be registered as a separate service than the application service. For example:
.application.yml
----
spring:
application:
name: myApp
management:
server:
port: 4452
----
Above configuration will register following 2 services:
* Application Service:
----
ID: myApp
Name: myApp
----
* Management Service:
----
ID: myApp-management
Name: myApp-management
----
Management service will inherit its `instanceId` and `serviceName` from the application service. For example:
.application.yml
----
spring:
application:
name: myApp
management:
server:
port: 4452
spring:
cloud:
consul:
discovery:
instance-id: custom-service-id
serviceName: myprefix-${spring.application.name}
----
Above configuration will register following 2 services:
* Application Service:
----
ID: custom-service-id
Name: myprefix-myApp
----
* Management Service:
----
ID: custom-service-id-management
Name: myprefix-myApp-management
----
Further customization is possible via following properties:
----
/** Port to register the management service under (defaults to management port) */
spring.cloud.consul.discovery.management-port
/** Suffix to use when registering management service (defaults to "management") */
spring.cloud.consul.discovery.management-suffix
/** Tags to use when registering management service (defaults to "management") */
spring.cloud.consul.discovery.management-tags
----
[[http-health-check]]
=== HTTP Health Check
The health check for a Consul instance defaults to "/actuator/health", which is the default location of the health endpoint in a Spring Boot Actuator application. You need to change this, even for an Actuator application, if you use a non-default context path or servlet path (e.g. `server.servletPath=/foo`) or management endpoint path (e.g. `management.server.servlet.context-path=/admin`).
The interval that Consul uses to check the health endpoint may also be configured. "10s" and "1m" represent 10 seconds and 1 minute respectively.
This example illustrates the above (see the `spring.cloud.consul.discovery.health-check-*` properties in link:appendix.html[the appendix page] for more options).
.application.yml
----
spring:
cloud:
consul:
discovery:
healthCheckPath: ${management.server.servlet.context-path}/actuator/health
healthCheckInterval: 15s
----
You can disable the HTTP health check entirely by setting `spring.cloud.consul.discovery.register-health-check=false`.
[[applying-headers]]
==== Applying Headers
Headers can be applied to health check requests. For example, if you're trying to register a https://cloud.spring.io/spring-cloud-config/[Spring Cloud Config] server that uses https://github.com/spring-cloud/spring-cloud-config/blob/main/docs/src/main/asciidoc/spring-cloud-config.adoc#vault-backend[Vault Backend]:
.application.yml
----
spring:
cloud:
consul:
discovery:
health-check-headers:
X-Config-Token: 6442e58b-d1ea-182e-cfa5-cf9cddef0722
----
According to the HTTP standard, each header can have more than one values, in which case, an array can be supplied:
.application.yml
----
spring:
cloud:
consul:
discovery:
health-check-headers:
X-Config-Token:
- "6442e58b-d1ea-182e-cfa5-cf9cddef0722"
- "Some other value"
----
[[ttl-health-check]]
=== TTL Health Check
A Consul https://www.consul.io/docs/discovery/checks#ttl[TTL Check] can be used instead of the default configured HTTP check.
The main difference is that the application sends a heartbeat signal to the Consul agent rather than the Consul agent sending a request to the application.
The interval the application uses to send the ping may also be configured. "10s" and "1m" represent 10 seconds and 1 minute respectively.
The default is 30 seconds.
This example illustrates the above (see the `spring.cloud.consul.discovery.heartbeat.*` properties in link:appendix.html[the appendix page] for more options).
.application.yml
----
spring:
cloud:
consul:
discovery:
heartbeat:
enabled: true
ttl: 10s
----
[[ttl-application-status]]
==== TTL Application Status
For a Spring Boot Actuator application the status is determined from its available health endpoint.
When the health endpoint is not available (either disabled or not a Spring Boot Actuator application) it assumes the application is in good health.
When querying the health endpoint, the root https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#production-ready-health-groups[health group] is used by default.
A different health group can be used by setting the following property:
.application.yml
----
spring:
cloud:
consul:
discovery:
heartbeat:
actuator-health-group: <your-custom-group-goes-here>
----
You can disable the use of the health endpoint entirely by setting the following property:
.application.yml
----
spring:
cloud:
consul:
discovery:
heartbeat:
use-actuator-health: false
----
[[custom-ttl-application-status]]
===== Custom TTL Application Status
If you want to configure your own application status mechanism, simply implement the `ApplicationStatusProvider` interface
.MyCustomApplicationStatusProvider.java
----
@Bean
public class MyCustomApplicationStatusProvider implements ApplicationStatusProvider {
public CheckStatus currentStatus() {
return yourMethodToDetermineAppStatusGoesHere();
}
}
----
and make it available to the application context:
----
@Bean
public CustomApplicationStatusProvider customAppStatusProvider() {
return new MyCustomApplicationStatusProvider();
}
----
[[actuator-health-indicators]]
=== Actuator Health Indicator(s)
If the service instance is a Spring Boot Actuator application, it may be provided the following Actuator health indicators.
[[discoveryclienthealthindicator]]
==== DiscoveryClientHealthIndicator
When Consul Service Discovery is active, a https://cloud.spring.io/spring-cloud-commons/2.2.x/reference/html/#health-indicator[DiscoverClientHealthIndicator] is configured and made available to the Actuator health endpoint.
See https://cloud.spring.io/spring-cloud-commons/2.2.x/reference/html/#health-indicator[here] for configuration options.
[[consulhealthindicator]]
==== ConsulHealthIndicator
An indicator is configured that verifies the health of the `ConsulClient`.
By default, it retrieves the Consul leader node status and all registered services.
In deployments that have many registered services it may be costly to retrieve all services on every health check.
To skip the service retrieval and only check the leader node status set `spring.cloud.consul.health-indicator.include-services-query=false`.
To disable the indicator set `management.health.consul.enabled=false`.
WARNING: When the application runs in https://cloud.spring.io/spring-cloud-commons/2.2.x/reference/html/#the-bootstrap-application-context[bootstrap context mode] (the default),
this indicator is loaded into the bootstrap context and is not made available to the Actuator health endpoint.
[[metadata]]
=== Metadata
Consul supports metadata on services. Spring Cloud's `ServiceInstance` has a `Map<String, String> metadata` field which is populated from a services `meta` field. To populate the `meta` field set values on `spring.cloud.consul.discovery.metadata` or `spring.cloud.consul.discovery.management-metadata` properties.
.application.yml
----
spring:
cloud:
consul:
discovery:
metadata:
myfield: myvalue
anotherfield: anothervalue
----
The above configuration will result in a service who's meta field contains `myfield->myvalue` and `anotherfield->anothervalue`.
[[generated-metadata]]
==== Generated Metadata
The Consul Auto Registration will generate a few entries automatically.
.Auto Generated Metadata
|===
| Key | Value
| 'group'
| Property `spring.cloud.consul.discovery.instance-group`. This values is only generated if `instance-group` is not empty.'
| 'secure'
| True if property `spring.cloud.consul.discovery.scheme` equals 'https', otherwise false.
| Property `spring.cloud.consul.discovery.default-zone-metadata-name`, defaults to 'zone'
| Property `spring.cloud.consul.discovery.instance-zone`. This values is only generated if `instance-zone` is not empty.'
|===
WARNING: Older versions of Spring Cloud Consul populated the `ServiceInstance.getMetadata()` method from Spring Cloud Commons by parsing the `spring.cloud.consul.discovery.tags` property. This is no longer supported, please migrate to using the `spring.cloud.consul.discovery.metadata` map.
[[making-the-consul-instance-id-unique]]
=== Making the Consul Instance ID Unique
By default a consul instance is registered with an ID that is equal to its Spring Application Context ID. By default, the Spring Application Context ID is `${spring.application.name}:comma,separated,profiles:${server.port}`. For most cases, this will allow multiple instances of one service to run on one machine. If further uniqueness is required, Using Spring Cloud you can override this by providing a unique identifier in `spring.cloud.consul.discovery.instanceId`. For example:
.application.yml
----
spring:
cloud:
consul:
discovery:
instanceId: ${spring.application.name}:${vcap.application.instance_id:${spring.application.instance_id:${random.value}}}
----
With this metadata, and multiple service instances deployed on localhost, the random value will kick in there to make the instance unique. In Cloudfoundry the `vcap.application.instance_id` will be populated automatically in a Spring Boot application, so the random value will not be needed.
[[looking-up-services]]
== Looking up services
[[using-load-balancer]]
=== Using Load-balancer
Spring Cloud has support for https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/[Feign] (a REST client builder) and also https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#rest-template-loadbalancer-client[Spring `RestTemplate`]
for looking up services using the logical service names/ids instead of physical URLs. Both Feign and the discovery-aware RestTemplate utilize https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer[Spring Cloud LoadBalancer] for client-side load balancing.
If you want to access service STORES using the RestTemplate simply declare:
----
@LoadBalanced
@Bean
public RestTemplate loadbalancedRestTemplate() {
return new RestTemplate();
}
----
and use it like this (notice how we use the STORES service name/id from Consul instead of a fully qualified domainname):
----
@Autowired
RestTemplate restTemplate;
public String getFirstProduct() {
return this.restTemplate.getForObject("https://STORES/products/1", String.class);
}
----
If you have Consul clusters in multiple datacenters and you want to access a service in another datacenter a service name/id alone is not enough. In that case
you use property `spring.cloud.consul.discovery.datacenters.STORES=dc-west` where `STORES` is the service name/id and `dc-west` is the datacenter
where the STORES service lives.
TIP: Spring Cloud now also offers support for
https://cloud.spring.io/spring-cloud-commons/reference/html/#_spring_resttemplate_as_a_load_balancer_client[Spring Cloud LoadBalancer].
[[using-the-discoveryclient]]
=== Using the DiscoveryClient
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();
}
return null;
}
----
[[consul-catalog-watch]]
== Consul Catalog Watch
The Consul Catalog Watch takes advantage of the ability of consul to https://www.consul.io/docs/agent/watches.html#services[watch services]. The Catalog Watch makes a blocking Consul HTTP API call to determine if any services have changed. If there is new service data a Heartbeat Event is published.
To change the frequency of when the Config Watch is called change `spring.cloud.consul.config.discovery.catalog-services-watch-delay`. The default value is 1000, which is in milliseconds. The delay is the amount of time after the end of the previous invocation and the start of the next.
To disable the Catalog Watch set `spring.cloud.consul.discovery.catalogServicesWatch.enabled=false`.
The watch uses a Spring `TaskScheduler` to schedule the call to consul. By default it is a `ThreadPoolTaskScheduler` with a `poolSize` of 1. To change the `TaskScheduler`, create a bean of type `TaskScheduler` named with the `ConsulDiscoveryClientConfiguration.CATALOG_WATCH_TASK_SCHEDULER_NAME` constant.

1
docs/modules/ROOT/pages/index.adoc Executable file
View File

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

14
docs/modules/ROOT/pages/install.adoc Normal file
View File

@@ -0,0 +1,14 @@
[[spring-cloud-consul-install]]
= Install Consul
// TODO: document using Testcontainers and SpringApplication.from()
Please see the https://www.consul.io/intro/getting-started/install.html[installation documentation] for instructions on how to install Consul.
[[spring-cloud-consul-agent]]
== Consul Agent
A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at `localhost:8500`. See the https://consul.io/docs/agent/basics.html[Agent documentation] for specifics on how to start an Agent client and how to connect to a cluster of Consul Agent Servers. Start a development agent according to the documentation above.
This will start an agent in server mode on port 8500, with the ui available at http://localhost:8500

11
docs/modules/ROOT/pages/intro.adoc Normal file
View File

@@ -0,0 +1,11 @@
[[spring-cloud-gateway-intro]]
= Introduction
This project provides Consul 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 Consul based components. The
patterns provided include Service Discovery, Control Bus and Configuration.
Intelligent Routing and Client Side Load Balancing, Circuit Breaker
are provided by integration with other Spring Cloud projects.

232
docs/modules/ROOT/pages/quickstart.adoc Normal file
View File

@@ -0,0 +1,232 @@
[[quickstart]]
= Quick Start
This quick start walks through using Spring Cloud Consul for Service Discovery and Distributed Configuration.
First, run Consul Agent on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Consul.
[[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-consul-core`.
The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-consul-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-consul-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-consul-discovery'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
}
}
----
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 Consul Agent running at the default local 8500 port.
To modify the startup behavior, you can change the location of Consul Agent by using `application.properties`, as shown in the following example:
----
spring:
cloud:
consul:
host: localhost
port: 8500
----
You can now use `DiscoveryClient`, `@LoadBalanced RestTemplate`, or `@LoadBalanced WebClient.Builder` to retrieve services and instances data from Consul, 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-consul-core` and `spring-cloud-consul-config`.
The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-consul-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-consul-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-consul-config'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
}
}
----
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 Consul.
WARNING: If you use Spring Cloud Consul Config, you need to set the `spring.config.import` property in order to bind to Consul.
You can read more about it in the xref:config.adoc#config-data-import[Spring Boot Config Data Import section].

15
docs/modules/ROOT/pages/retry.adoc Normal file
View File

@@ -0,0 +1,15 @@
[[spring-cloud-consul-retry]]
= Consul Retry
If you expect that the consul agent may occasionally be unavailable when
your app starts, you can ask it to keep trying after a failure. You need to add
`spring-retry` and `spring-boot-starter-aop` to your classpath. The default
behaviour is to retry 6 times with an initial backoff interval of 1000ms and an
exponential multiplier of 1.1 for subsequent backoffs. You can configure these
properties (and others) using `spring.cloud.consul.retry.*` configuration properties.
This works with both Spring Cloud Consul Config and Discovery registration.
TIP: To take full control of the retry add a `@Bean` of type
`RetryOperationsInterceptor` with id "consulRetryInterceptor". Spring
Retry has a `RetryInterceptorBuilder` that makes it easy to create one.

84
docs/modules/ROOT/partials/_configprops.adoc Normal file
View File

@@ -0,0 +1,84 @@
|===
|Name | Default | Description
|spring.cloud.consul.config.acl-token | |
|spring.cloud.consul.config.data-key | `+++data+++` | If format is Format.PROPERTIES or Format.YAML then the following field is used as key to look up consul for configuration.
|spring.cloud.consul.config.default-context | `+++application+++` |
|spring.cloud.consul.config.enabled | `+++true+++` |
|spring.cloud.consul.config.fail-fast | `+++true+++` | Throw exceptions during config lookup if true, otherwise, log warnings.
|spring.cloud.consul.config.format | |
|spring.cloud.consul.config.name | | Alternative to spring.application.name to use in looking up values in consul KV.
|spring.cloud.consul.config.prefix | |
|spring.cloud.consul.config.prefixes | |
|spring.cloud.consul.config.profile-separator | `+++,+++` |
|spring.cloud.consul.config.watch.delay | `+++1000+++` | The value of the fixed delay for the watch in millis. Defaults to 1000.
|spring.cloud.consul.config.watch.enabled | `+++true+++` | If the watch is enabled. Defaults to true.
|spring.cloud.consul.config.watch.wait-time | `+++55+++` | The number of seconds to wait (or block) for watch query, defaults to 55. Needs to be less than default ConsulClient (defaults to 60). To increase ConsulClient timeout create a ConsulClient bean with a custom ConsulRawClient with a custom HttpClient.
|spring.cloud.consul.discovery.acl-token | |
|spring.cloud.consul.discovery.catalog-services-watch-delay | `+++1000+++` | The delay between calls to watch consul catalog in millis, default is 1000.
|spring.cloud.consul.discovery.catalog-services-watch-timeout | `+++2+++` | The number of seconds to block while watching consul catalog, default is 2.
|spring.cloud.consul.discovery.consistency-mode | | Consistency mode for health service request.
|spring.cloud.consul.discovery.datacenters | | Map of serviceId's -> datacenter to query for in server list. This allows looking up services in another datacenters.
|spring.cloud.consul.discovery.default-query-tag | | Tag to query for in service list if one is not listed in serverListQueryTags. Multiple tags can be specified with a comma separated value.
|spring.cloud.consul.discovery.default-zone-metadata-name | `+++zone+++` | Service instance zone comes from metadata. This allows changing the metadata tag name.
|spring.cloud.consul.discovery.deregister | `+++true+++` | Disable automatic de-registration of service in consul.
|spring.cloud.consul.discovery.enable-tag-override | | Enable tag override for the registered service.
|spring.cloud.consul.discovery.enabled | `+++true+++` | Is service discovery enabled?
|spring.cloud.consul.discovery.fail-fast | `+++true+++` | Throw exceptions during service registration if true, otherwise, log warnings (defaults to true).
|spring.cloud.consul.discovery.health-check-critical-timeout | | Timeout to deregister services critical for longer than timeout (e.g. 30m). Requires consul version 7.x or higher.
|spring.cloud.consul.discovery.health-check-headers | | Headers to be applied to the Health Check calls.
|spring.cloud.consul.discovery.health-check-interval | `+++10s+++` | How often to perform the health check (e.g. 10s), defaults to 10s.
|spring.cloud.consul.discovery.health-check-path | `+++/actuator/health+++` | Alternate server path to invoke for health checking.
|spring.cloud.consul.discovery.health-check-timeout | | Timeout for health check (e.g. 10s).
|spring.cloud.consul.discovery.health-check-tls-skip-verify | | Skips certificate verification during service checks if true, otherwise runs certificate verification.
|spring.cloud.consul.discovery.health-check-url | | Custom health check url to override default.
|spring.cloud.consul.discovery.heartbeat.actuator-health-group | | The actuator health group to use (null for the root group) when determining system health via Actuator.
|spring.cloud.consul.discovery.heartbeat.enabled | `+++false+++` |
|spring.cloud.consul.discovery.heartbeat.interval-ratio | |
|spring.cloud.consul.discovery.heartbeat.reregister-service-on-failure | `+++false+++` |
|spring.cloud.consul.discovery.heartbeat.ttl | `+++30s+++` |
|spring.cloud.consul.discovery.heartbeat.use-actuator-health | `+++true+++` | Whether or not to take the current system health (as reported via the Actuator Health endpoint) into account when reporting the application status to the Consul TTL check. Actuator Health endpoint also has to be available to the application.
|spring.cloud.consul.discovery.hostname | | Hostname to use when accessing server.
|spring.cloud.consul.discovery.include-hostname-in-instance-id | `+++false+++` | Whether hostname is included into the default instance id when registering service.
|spring.cloud.consul.discovery.instance-group | | Service instance group.
|spring.cloud.consul.discovery.instance-id | | Unique service instance id.
|spring.cloud.consul.discovery.instance-zone | | Service instance zone.
|spring.cloud.consul.discovery.ip-address | | IP address to use when accessing service (must also set preferIpAddress to use).
|spring.cloud.consul.discovery.lifecycle.enabled | `+++true+++` |
|spring.cloud.consul.discovery.management-enable-tag-override | | Enable tag override for the registered management service.
|spring.cloud.consul.discovery.management-metadata | | Metadata to use when registering management service.
|spring.cloud.consul.discovery.management-port | | Port to register the management service under (defaults to management port).
|spring.cloud.consul.discovery.management-suffix | `+++management+++` | Suffix to use when registering management service.
|spring.cloud.consul.discovery.management-tags | | Tags to use when registering management service.
|spring.cloud.consul.discovery.metadata | | Metadata to use when registering service.
|spring.cloud.consul.discovery.order | `+++0+++` | Order of the discovery client used by `CompositeDiscoveryClient` for sorting available clients.
|spring.cloud.consul.discovery.port | | Port to register the service under (defaults to listening port).
|spring.cloud.consul.discovery.prefer-agent-address | `+++false+++` | Source of how we will determine the address to use.
|spring.cloud.consul.discovery.prefer-ip-address | `+++false+++` | Use ip address rather than hostname during registration.
|spring.cloud.consul.discovery.query-passing | `+++false+++` | Add the 'passing` parameter to /v1/health/service/serviceName. This pushes health check passing to the server.
|spring.cloud.consul.discovery.register | `+++true+++` | Register as a service in consul.
|spring.cloud.consul.discovery.register-health-check | `+++true+++` | Register health check in consul. Useful during development of a service.
|spring.cloud.consul.discovery.scheme | `+++http+++` | Whether to register an http or https service.
|spring.cloud.consul.discovery.server-list-query-tags | | Map of serviceId's -> tag to query for in server list. This allows filtering services by one more tags. Multiple tags can be specified with a comma separated value.
|spring.cloud.consul.discovery.service-name | | Service name.
|spring.cloud.consul.discovery.tags | | Tags to use when registering service.
|spring.cloud.consul.enabled | `+++true+++` | Is spring cloud consul enabled.
|spring.cloud.consul.host | `+++localhost+++` | Consul agent hostname. Defaults to 'localhost'.
|spring.cloud.consul.path | | Custom path if consul is under non-root.
|spring.cloud.consul.port | `+++8500+++` | Consul agent port. Defaults to '8500'.
|spring.cloud.consul.retry.enabled | `+++true+++` | If consul retry is enabled.
|spring.cloud.consul.retry.initial-interval | `+++1000+++` | Initial retry interval in milliseconds.
|spring.cloud.consul.retry.max-attempts | `+++6+++` | Maximum number of attempts.
|spring.cloud.consul.retry.max-interval | `+++2000+++` | Maximum interval for backoff.
|spring.cloud.consul.retry.multiplier | `+++1.1+++` | Multiplier for next interval.
|spring.cloud.consul.ribbon.enabled | `+++true+++` | Enables Consul and Ribbon integration.
|spring.cloud.consul.scheme | | Consul agent scheme (HTTP/HTTPS). If there is no scheme in address - client will use HTTP.
|spring.cloud.consul.service-registry.auto-registration.enabled | `+++true+++` | Enables Consul Service Registry Auto-registration.
|spring.cloud.consul.service-registry.enabled | `+++true+++` | Enables Consul Service Registry functionality.
|spring.cloud.consul.tls.certificate-password | | Password to open the certificate.
|spring.cloud.consul.tls.certificate-path | | File path to the certificate.
|spring.cloud.consul.tls.key-store-instance-type | | Type of key framework to use.
|spring.cloud.consul.tls.key-store-password | | Password to an external keystore.
|spring.cloud.consul.tls.key-store-path | | Path to an external keystore.
|===

6
docs/modules/ROOT/partials/_conventions.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[observability-conventions]]
=== Observability - Conventions
Below you can find a list of all `GlobalObservationConvention` and `ObservationConvention` declared by this project.

6
docs/modules/ROOT/partials/_metrics.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[observability-metrics]]
=== Observability - Metrics
Below you can find a list of all metrics declared by this project.

6
docs/modules/ROOT/partials/_spans.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[observability-spans]]
=== Observability - Spans
Below you can find a list of all spans declared by this project.