From 1b0b3b25ab703c00cba56f0c7b9f4a0243f52bca Mon Sep 17 00:00:00 2001
From: Dave Syer <dsyer@pivotal.io>
Date: Mon, 16 Feb 2015 15:19:43 +0000
Subject: [PATCH] Sync docs from master to gh-pages

---
 spring-cloud.html | 53 ++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/spring-cloud.html b/spring-cloud.html
index 881f4c4..f34290d 100644
--- a/spring-cloud.html
+++ b/spring-cloud.html
@@ -459,7 +459,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="#_making_the_eureka_instance_id_unique">Making the Eureka Instance ID Unique</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_discoveryclient">Alternatives to the DiscoveryClient</a></li>
 <li><a href="#_why_is_it_so_slow_to_register_a_service">Why is it so Slow to Register a Service?</a></li>
@@ -483,7 +483,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#spring-cloud-ribbon">Client Side Load Balancer: Ribbon</a>
 <ul class="sectlevel2">
 <li><a href="#_customizing_the_ribbon_client">Customizing the Ribbon Client</a></li>
-<li><a href="#_using_the_ribbon_with_eureka">Using the Ribbon with Eureka</a></li>
+<li><a href="#_using_ribbon_with_eureka">Using Ribbon with Eureka</a></li>
 <li><a href="#spring-cloud-ribbon-without-eureka">Example: How to Use Ribbon Without Eureka</a></li>
 <li><a href="#_using_the_ribbon_api_directly">Using the Ribbon API Directly</a></li>
 <li><a href="#_spring_resttemplate_as_a_ribbon_client">Spring RestTemplate as a Ribbon Client</a></li>
@@ -1748,7 +1748,32 @@ application, so it&#8217;s helpful if they are accurate.</p>
 </div>
 </div>
 <div class="sect2">
-<h3 id="_making_the_eureka_instance_id_unique">Making the Eureka Instance ID Unique</h3>
+<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>
+</div>
+<div class="sect3">
+<h4 id="_using_eureka_on_cloudfoundry">Using Eureka on Cloudfoundry</h4>
+<div class="paragraph">
+<p>Cloudfoundry has a global router so that all instances of the same app have the same hostname (it&#8217;s the same in other PaaS solutions with a similar architecture). This isn&#8217;t necessarily a barrier to using Eureka, but if you use the router (recommended, or even mandatory depending on the way your platform was set up), you need to explicitly set the hostname and port numbers (secure or non-secure) so that they use the router. You might also want to use instance metadata so you can distinguish between the instances on the client (e.g. in a custom load balancer). For example:</p>
+</div>
+<div class="listingblock">
+<div class="title">application.yml</div>
+<div class="content">
+<pre>eureka:
+  instance:
+    metadataMap:
+      hostname: ${vcap.application.uris[0]}
+      nonSecurePort: 80
+      instanceId: ${vcap.application.instance_id:${spring.application.name}:${spring.application.instance_id:${server.port}}}</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Depending on the way the security rules are set up in your Cloudfoundry instance, you might be able to register and use the IP address of the host VM for direct service-to-service calls. This feature is not (yet) available on Pivotal Web Services (<a href="https://run.pivotal.io">PWS</a>).</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_making_the_eureka_instance_id_unique">Making the Eureka Instance ID Unique</h4>
 <div class="paragraph">
 <p>By default a eureka instance is registered with an ID that is equal to its host name (i.e. only one service per host). Using Spring Cloud you can override this by providing a unique identifier in <code>eureka.instance.metadataMap.instanceId</code>. For example:</p>
 </div>
@@ -1761,6 +1786,14 @@ application, so it&#8217;s helpful if they are accurate.</p>
       instanceId: ${spring.application.name}:${spring.application.instance_id:${random.value}}</pre>
 </div>
 </div>
+<div class="paragraph">
+<p>With this meatdata, and multiple service instances deployed on
+localhost, the random value will kick in there to make the instance
+unique. In Cloudfoundry the <code>spring.application.instance_id</code> will be
+populated automatically in a Spring Boot Actuator application, so the
+random value will not be needed.</p>
+</div>
+</div>
 </div>
 <div class="sect2">
 <h3 id="_using_the_discoveryclient">Using the DiscoveryClient</h3>
@@ -1787,11 +1820,11 @@ public String serviceUrl() {
 </td>
 <td class="content">
 <div class="paragraph">
-<p>Don&#8217;t use the <code>DiscoveryClient</code> in <code>@PostConstruct</code> method (or
-anywhere where the <code>ApplicationContext</code> might not be started yet). It
-is initialized in a <code>SmartLifecycle</code> (with <code>phase=0</code>) so the earliest
-you can rely on it being available is in another <code>SmartLifecycle</code> with
-higher phase.</p>
+<p>Don&#8217;t use the <code>DiscoveryClient</code> in <code>@PostConstruct</code> method or in a
+<code>@Scheduled</code> method (or anywhere where the <code>ApplicationContext</code> might
+not be started yet). It is initialized in a <code>SmartLifecycle</code> (with
+<code>phase=0</code>) so the earliest you can rely on it being available is in
+another <code>SmartLifecycle</code> with higher phase.</p>
 </div>
 </td>
 </tr>
@@ -2296,7 +2329,7 @@ public class FooConfiguration {
 </div>
 </div>
 <div class="sect2">
-<h3 id="_using_the_ribbon_with_eureka">Using the Ribbon with Eureka</h3>
+<h3 id="_using_ribbon_with_eureka">Using Ribbon with Eureka</h3>
 <div class="paragraph">
 <p>When Eureka is used in conjunction with Ribbon the <code>ribbonServerList</code>
 is overridden with an extension of <code>DiscoveryEnabledNIWSServerList</code>
@@ -3340,7 +3373,7 @@ ProxyAuthenticationProperties</a> for full details.</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2015-02-16 09:31:51 UTC
+Last updated 2015-02-16 15:18:08 UTC
 </div>
 </div>
 </body>