From 85f989ab3d4d30a1305bf68715e7b4c74fb36135 Mon Sep 17 00:00:00 2001
From: Anthony Romano <anthony.romano@coreos.com>
Date: Tue, 21 Mar 2017 12:15:07 -0700
Subject: [PATCH] Documentation, op-guide, clientv3: add documentation for
 namespacing

---
 Documentation/docs.md                |  5 ++++-
 Documentation/op-guide/grpc_proxy.md | 25 +++++++++++++++++++++++++
 clientv3/README.md                   |  4 ++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/Documentation/docs.md b/Documentation/docs.md
index 63279c305..890323d73 100644
--- a/Documentation/docs.md
+++ b/Documentation/docs.md
@@ -15,6 +15,7 @@ The easiest way to get started using etcd as a distributed key-value store is to
  - [gRPC API references][api_ref]
  - [HTTP JSON API through the gRPC gateway][api_grpc_gateway]
  - [gRPC naming and discovery][grpc_naming]
+ - [Client][namespace_client] and [proxy][namespace_proxy] namespacing
  - [Embedding etcd][embed_etcd]
  - [Experimental features and APIs][experimental]
  - [System limits][system-limit]
@@ -25,7 +26,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]
+ - [Setting up etcd gRPC proxy][grpc_proxy]
  - [Run etcd clusters inside containers][container]
  - [Hardware recommendations][hardware]
  - [Configuration][conf]
@@ -74,6 +75,8 @@ Answers to [common questions] about etcd.
 [failures]: op-guide/failures.md
 [gateway]: op-guide/gateway.md
 [glossary]: learning/glossary.md
+[namespace_client]: https://godoc.org/github.com/coreos/etcd/clientv3/namespace
+[namespace_proxy]: op-guide/grpc_proxy.md#namespacing
 [grpc_proxy]: op-guide/grpc_proxy.md
 [hardware]: op-guide/hardware.md
 [interacting]: dev-guide/interacting_v3.md
diff --git a/Documentation/op-guide/grpc_proxy.md b/Documentation/op-guide/grpc_proxy.md
index bc5c227fd..670aa68a1 100644
--- a/Documentation/op-guide/grpc_proxy.md
+++ b/Documentation/op-guide/grpc_proxy.md
@@ -168,3 +168,28 @@ ETCDCTL_API=3 ./bin/etcdctl --endpoints=http://localhost:23792 member list --wri
 |  0 | started | Gyu-Hos-MBP.sfo.coreos.systems |            | 127.0.0.1:23792 |
 +----+---------+--------------------------------+------------+-----------------+
 ```
+
+## Namespacing
+
+Suppose an application expects full control over the entire key space, but the etcd cluster is shared with other applications. To let all appications run without interfering with each other, the proxy can partition the etcd keyspace so clients appear to have access to the complete keyspace. When the proxy is given the flag `--namespace`, all client requests going into the proxy are translated to have a user-defined prefix on the keys. Accesses to the etcd cluster will be under the prefix and responses from the proxy will strip away the prefix; to the client, it appears as if there is no prefix at all.
+
+To namespace a proxy, start it with `--namespace`:
+
+```bash
+$ etcd grpc-proxy start --endpoints=localhost:2379 \
+  --listen-addr=127.0.0.1:23790 \
+  --namespace=my-prefix/
+```
+
+Accesses to the proxy are now transparently prefixed on the etcd cluster:
+
+```bash
+$ ETCDCTL_API=3 ./bin/etcdctl --endpoints=localhost:23790 put my-key abc
+# OK
+$ ETCDCTL_API=3 ./bin/etcdctl --endpoints=localhost:23790 get my-key
+# my-key
+# abc
+$ ETCDCTL_API=3 ./bin/etcdctl --endpoints=localhost:2379 get my-prefix/my-key
+# my-prefix/my-key
+# abc
+```
diff --git a/clientv3/README.md b/clientv3/README.md
index f135b9a7d..643d0e2f0 100644
--- a/clientv3/README.md
+++ b/clientv3/README.md
@@ -76,6 +76,10 @@ if err != nil {
 
 The etcd client optionally exposes RPC metrics through [go-grpc-prometheus](https://github.com/grpc-ecosystem/go-grpc-prometheus). See the [examples](https://github.com/coreos/etcd/blob/master/clientv3/example_metrics_test.go).
 
+## Namespacing
+
+The [namespace](https://godoc.org/github.com/coreos/etcd/clientv3/namespace) package provides `clientv3` interface wrappers to transparently isolate client requests to a user-defined prefix.
+
 ## Examples
 
 More code examples can be found at [GoDoc](https://godoc.org/github.com/coreos/etcd/clientv3).