From 4754a1e160a4bb00178efc8efdd5b69c700de98d Mon Sep 17 00:00:00 2001
From: Spencer Gibb <spencer@gibb.us>
Date: Fri, 13 Feb 2015 14:45:30 -0700
Subject: [PATCH] an attempt at some sidecar documentation

fixes gh-201
---
 .../main/asciidoc/spring-cloud-netflix.adoc   | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)

diff --git a/docs/src/main/asciidoc/spring-cloud-netflix.adoc b/docs/src/main/asciidoc/spring-cloud-netflix.adoc
index a5c3c157..c2d1c219 100644
--- a/docs/src/main/asciidoc/spring-cloud-netflix.adoc
+++ b/docs/src/main/asciidoc/spring-cloud-netflix.adoc
@@ -824,3 +824,101 @@ still specified by configuring "zuul.routes.*", but there is no service discover
 ----
 
 maps all paths in "/api/**" to the Zuul filter chain.
+
+=== Polyglot support with Sidecar
+
+Do you have non-jvm languages you want to take advantage of Eureka, Ribbon and
+Config Server?  The Spring Cloud Netflix Sidecar was inspired by
+https://github.com/Netflix/Prana[Netflix Prana].  It includes a simple http api
+to get all of the instances (ie host and port) for a given service.  You can
+also proxy service calls through an embedded Zuul proxy which gets its route
+entries from Eureka.  The Spring Cloud Config Server can be accessed directly
+via host lookup or through the Zuul Proxy.  The non-jvm app should implement
+a health check so the Sidecar can report to eureka if the app is up or down.
+
+To enable the Sidecar, create a Spring Boot application with `@EnableSidecar`.
+This annotation includes `@EnableCircuitBreaker`, `@EnableDiscoveryClient`,
+and `@EnableZuulProxy`.  Run the resulting application on the same host as the
+non-jvm application.
+
+To configure the side car add `sidecar.port` and `sidecar.health-uri` to `application.yml`.
+The `sidecar.port` property is the port the non-jvm app is listening on.  This
+is so the Sidecar can properly register the app with Eureka.  The `sidecar.health-uri`
+is a uri accessible on the non-jvm app that mimicks a Spring Boot health
+indicator.  It should return a json document like the following:
+
+.health-uri-document
+[source,json]
+----
+{
+  "status":"UP"
+}
+----
+
+Here is an example application.yml for a Sidecar application:
+
+.application.yml
+[source,yaml]
+----
+server:
+  port: 5678
+spring:
+  application:
+    name: sidecar
+
+sidecar:
+  port: 8000
+  health-uri: http://localhost:8000/health.json
+----
+
+The api for the `DiscoveryClient.getInstances()` method is `/hosts/{serviceId}`.
+Here is an example response for `/hosts/customers` that returns two instances on
+different hosts.  This api is accessible to the non-jvm app (if the sidecar is
+on port 5678) at `http://localhost:5678/hosts/{serviceId}`.
+
+./hosts/customers
+[source,json]
+----
+[
+    {
+        "host": "myhost",
+        "port": 9000,
+        "uri": "http://myhost:9000",
+        "serviceId": "CUSTOMERS",
+        "secure": false
+    },
+    {
+        "host": "myhost2",
+        "port": 9000,
+        "uri": "http://myhost2:9000",
+        "serviceId": "CUSTOMERS",
+        "secure": false
+    }
+]
+----
+
+The Zuul proxy automatically adds routes for each service known in eureka to
+`/<serviceId>`, so the customers service is available at `/customers`.  The
+Non-jvm app can access the customer service via `http://localhost:5678/customers`
+(assuming the sidecar is listening on port 5678).
+
+If the Config Server is registered with Eureka, non-jvm application can access
+it via the Zuul proxy.  If the serviceId of the ConfigServer is `configserver`
+and the Sidecar is on port 5678, then it can be accessed at
+http://localhost:5678/configserver
+
+Non-jvm app can take advantage of the Config Server's ability to return YAML
+documents.  For example, a call to http://sidecar.local.spring.io:5678/configserver/default-master.yml
+might result in a YAML document like the following
+
+[source,yaml]
+----
+eureka:
+  client:
+    serviceUrl:
+      defaultZone: http://localhost:8761/eureka/
+  password: password
+info:
+  description: Spring Cloud Samples
+  url: https://github.com/spring-cloud-samples
+----
\ No newline at end of file