Documentation, op-guide, clientv3: add documentation for namespacing

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

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
+```

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).