added lb diagram and some more detail

1 files changed, 59 insertions, 14 deletions

diff --git a/doc/load-balancing.md b/doc/load-balancing.md
index 681be02a72..05d555a3f1 100644
--- a/doc/load-balancing.md
+++ b/doc/load-balancing.md
@@ -4,7 +4,7 @@ Load Balancing in gRPC
 # Objective
 
 To design a load balancing API between a gRPC client and a Load Balancer to
-instruct the client how to send load to multiple backend servers. 
+instruct the client how to send load to multiple backend servers.
 
 # Background
 
@@ -19,7 +19,7 @@ have temporary copies of the RPC request and response. This model also increases
 latency to the RPCs.
 
 The proxy model was deemed inefficient when considering request heavy services
-like storage. 
+like storage.
 
 ### Balancing-aware Client
 
@@ -28,7 +28,7 @@ example, the client could contain many load balancing policies (Round Robin,
 Random, etc) used to select servers from a list. In this model, a list of
 servers would be either statically configured in the client, provided by the
 name resolution system, an external load balancer, etc. In any case, the client
-is responsible for choosing the preferred server from the list. 
+is responsible for choosing the preferred server from the list.
 
 One of the drawbacks of this approach is writing and maintaining the load
 balancing policies in multiple languages and/or versions of the clients. These
@@ -53,14 +53,67 @@ unavailability or health issues. The load balancer will make any necessary
 complex decisions and inform the client. The load balancer may communicate with
 the backend servers to collect load and health information.
 
+
+## Requirements
+
+#### Simple API and client
+
+The gRPC client load balancing code must be simple and portable. The client
+should only contain simple algorithms (ie Round Robin) for server selection. For
+complex algorithms, the client should rely on a load balancer to provide load
+balancing configuration and the list of servers to which the client should send
+requests. The balancer will update the server list as needed to balance the load
+as well as handle server unavailability or health issues. The load balancer will
+make any necessary complex decisions and inform the client. The load balancer
+may communicate with the backend servers to collect load and health information.
+
+#### Security
+
+The load balancer may be separate from the actual server backends and a
+compromise of the load balancer should only lead to a compromise of the
+loadbalancing functionality. In other words, a compromised load balancer should
+not be able to cause a client to trust a (potentially malicious) backend server
+any more than in a comparable situation without loadbalancing.
+
 # Proposed Architecture
 
-The gRPC load balancing approach follows the third approach, by having an
-external load balancer which provides simple clients with a list of servers.
+The gRPC load balancing implements the external load balancing server approach:
+an external load balancer provides simple clients with an up-to-date list of
+servers.
+
+![image](images/load_balancing_design.png)
+
+1. On startup, the gRPC client issues a name resolution request for the service.
+   The name will resolve to one or more IP addresses to gRPC servers, a hint on
+   whether the IP address(es) point to a load balancer or not, and also return a
+   client config.
+2. The gRPC client connects to a gRPC Server.
+   1. If the name resolution has hinted that the endpoint is a load balancer,
+      the client will attempt to open a stream to the load balancer service. The
+      server may respond in only one of the following ways.
+      1. `status::UNIMPLEMENTED`. There is no loadbalancing in use. The client
+         proceeds by sending all RPCs to this gRPC server.
+      1. "I am a Load Balancer and here is the server list." (Goto Step 4.)
+      1. "Please contact Load Balancer X" (See Step 3.) The client will close
+         this connection and cancel the stream.
+      1. If the server fails to respond, the client will wait for some timeout
+         and then re-resolve the name (process to Step 1 above).
+   1. If the name resolution has not hinted that the endpoint is a load
+      balancer, the client connects directly to the service it wants to talk to.
+3. The gRPC client opens a separate connection to the Load Balancer. If this
+   fails, it will go back to step 1 and try another address.
+   1. During channel initialization to the Load Balancer, the client will
+      attempt to open a stream to the Load Balancer service.
+   1. The load balancer will return a server list to the gRPC client.
+      Optional: The load balancer will also open channels to the gRPC servers if
+      load reporting is needed.
+4. The gRPC client will send RPCs to the gRPC servers contained in the server
+   list from the load balancer.
+5. Optional: The gRPC servers may periodically report load to the Load Balancer.
 
 ## Client
 
-When establishing a gRPC stream to the balancer, the client will send an initial
+When establishing a gRPC _stream_ to the balancer, the client will send an initial
 request to the load balancer (via a regular gRPC message). The load balancer
 will respond with client config (including, for example, settings for flow
 control, RPC deadlines, etc.) or a redirect to another load balancer. If the
@@ -87,11 +140,3 @@ balancer in order to compute the next list of servers.
 The gRPC Server is responsible for answering RPC requests and providing
 responses to the client. The server will also report load to the load balancer
 if a reporting stream was opened for this purpose.
-
-### Security 
-
-The load balancer may be separate from the actual server backends and a
-compromise of the load balancer should only lead to a compromise of the
-loadbalancing functionality. In other words, a compromised load balancer should
-not be able to cause a client to trust a (potentially malicious) backend server
-any more than in a comparable situation without loadbalancing.