![[Caution]](images/caution.png)
![[Tip]](images/tip.png)
1.2.2.BUILD-SNAPSHOT
-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 (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker -(Hystrix) are provided by integration with Spring Cloud Netflix.
+1.2.2.BUILD-SNAPSHOT
Install Consul
+Pick The Documentation Option
Please see the installation documentation for instructions on how to install Consul.
-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 Agent documentation for specifics on how to start an Agent client and how to connect to a cluster of Consul Agent Servers. For development, after you have installed consul, you may start a Consul Agent using the following command:
./src/main/bash/local_run_consul.sh-
This will start an agent in server mode on port 8500, with the ui available at http://localhost:8500
-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 HTTP API and 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 cluster that communicates via a gossip protocol and uses the Raft consensus protocol.
-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 Spring Cloud Project page for details on setting up your build system with the current Spring Cloud Release Train.
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 HTTP Check is created by default that Consul hits the /health endpoint every 10 seconds. If the health check fails, the service instance is marked as critical.
Example Consul client:
-@SpringBootApplication
-@EnableDiscoveryClient
-@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:
spring: - cloud: - consul: - host: localhost - port: 8500-
|
- Caution
- |
-
-If you use Spring Cloud Consul Config, 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.
@EnableDiscoveryClient make the app into both a Consul "service" (i.e. it registers itself) and a "client" (i.e. it can query Consul to locate other services).
HTTP Health Check
-The health check for a Consul instance defaults to "/health", which is the default locations of a useful endpoint in a Spring Boot Actuator application. You need to change these, 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.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. Example:
spring:
- cloud:
- consul:
- discovery:
- healthCheckPath: ${management.context-path}/health
- healthCheckInterval: 15s
-Metadata and Consul tags
-Consul does not yet support metadata on services. Spring Cloud’s ServiceInstance has a Map<String, String> metadata field. Spring Cloud Consul uses Consul tags to approximate metadata until Consul officially supports metadata. Tags with the form key=value will be split and used as a Map key and value respectively. Tags without the equal = sign, will be used as both the key and value.
spring: - cloud: - consul: - discovery: - tags: foo=bar, baz-
The above configuration will result in a map with foo→bar and baz→baz.
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:
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.
Using the DiscoveryClient
-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();
- }
- return null;
-}
-Distributed Configuration with Consul
-Consul provides a Key/Value Store for storing configuration and other metadata. Spring Cloud Consul 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 folder 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 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. Watching the key value store (which Consul supports) is not currently possible, but will be a future addition to this project.
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 Spring Cloud Project page for details on setting up your build system with the current Spring Cloud Release Train.
This will enable auto-configuration that will setup Spring Cloud Consul Config.
-Customizing
-Consul Config may be customized using the following properties:
-spring: - cloud: - consul: - config: - enabled: true - prefix: configuration - defaultContext: apps - profileSeparator: '::'-
-
-
+enabledsetting this value to "false" disables Consul Config -
-
-prefixsets the base folder for configuration values
- -
-
-defaultContextsets the folder name used by all applications
- -
-
+profileSeparatorsets the value of the separator used to separate the profile name in property sources with profiles
Config Watch
-The Consul Config Watch takes advantage of the ability of consul to 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.
To disable the Config Watch set spring.cloud.consul.config.watch.enabled=false.
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:
spring: - cloud: - consul: - config: - format: YAML-
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.
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:
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.
-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.failFast=false in bootstrap.yml will cause the configuration module to log a warning rather than throw an exception. This will allow the application to continue startup normally.
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.
- |
-
Spring Cloud Bus with Consul
-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 Spring Cloud Project page for details on setting up your build system with the current Spring Cloud Release Train.
See the Spring Cloud Bus documentation for the available actuator endpoints and howto send custom messages.
-Circuit Breaker with Hystrix
-Applications can use the Hystrix Circuit Breaker provided by the Spring Cloud Netflix project by including this starter in the projects pom.xml: spring-cloud-starter-hystrix. Hystrix doesn’t depend on the Netflix Discovery Client. The @EnableHystrix annotation should be placed on a configuration class (usually the main class). Then methods can be annotated with @HystrixCommand to be protected by a circuit breaker. See the documentation for more details.
Hystrix metrics aggregation with Turbine and Consul
-Turbine (provided by the Spring Cloud Netflix project), aggregates multiple instances Hystrix metrics streams, so the dashboard can display an aggregate view. Turbine uses the DiscoveryClient interface to lookup relevant instances. To use Turbine with Spring Cloud Consul, configure the Turbine application in a manner similar to the following examples:
<dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-netflix-turbine</artifactId> -</dependency> -<dependency> - <groupId>org.springframework.cloud</groupId> - <artifactId>spring-cloud-starter-consul-discovery</artifactId> -</dependency>-
Notice that the Turbine dependency is not a starter. The turbine starter includes support for Netflix Eureka.
-spring.application.name: turbine
-applications: consulhystrixclient
-turbine:
- aggregator:
- clusterConfig: ${applications}
- appConfig: ${applications}
-The clusterConfig and appConfig sections must match, so it’s useful to put the comma-separated list of service ID’s into a separate configuration property.
@EnableTurbine
-@EnableDiscoveryClient
-@SpringBootApplication
-public class Turbine {
- public static void main(String[] args) {
- SpringApplication.run(DemoturbinecommonsApplication.class, args);
- }
-}
-