From 17a6025ac891e2a43ea1c10b2db0b63415dec228 Mon Sep 17 00:00:00 2001
From: Xiang Li <xiangli.cs@gmail.com>
Date: Tue, 11 Oct 2016 10:50:40 -0700
Subject: [PATCH] doc: add grpc proxy doc

---
 Documentation/docs.md                |  2 ++
 Documentation/op-guide/grpc_proxy.md | 49 ++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 Documentation/op-guide/grpc_proxy.md

diff --git a/Documentation/docs.md b/Documentation/docs.md
index ebe7ad596..36dfd4c17 100644
--- a/Documentation/docs.md
+++ b/Documentation/docs.md
@@ -23,6 +23,7 @@ Administrators who need to create reliable and scalable key-value stores for the
 
  - [Setting up etcd clusters][clustering]
  - [Setting up etcd gateways][gateway]
+ - [Setting up etcd gRPC proxy (pre-alpha)][grpc_proxy]
  - [Run etcd clusters inside containers][container]
  - [Configuration][conf]
  - [Security][security]
@@ -62,6 +63,7 @@ To learn more about the concepts and internals behind etcd, read the following p
 [failures]: op-guide/failures.md
 [gateway]: op-guide/gateway.md
 [glossary]: learning/glossary.md
+[grpc_proxy]: op-guide/grpc_proxy.md
 [interacting]: dev-guide/interacting_v3.md
 [local_cluster]: dev-guide/local_cluster.md
 [performance]: op-guide/performance.md
diff --git a/Documentation/op-guide/grpc_proxy.md b/Documentation/op-guide/grpc_proxy.md
new file mode 100644
index 000000000..44988d03c
--- /dev/null
+++ b/Documentation/op-guide/grpc_proxy.md
@@ -0,0 +1,49 @@
+# gRPC proxy
+
+*This is a pre-alpha feature, we are looking for early feedback.*
+
+The gRPC proxy is a stateless etcd reverse proxy operating at the gRPC layer (L7). The proxy is designed to reduce the total processing load on the core etcd cluster. For horizontal scalability, it coalesces watch and lease API requests. To protect the cluster against abusive clients, it caches key range requests.
+
+The gRPC proxy supports multiple etcd server endpoints. When the proxy starts, it randomly picks one etcd server endpoint to use. This endpoint serves all requests until the proxy detects an endpoint failure. If the gRPC proxy detects an endpoint failure, it switches to a different endpoint, if available, to hide failures from its clients. Other retry policies, such as weighted round-robin, may be supported in the future.
+
+## Scalable watch API
+
+The gRPC proxy coalesces multiple client watchers (`c-watchers`) on the same key or range into a single watcher (`s-watcher`) connected to an etcd server. The proxy broadcasts all events from the `s-watcher` to its `c-watchers`.
+
+Assuming N clients watch the same key, one gRPC proxy can reduce the watch load on the etcd server from N to 1. Users can deploy multiple gRPC proxies to further distribute server load.
+
+In the following example, three clients watch on key A. The gRPC proxy coalesces the three watchers, creating a single  watcher attached to the etcd server.
+
+```
+            +-------------+
+            | etcd server |
+            +------+------+
+                   ^ watch key A (s-watcher)
+                   |
+           +-------+-----+
+           | gRPC proxy  | <-------+
+           |             |         |
+           ++-----+------+         |watch key A (c-watcher)
+watch key A ^     ^ watch key A    |
+(c-watcher) |     | (c-watcher)    |
+    +-------+-+  ++--------+  +----+----+
+    |  client |  |  client |  |  client |
+    |         |  |         |  |         |
+    +---------+  +---------+  +---------+
+```
+
+### Limitations
+
+To effectively coalesce multiple client watchers into a single watcher, the gRPC proxy coalesces new `c-watchers` into an existing `s-watcher` when possible. This coalesced `s-watcher` may be out of sync with the etcd server due to network delays or buffered undelivered events. When the watch revision is unspecified, the gRPC proxy will not guarantee the `c-watcher` will start watching from the most recent store revision. For example, if a client watches from an etcd server with revision 1000, that watcher will begin at revision 1000. If a client watches from the gRPC proxy, may begin watching from revision 990.
+
+Similar limitations apply to cancellation. When the watcher is cancelled, the etcd server’s revision may be greater than the cancellation response revision. 
+
+These two limitations should not cause problems for most use cases. In the future, there may be additional options to force the watcher to bypass the gRPC proxy for more accurate revision responses. 
+
+## Scalable lease API
+
+TODO
+
+## Abusive clients protection
+
+The gRPC proxy caches responses for requests when it does not break consistency requirements. This can protect the etcd server from abusive clients in tight for loops.