Finish docs.

2 files changed, 19 insertions, 103 deletions

diff --git a/doc/load-balancing.md b/doc/load-balancing.md
index 03c9bd2cba..4ed938c990 100644
--- a/doc/load-balancing.md
+++ b/doc/load-balancing.md
@@ -11,7 +11,7 @@ instruct the client how to send load to multiple backend servers.
 Prior to any gRPC specifics, we explore some usual ways to approach load
 balancing.
 
-### Proxy Model
+## Proxy Model
 
 Using a proxy provides a solid trustable client that can report load to the load
 balancing system. Proxies typically require more resources to operate since they
@@ -21,7 +21,7 @@ latency to the RPCs.
 The proxy model was deemed inefficient when considering request heavy services
 like storage.
 
-### Balancing-aware Client
+## Balancing-aware Client
 
 This thicker client places more of the load balancing logic in the client. For
 example, the client could contain many load balancing policies (Round Robin,
@@ -41,7 +41,7 @@ It would also significantly complicate the client's code: the new design hides
 the load balancing complexity of multiple layers and presents it as a simple
 list of servers to the client.
 
-### External Load Balancing Service
+## External Load Balancing Service
 
 The client load balancing code is kept simple and portable, implementing
 well-known algorithms (e.g., Round Robin) for server selection.
@@ -56,7 +56,7 @@ servers to collect load and health information.
 
 # Requirements
 
-### Simple API and client
+## Simple API and client
 
 The gRPC client load balancing code must be simple and portable. The
 client should only contain simple algorithms (e.g., Round Robin) for
@@ -68,7 +68,7 @@ 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
+## 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
@@ -90,13 +90,13 @@ However, there are only a small number of these (one of which is the
 are discouraged from trying to extend gRPC by adding more.  Instead, new
 load balancing policies should be implemented in external load balancers.
 
-## Load Balancing Policies
+## Workflow
 
 Load-balancing policies fit into the gRPC client workflow in between
 name resolution and the connection to the server.  Here's how it all
 works:
 
-![image](images/load_balancing_design.png)
+![image](images/load-balancing.svg)
 
 1. On startup, the gRPC client issues a [name resolution](naming.md) request
    for the server name.  The name will resolve to one or more IP addresses,
@@ -130,33 +130,3 @@ works:
    received.
 6. The gRPC client will send RPCs to the gRPC servers contained in
    the server list from the Load Balancer.
-
-## Client
-
-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
-balancer did not redirect the client, it will then send a list of servers to the
-client. The client will contain simple load balancing logic for choosing the
-next server when it needs to send a request.
-
-## Load Balancer
-
-The Load Balancer is responsible for providing the client with a list of servers
-and client RPC parameters. The balancer chooses when to update the list of
-servers and can decide whether to provide a complete list, a subset, or a
-specific list of “picked” servers in a particular order. The balancer can
-optionally provide an expiration interval after which the server list should no
-longer be trusted and should be updated by the balancer.
-
-The load balancer may open reporting streams to each server contained in the
-server list. These streams are primarily used for load reporting. For example,
-Weighted Round Robin requires that the servers report utilization to the load
-balancer in order to compute the next list of servers.
-
-## Server
-
-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.
diff --git a/doc/service_config.md b/doc/service_config.md
index 6093fc3445..7318b69f21 100644
--- a/doc/service_config.md
+++ b/doc/service_config.md
@@ -123,6 +123,9 @@ The service config is a JSON string of the following form:
 }
 ```
 
+Note that new per-method parameters may be added in the future as new
+functionality is introduced.
+
 # Architecture
 
 A service config is associated with a server name.  The [name
@@ -131,71 +134,14 @@ name, will return both the resolved addresses and the service config.
 
 TODO(roth): Design how the service config will be encoded in DNS.
 
+# APIs
 
+The service config is used in the following APIs:
 
-
-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's gRPC LB policy 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
-         call will fail.
-      2. "I am a Load Balancer and here is the server list." (Goto Step 4.)
-      3. "Please contact Load Balancer X" (See Step 3.) The client will close
-         this connection and cancel the stream.
-      4. If the server fails to respond, the client will wait for some timeout
-         and then re-resolve the name (process to Step 1 above).
-   2. 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's gRPC LB policy 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.
-   2. The Load Balancer will return a server list to the gRPC client. If the
-      server list is empty, the call will wait until a non-empty one is
-      received. 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
-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
-balancer did not redirect the client, it will then send a list of servers to the
-client. The client will contain simple load balancing logic for choosing the
-next server when it needs to send a request.
-
-## Load Balancer
-
-The Load Balancer is responsible for providing the client with a list of servers
-and client RPC parameters. The balancer chooses when to update the list of
-servers and can decide whether to provide a complete list, a subset, or a
-specific list of “picked” servers in a particular order. The balancer can
-optionally provide an expiration interval after which the server list should no
-longer be trusted and should be updated by the balancer.
-
-The load balancer may open reporting streams to each server contained in the
-server list. These streams are primarily used for load reporting. For example,
-Weighted Round Robin requires that the servers report utilization to the load
-balancer in order to compute the next list of servers.
-
-## Server
-
-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.
+- In the resolver API, used by resolver plugins to return the service
+  config to the gRPC client.
+- In the gRPC client API, where users can query the channel to obtain
+  the service config associated with the channel (for debugging
+  purposes).
+- In the gRPC client API, where users can set the service config
+  explicitly.  This is intended for use in unit tests.