|
|
|
|
@@ -1,16 +1,16 @@
|
|
|
|
|
<html><head>
|
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
|
|
|
<title>Spring Cloud Consul</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Spring Cloud Consul</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#d0e9"></a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-install">1. Install Consul</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-agent">2. Consul Agent</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-discovery">3. Service Discovery with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate">3.1. How to activate</a></span></dt><dt><span class="section"><a href="#_registering_with_consul">3.2. Registering with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_registering_management_as_a_separate_service">3.2.1. Registering Management as a Separate Service</a></span></dt></dl></dd><dt><span class="section"><a href="#_http_health_check">3.3. HTTP Health Check</a></span></dt><dd><dl><dt><span class="section"><a href="#_metadata_and_consul_tags">3.3.1. Metadata and Consul tags</a></span></dt><dt><span class="section"><a href="#_making_the_consul_instance_id_unique">3.3.2. Making the Consul Instance ID Unique</a></span></dt><dt><span class="section"><a href="#_applying_headers_to_health_check_requests">3.3.3. Applying Headers to Health Check Requests</a></span></dt></dl></dd><dt><span class="section"><a href="#_looking_up_services">3.4. Looking up services</a></span></dt><dd><dl><dt><span class="section"><a href="#_using_ribbon">3.4.1. Using Ribbon</a></span></dt><dt><span class="section"><a href="#_using_the_discoveryclient">3.4.2. Using the DiscoveryClient</a></span></dt></dl></dd><dt><span class="section"><a href="#_consul_catalog_watch">3.5. Consul Catalog Watch</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-config">4. Distributed Configuration with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_2">4.1. How to activate</a></span></dt><dt><span class="section"><a href="#_customizing">4.2. Customizing</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-watch">4.3. Config Watch</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-format">4.4. YAML or Properties with Config</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-git2consul">4.5. git2consul with Config</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-failfast">4.6. Fail Fast</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-retry">5. Consul Retry</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-bus">6. Spring Cloud Bus with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_3">6.1. How to activate</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-hystrix">7. Circuit Breaker with Hystrix</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-turbine">8. Hystrix metrics aggregation with Turbine and Consul</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9" href="#d0e9"></a></h1></div></div></div><p><span class="strong"><strong>2.1.2.BUILD-SNAPSHOT</strong></span></p><p>This project provides Consul integrations for Spring Boot apps through autoconfiguration
|
|
|
|
|
<title>Spring Cloud Consul</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Spring Cloud Consul</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#d0e9"></a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-install">1. Install Consul</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-agent">2. Consul Agent</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-discovery">3. Service Discovery with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate">3.1. How to activate</a></span></dt><dt><span class="section"><a href="#_registering_with_consul">3.2. Registering with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_registering_management_as_a_separate_service">3.2.1. Registering Management as a Separate Service</a></span></dt></dl></dd><dt><span class="section"><a href="#_http_health_check">3.3. HTTP Health Check</a></span></dt><dd><dl><dt><span class="section"><a href="#_metadata_and_consul_tags">3.3.1. Metadata and Consul tags</a></span></dt><dt><span class="section"><a href="#_making_the_consul_instance_id_unique">3.3.2. Making the Consul Instance ID Unique</a></span></dt><dt><span class="section"><a href="#_applying_headers_to_health_check_requests">3.3.3. Applying Headers to Health Check Requests</a></span></dt></dl></dd><dt><span class="section"><a href="#_looking_up_services">3.4. Looking up services</a></span></dt><dd><dl><dt><span class="section"><a href="#_using_ribbon">3.4.1. Using Ribbon</a></span></dt><dt><span class="section"><a href="#_using_the_discoveryclient">3.4.2. Using the DiscoveryClient</a></span></dt></dl></dd><dt><span class="section"><a href="#_consul_catalog_watch">3.5. Consul Catalog Watch</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-config">4. Distributed Configuration with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_2">4.1. How to activate</a></span></dt><dt><span class="section"><a href="#_customizing">4.2. Customizing</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-watch">4.3. Config Watch</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-format">4.4. YAML or Properties with Config</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-git2consul">4.5. git2consul with Config</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-failfast">4.6. Fail Fast</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-retry">5. Consul Retry</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-bus">6. Spring Cloud Bus with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_3">6.1. How to activate</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-hystrix">7. Circuit Breaker with Hystrix</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-turbine">8. Hystrix metrics aggregation with Turbine and Consul</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9" href="#d0e9"></a></h1></div></div></div><p><span class="strong"><strong>2.1.3.BUILD-SNAPSHOT</strong></span></p><p>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.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spring-cloud-consul-install" href="#spring-cloud-consul-install"></a>1. Install Consul</h1></div></div></div><p>Please see the <a class="link" href="https://www.consul.io/intro/getting-started/install.html" target="_top">installation documentation</a> for instructions on how to install Consul.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spring-cloud-consul-agent" href="#spring-cloud-consul-agent"></a>2. Consul Agent</h1></div></div></div><p>A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at <code class="literal">localhost:8500</code>. See the <a class="link" href="https://consul.io/docs/agent/basics.html" target="_top">Agent documentation</a> 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:</p><pre class="screen">./src/main/bash/local_run_consul.sh</pre><p>This will start an agent in server mode on port 8500, with the ui available at <a class="link" href="http://localhost:8500" target="_top">http://localhost:8500</a></p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spring-cloud-consul-discovery" href="#spring-cloud-consul-discovery"></a>3. Service Discovery with Consul</h1></div></div></div><p>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 <a class="link" href="https://www.consul.io/docs/agent/http.html" target="_top">HTTP API</a> and <a class="link" href="https://www.consul.io/docs/agent/dns.html" target="_top">DNS</a>. 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 <a class="link" href="https://www.consul.io/docs/internals/architecture.html" target="_top">cluster</a> that communicates via a <a class="link" href="https://www.consul.io/docs/internals/gossip.html" target="_top">gossip protocol</a> and uses the <a class="link" href="https://www.consul.io/docs/internals/consensus.html" target="_top">Raft consensus protocol</a>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate" href="#_how_to_activate"></a>3.1 How to activate</h2></div></div></div><p>To activate Consul Service Discovery use the starter with group <code class="literal">org.springframework.cloud</code> and artifact id <code class="literal">spring-cloud-starter-consul-discovery</code>. See the <a class="link" href="https://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a> for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_with_consul" href="#_registering_with_consul"></a>3.2 Registering with Consul</h2></div></div></div><p>When a client registers with Consul, it provides meta-data about itself such as host and port, id, name and tags. An HTTP <a class="link" href="https://www.consul.io/docs/agent/checks.html" target="_top">Check</a> is created by default that Consul hits the <code class="literal">/health</code> endpoint every 10 seconds. If the health check fails, the service instance is marked as critical.</p><p>Example Consul client:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
|
|
|
(Hystrix) are provided by integration with Spring Cloud Netflix.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spring-cloud-consul-install" href="#spring-cloud-consul-install"></a>1. Install Consul</h1></div></div></div><p>Please see the <a class="link" href="https://www.consul.io/intro/getting-started/install.html" target="_top">installation documentation</a> for instructions on how to install Consul.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spring-cloud-consul-agent" href="#spring-cloud-consul-agent"></a>2. Consul Agent</h1></div></div></div><p>A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at <code class="literal">localhost:8500</code>. See the <a class="link" href="https://consul.io/docs/agent/basics.html" target="_top">Agent documentation</a> 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:</p><pre class="screen">./src/main/bash/local_run_consul.sh</pre><p>This will start an agent in server mode on port 8500, with the ui available at <a class="link" href="http://localhost:8500" target="_top">http://localhost:8500</a></p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="spring-cloud-consul-discovery" href="#spring-cloud-consul-discovery"></a>3. Service Discovery with Consul</h1></div></div></div><p>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 <a class="link" href="https://www.consul.io/docs/agent/http.html" target="_top">HTTP API</a> and <a class="link" href="https://www.consul.io/docs/agent/dns.html" target="_top">DNS</a>. 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 <a class="link" href="https://www.consul.io/docs/internals/architecture.html" target="_top">cluster</a> that communicates via a <a class="link" href="https://www.consul.io/docs/internals/gossip.html" target="_top">gossip protocol</a> and uses the <a class="link" href="https://www.consul.io/docs/internals/consensus.html" target="_top">Raft consensus protocol</a>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate" href="#_how_to_activate"></a>3.1 How to activate</h2></div></div></div><p>To activate Consul Service Discovery use the starter with group <code class="literal">org.springframework.cloud</code> and artifact id <code class="literal">spring-cloud-starter-consul-discovery</code>. See the <a class="link" href="https://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a> for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_with_consul" href="#_registering_with_consul"></a>3.2 Registering with Consul</h2></div></div></div><p>When a client registers with Consul, it provides meta-data about itself such as host and port, id, name and tags. An HTTP <a class="link" href="https://www.consul.io/docs/agent/checks.html" target="_top">Check</a> is created by default that Consul hits the <code class="literal">/health</code> endpoint every 10 seconds. If the health check fails, the service instance is marked as critical.</p><p>Example Consul client:</p><pre class="programlisting"><xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@SpringBootApplication</xslthl:annotation>
|
|
|
|
|
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@RestController</xslthl:annotation>
|
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
|
|
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping("/")</span></em>
|
|
|
|
|
<xslthl:annotation xmlns:xslthl="http://xslthl.sourceforge.net/">@RequestMapping("/")</xslthl:annotation>
|
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String home() {
|
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello world"</span>;
|
|
|
|
|
}
|
|
|
|
|
|
buildmaster