Merge pull request #8378 from heyitsanthony/doc-tls-termination

op-guide: TLS termination with grpc-proxy

Documentation/op-guide/grpc_proxy.md

@@ -90,9 +90,9 @@ The etcd gRPC proxy starts and listens on port 8080. It forwards client requests
 Sending requests through the proxy:
 
 ```bash
-$ ETCDCTL_API=3 ./etcdctl --endpoints=127.0.0.1:2379 put foo bar
+$ ETCDCTL_API=3 etcdctl --endpoints=127.0.0.1:2379 put foo bar
 OK
-$ ETCDCTL_API=3 ./etcdctl --endpoints=127.0.0.1:2379 get foo
+$ ETCDCTL_API=3 etcdctl --endpoints=127.0.0.1:2379 get foo
 foo
 bar
 ```
@@ -120,7 +120,7 @@ $ etcd grpc-proxy start --endpoints=localhost:2379 \
 The proxy will list all its members for member list:
 
 ```bash
-ETCDCTL_API=3 ./bin/etcdctl --endpoints=http://localhost:23790 member list --write-out table
+ETCDCTL_API=3 etcdctl --endpoints=http://localhost:23790 member list --write-out table
 
 +----+---------+--------------------------------+------------+-----------------+
 | ID | STATUS  |              NAME              | PEER ADDRS |  CLIENT ADDRS   |
@@ -155,10 +155,10 @@ $ etcd grpc-proxy start --endpoints=localhost:2379 \
   --advertise-client-url=127.0.0.1:23792
 ```
 
-the member list API to the grpc-proxy returns its own `advertise-client-url`:
+The member list API to the grpc-proxy returns its own `advertise-client-url`:
 
 ```bash
-ETCDCTL_API=3 ./bin/etcdctl --endpoints=http://localhost:23792 member list --write-out table
+ETCDCTL_API=3 etcdctl --endpoints=http://localhost:23792 member list --write-out table
 
 +----+---------+--------------------------------+------------+-----------------+
 | ID | STATUS  |              NAME              | PEER ADDRS |  CLIENT ADDRS   |
@@ -182,12 +182,44 @@ $ etcd grpc-proxy start --endpoints=localhost:2379 \
 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
+$ ETCDCTL_API=3 etcdctl --endpoints=localhost:23790 put my-key abc
 # OK
-$ ETCDCTL_API=3 ./bin/etcdctl --endpoints=localhost:23790 get my-key
+$ ETCDCTL_API=3 etcdctl --endpoints=localhost:23790 get my-key
 # my-key
 # abc
-$ ETCDCTL_API=3 ./bin/etcdctl --endpoints=localhost:2379 get my-prefix/my-key
+$ ETCDCTL_API=3 etcdctl --endpoints=localhost:2379 get my-prefix/my-key
 # my-prefix/my-key
 # abc
 ```
+
+## TLS termination
+
+Terminate TLS from a secure etcd cluster with the grpc proxy by serving an unencrypted local endpoint.
+
+To try it out, start a single member etcd cluster with client https:
+
+```sh
+$ etcd --listen-client-urls https://localhost:2379 --advertise-client-urls https://localhost:2379 --cert-file=peer.crt --key-file=peer.key --trusted-ca-file=ca.crt --client-cert-auth
+```
+
+Confirm the client port is serving https:
+
+```sh
+# fails
+$ ETCDCTL_API=3 etcdctl --endpoints=http://localhost:2379 endpoint status
+# works
+$ ETCDCTL_API=3 etcdctl --endpoints=https://localhost:2379 --cert=client.crt --key=client.key --cacert=ca.crt endpoint status
+```
+
+Next, start a grpc proxy on `localhost:12379` by connecting to the etcd endpoint `https://localhost:2379` using the client certificates:
+
+```sh
+$ etcd grpc-proxy start --endpoints=https://localhost:2379 --listen-addr localhost:12379 --cert client.crt --key client.key --cacert=ca.crt --insecure-skip-tls-verify &
+```
+
+Finally, test the TLS termination by putting a key into the proxy over http:
+
+```sh
+$ ETCDCTL_API=3 etcdctl --endpoints=http://localhost:12379 put abc def
+# OK
+```