From de0352ae6bd76c22c8ab49687b6519623fcd7cc3 Mon Sep 17 00:00:00 2001
From: Dave Syer <dsyer@pivotal.io>
Date: Fri, 4 Sep 2015 08:26:56 +0000
Subject: [PATCH] Sync docs from master to gh-pages

---
 spring-cloud.html | 198 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 174 insertions(+), 24 deletions(-)

diff --git a/spring-cloud.html b/spring-cloud.html
index 5865e7d..a2a4068 100644
--- a/spring-cloud.html
+++ b/spring-cloud.html
@@ -476,6 +476,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <ul class="sectlevel2">
 <li><a href="#_registering_with_eureka">Registering with Eureka</a></li>
 <li><a href="#_status_page_and_health_indicator">Status Page and Health Indicator</a></li>
+<li><a href="#_eureka_s_health_checks">Eureka&#8217;s Health Checks</a></li>
 <li><a href="#_eureka_metadata_for_instances_and_clients">Eureka Metadata for Instances and Clients</a></li>
 <li><a href="#_using_the_discoveryclient">Using the DiscoveryClient</a></li>
 <li><a href="#_alternatives_to_the_native_netflix_discoveryclient">Alternatives to the native Netflix DiscoveryClient</a></li>
@@ -513,7 +514,11 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#_using_the_ribbon_api_directly">Using the Ribbon API Directly</a></li>
 </ul>
 </li>
-<li><a href="#spring-cloud-feign">Declarative REST Client: Feign</a></li>
+<li><a href="#spring-cloud-feign">Declarative REST Client: Feign</a>
+<ul class="sectlevel2">
+<li><a href="#spring-cloud-feign-inheritance">Feign Inheritance Support</a></li>
+</ul>
+</li>
 <li><a href="#_external_configuration_archaius">External Configuration: Archaius</a></li>
 <li><a href="#_router_and_filter_zuul">Router and Filter: Zuul</a>
 <ul class="sectlevel2">
@@ -754,8 +759,8 @@ things with their parent.</p>
 <div class="sect2">
 <h3 id="customizing-bootstrap-properties">Changing the Location of Bootstrap Properties</h3>
 <div class="paragraph">
-<p>The <code>bootstrap.yml</code> (or <code>.properties) location can be specified using
-`spring.cloud.bootstrap.name</code> (default "bootstrap") or
+<p>The <code>bootstrap.yml</code> (or <code>.properties</code>) location can be specified using
+<code>spring.cloud.bootstrap.name</code> (default "bootstrap") or
 <code>spring.cloud.bootstrap.location</code> (default empty), e.g. in System
 properties. Those properties behave like the <code>spring.config.*</code>
 variants with the same name, in fact they are used to set up the
@@ -1057,12 +1062,7 @@ the provided `@LoadBalanced</code> <code>Qualifier</code>:</p>
 <h1 id="_spring_cloud_config" class="sect0">Spring Cloud Config</h1>
 <div class="openblock partintro">
 <div class="content">
-<div class="paragraph">
-<p>Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring <code>Environment</code> and <code>PropertySource</code> abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content.  It is easy to add alternative implementations and plug them in with Spring configuration.</p>
-</div>
-<div class="paragraph">
-<p><a href="https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc" class="bare">https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc</a></p>
-</div>
+Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring <code>Environment</code> and <code>PropertySource</code> abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content.  It is easy to add alternative implementations and plug them in with Spring configuration.
 </div>
 </div>
 <div class="sect1">
@@ -1272,7 +1272,78 @@ the config server URL.
 <p>The Server provides an HTTP, resource-based API for external
 configuration (name-value pairs, or equivalent YAML content).  The
 server is easily embeddable in a Spring Boot application using the
-<code>@EnableConfigServer</code> annotation.</p>
+<code>@EnableConfigServer</code> annotation. So this app is a config server:</p>
+</div>
+<div class="listingblock">
+<div class="title">ConfigServer.java</div>
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">@SpringBootApplication
+@EnableConfigServer
+public class ConfigServer {
+  public static void main(String[] args) {
+    SpringApplication.run(ConfigServer.class, args);
+  }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Like all Spring Boot apps it runs on port 8080 by default, but you
+can switch it to the conventional port 8888 in various ways. The
+easiest, which also sets a default configuration repository,
+is by launching it with <code>spring.config.name=configserver</code> (there
+is a <code>configserver.yml</code> in the Config Server jar). Another is
+to use your own <code>application.properties</code>, e.g.</p>
+</div>
+<div class="listingblock">
+<div class="title">application.properties</div>
+<div class="content">
+<pre class="highlight"><code class="language-properties" data-lang="properties">server.port: 8888
+spring.cloud.config.server.git.uri: file://${HOME}/config-repo</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>where <code>${HOME}/config-repo</code> is a git repository containing
+YAML and properties files.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Tip</div>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Here&#8217;s a recipe for creating the git repository in the example
+above:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>$ cd $HOME
+$ mkdir config-repo
+$ cd config-repo
+$ git init .
+$ echo info.foo: bar &gt; application.properties
+$ git add -A .
+$ git commit -m "Add application.properties"</pre>
+</div>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<div class="title">Warning</div>
+</td>
+<td class="content">
+using the local filesystem for your git repository is
+intended for testing only. Use a server to host your
+configuration repositories in production.
+</td>
+</tr>
+</table>
 </div>
 <div class="sect2">
 <h3 id="_environment_repository">Environment Repository</h3>
@@ -1654,9 +1725,9 @@ mysecret</pre>
 </div>
 </div>
 <div class="paragraph">
-<p>Take the encypted value and add the <code>{cipher}</code> prefix before you put
+<p>Take the encrypted value and add the <code>{cipher}</code> prefix before you put
 it in the YAML or properties file, and before you commit and push it
-to a remote, potentially insecure store. The <code>/encypt</code> and <code>/decrypt</code>
+to a remote, potentially insecure store. The <code>/encrypt</code> and <code>/decrypt</code>
 endpoints also both accept paths of the form <code>/*/{name}/{profiles}</code>
 which can be used to control cryptography per application (name)
 and profile when clients call into the main Environment resource.</p>
@@ -1689,7 +1760,7 @@ mysecret</pre>
 </div>
 </div>
 <div class="paragraph">
-<p>To use a key in a file (e.g. an RSA public key for encyption) prepend
+<p>To use a key in a file (e.g. an RSA public key for encryption) prepend
 the key value with "@" and provide the file path, e.g.</p>
 </div>
 <div class="listingblock">
@@ -2121,17 +2192,43 @@ non-default context path or servlet path
 <div class="content">
 <pre>eureka:
   instance:
-    statusPageUrlPath: ${management.contextPath}/info
-    healthCheckUrlPath: ${management.contextPath}/health</pre>
+    statusPageUrlPath: ${management.context-path}/info
+    healthCheckUrlPath: ${management.context-path}/health</pre>
 </div>
 </div>
 <div class="paragraph">
-<p>These links show up in the metadata that is consumers by clients, and
+<p>These links show up in the metadata that is consumed by clients, and
 used in some scenarios to decide whether to send requests to your
 application, so it&#8217;s helpful if they are accurate.</p>
 </div>
 </div>
 <div class="sect2">
+<h3 id="_eureka_s_health_checks">Eureka&#8217;s Health Checks</h3>
+<div class="paragraph">
+<p>By default, Eureka uses the client heartbeat to determine if a client is up.
+Unless specified otherwise the Discovery Client will not propagate the
+application Spring Boot Actuator current health check status.  Which means
+that after successful registration Eureka will always announce that the
+application is in 'UP' state. This behaviour can be altered by enabling
+Eureka health checks, which results in propagating application status
+to Eureka, as a consequence every other application will not sending
+traffic to application in state other then 'UP'.</p>
+</div>
+<div class="listingblock">
+<div class="title">application.yml</div>
+<div class="content">
+<pre>eureka:
+  client:
+    healthcheck:
+      enabled: true</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you require more control over the health checks, you may consider
+implementing your own <code>com.netflix.appinfo.HealthCheckHandler</code>.</p>
+</div>
+</div>
+<div class="sect2">
 <h3 id="_eureka_metadata_for_instances_and_clients">Eureka Metadata for Instances and Clients</h3>
 <div class="paragraph">
 <p>It&#8217;s worth spending a bit of time understanding how the Eureka metadata works, so you can use it in a way that makes sense in your platform. There is standard metadata for things like hostname, IP address, port numbers, status page and health check. These are published in the service registry and used by clients to contact the services in a straightforward way. Additional metadata can be added to the instance registration in the <code>eureka.instance.metadataMap</code>, and this will be accessible in the remote clients, but in general will not change the behaviour of the client, unless it is made aware of the meaning of the metadata. There are a couple of special cases described below where Spring Cloud already assigns meaning to the metadata map.</p>
@@ -2541,9 +2638,6 @@ for details on the properties available.</p>
 <div class="paragraph">
 <p>The same thing applies if you are using <code>@SessionScope</code> or <code>@RequestScope</code>. You will know when you need to do this because of a runtime exception that says it can&#8217;t find the scoped context.</p>
 </div>
-<div class="paragraph">
-<p>In particular you might be interested</p>
-</div>
 </div>
 <div class="sect2">
 <h3 id="_health_indicator_2">Health Indicator</h3>
@@ -2758,7 +2852,7 @@ explicitly in the <code>@ComponentScan</code>).
 <p><code>IPing</code> ribbonPing: <code>NoOpPing</code></p>
 </li>
 <li>
-<p><code>ServerList&lt;Server&gt; ribbonServerList: `ConfigurationBasedServerList</code></p>
+<p><code>ServerList&lt;Server&gt;</code> ribbonServerList: <code>ConfigurationBasedServerList</code></p>
 </li>
 <li>
 <p><code>ServerListFilter&lt;Server&gt;</code> ribbonServerListFilter: <code>ZonePreferenceServerListFilter</code></p>
@@ -2803,7 +2897,7 @@ server list will be constructed with "zone" information as provided in
 the instance metadata (so on the client set
 <code>eureka.instance.metadataMap.zone</code>), and if that is missing it can use
 the domain name from the server hostname as a proxy for zone (if the
-flag <code>approximateZoneFromDomain</code> is set). Once the zone information is
+flag <code>approximateZoneFromHostname</code> is set). Once the zone information is
 available it can be used in a <code>ServerListFilter</code> (by default it will
 be used to locate a server in the same zone as the client because the
 default is a <code>ZonePreferenceServerListFilter</code>).</p>
@@ -2919,6 +3013,43 @@ don&#8217;t want to use Eureka, you can simply configure a list of servers
 in your external configuration (see
 <a href="#spring-cloud-ribbon-without-eureka">above for example</a>).</p>
 </div>
+<div class="sect2">
+<h3 id="spring-cloud-feign-inheritance">Feign Inheritance Support</h3>
+<div class="paragraph">
+<p>Feign supports boilerplate apis via single-inheritance interfaces.
+This allows grouping common operations into convenient base interfaces.
+Together with Spring MVC you can share the same contract for your
+REST endpoint and Feign client.</p>
+</div>
+<div class="listingblock">
+<div class="title">UserService.java</div>
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">public interface UserService {
+
+    @RequestMapping(method = RequestMethod.GET, value ="/users/{id}")
+    User getUser(@PathVariable("id") long id);
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">UserResource.java</div>
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">@RestController
+public class UserResource implements UserService {
+
+}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="title">UserClient.java</div>
+<div class="content">
+<pre class="highlight"><code class="language-java" data-lang="java">@FeignClient("users")
+public interface UserClient extends UserService {
+
+}</code></pre>
+</div>
+</div>
+</div>
 </div>
 </div>
 <div class="sect1">
@@ -3022,7 +3153,7 @@ configured routes map, then it will be unignored. Example:</p>
 <div class="title">application.yml</div>
 <div class="content">
 <pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
-  ignoredServices: *
+  ignoredServices: '*'
   routes:
     users: /myusers/**</code></pre>
 </div>
@@ -3133,7 +3264,7 @@ Set that flag to "true" to have the Ribbon client automatically retry failed req
 the Ribbon client configuration).</p>
 </div>
 <div class="paragraph">
-<p>The <code>X-Forwarded-Host</code> header added to the forwarded requests by
+<p>The <code>X-Forwarded-Host</code> header is added to the forwarded requests by
 default.  To turn it off set <code>zuul.addProxyHeaders = false</code>.  The
 prefix path is stripped by default, and the request to the backend
 picks up a header "X-Forwarded-Prefix" ("/myusers" in the examples
@@ -3144,6 +3275,25 @@ above).</p>
 server if you set a default route ("/"), for example <code>zuul.route.home:
 /</code> would route all traffic (i.e. "/**") to the "home" service.</p>
 </div>
+<div class="paragraph">
+<p>If more fine-grained ignoring is needed, you can specify specific patterns to ignore.
+These patterns are being evaluated at the end of the route location process, which
+means prefixes should be included in the pattern to warrant a match. Ignored patterns
+span all services and supersede any other route specification.</p>
+</div>
+<div class="listingblock">
+<div class="title">application.yml</div>
+<div class="content">
+<pre class="highlight"><code class="language-yaml" data-lang="yaml"> zuul:
+  ignoredPatterns: */admin/**
+  routes:
+    users: /myusers/**</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This means that all calls such as "/myusers/101" will be forwarded to "/101" on the "users" service.
+But calls including "/admin/" will not resolve.</p>
+</div>
 </div>
 <div class="sect2">
 <h3 id="_uploading_files_through_zuul">Uploading Files through Zuul</h3>
@@ -3546,7 +3696,7 @@ AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...</pre>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2015-08-25 14:26:27 UTC
+Last updated 2015-09-04 08:26:05 UTC
 </div>
 </div>
 </body>