Documentation metadata for 3.3 branch (#10692)

* Update Documentation folder Signed-off-by: lucperkins <[email protected]> * Re-add README file Signed-off-by: lucperkins <[email protected]>
etcd-io · Apr 30, 2019 · c46aa44 · c46aa44
1 parent ad7c2cd
commit c46aa44
Show file tree

Hide file tree

Showing 124 changed files with 3,344 additions and 8,149 deletions.
diff --git a/Documentation/_index.md b/Documentation/_index.md
@@ -0,0 +1,3 @@
+---
+title: etcd version 3.3.12
+---
diff --git a/Documentation/benchmarks/README.md b/Documentation/benchmarks/README.md
diff --git a/Documentation/benchmarks/_index.md b/Documentation/benchmarks/_index.md
@@ -0,0 +1,3 @@
+---
+title: Benchmarks
+---
diff --git a/Documentation/benchmarks/etcd-2-1-0-alpha-benchmarks.md b/Documentation/benchmarks/etcd-2-1-0-alpha-benchmarks.md
@@ -1,3 +1,7 @@
+---
+title: Benchmarking etcd v2.1.0
+---
+
 ## Physical machines
 
 GCE n1-highcpu-2 machine type

diff --git a/Documentation/benchmarks/etcd-2-2-0-benchmarks.md b/Documentation/benchmarks/etcd-2-2-0-benchmarks.md
@@ -1,4 +1,6 @@
-# Benchmarking etcd v2.2.0
+---
+title: Benchmarking etcd v2.2.0
+---
 
 ## Physical Machines
 
@@ -26,7 +28,7 @@ Go OS/Arch: linux/amd64
 
 Bootstrap another machine, outside of the etcd cluster, and run the [`hey` HTTP benchmark tool](https://github.com/rakyll/hey) with a connection reuse patch to send requests to each etcd cluster member. See the [benchmark instructions](../../hack/benchmark/) for the patch and the steps to reproduce our procedures.
 
-The performance is calulated through results of 100 benchmark rounds.
+The performance is calculated through results of 100 benchmark rounds.
 
 ## Performance
 

diff --git a/Documentation/benchmarks/etcd-2-2-0-rc-benchmarks.md b/Documentation/benchmarks/etcd-2-2-0-rc-benchmarks.md
@@ -1,4 +1,8 @@
-## Physical machines
+---
+title: Benchmarking etcd v2.2.0-rc
+---
+
+## Physical machine
 
 GCE n1-highcpu-2 machine type
 

diff --git a/Documentation/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md b/Documentation/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md
@@ -1,3 +1,7 @@
+---
+title: Benchmarking etcd v2.2.0-rc-memory
+---
+
 ## Physical machine
 
 GCE n1-standard-2 machine type

diff --git a/Documentation/benchmarks/etcd-3-demo-benchmarks.md b/Documentation/benchmarks/etcd-3-demo-benchmarks.md
@@ -1,3 +1,7 @@
+---
+title: Benchmarking etcd v3
+---
+
 ## Physical machines
 
 GCE n1-highcpu-2 machine type

diff --git a/Documentation/benchmarks/etcd-3-watch-memory-benchmark.md b/Documentation/benchmarks/etcd-3-watch-memory-benchmark.md
@@ -1,4 +1,6 @@
-# Watch Memory Usage Benchmark
+---
+title: Watch Memory Usage Benchmark
+---
 
 *NOTE*: The watch features are under active development, and their memory usage may change as that development progresses. We do not expect it to significantly increase beyond the figures stated below.
 

diff --git a/Documentation/benchmarks/etcd-storage-memory-benchmark.md b/Documentation/benchmarks/etcd-storage-memory-benchmark.md
@@ -1,4 +1,6 @@
-# Storage Memory Usage Benchmark
+---
+title: Storage Memory Usage Benchmark
+---
 
 <!---todo: link storage to storage design doc-->
 Two components of etcd storage consume physical memory. The etcd process allocates an *in-memory index* to speed key lookup. The process's *page cache*, managed by the operating system, stores recently-accessed data from disk for quick re-use.

diff --git a/Documentation/branch_management.md b/Documentation/branch_management.md
@@ -1,4 +1,6 @@
-# Branch management
+---
+title: Branch management
+---
 
 ## Guide
 

diff --git a/Documentation/demo.md b/Documentation/demo.md
@@ -1,4 +1,6 @@
-# Demo
+---
+title: Demo
+---
 
 This series of examples shows the basic procedures for working with an etcd cluster.
 

diff --git a/Documentation/dev-guide/_index.md b/Documentation/dev-guide/_index.md
@@ -0,0 +1,3 @@
+---
+title: Developer guide
+---
diff --git a/Documentation/dev-guide/api_concurrency_reference_v3.md b/Documentation/dev-guide/api_concurrency_reference_v3.md
@@ -1,4 +1,6 @@
-### etcd concurrency API Reference
+---
+title: etcd concurrency API Reference
+---
 
 
 This is a generated documentation. Please read the proto files for more.
@@ -20,7 +22,7 @@ The lock service exposes client-side locking facilities as a gRPC interface.
 | Field | Description | Type |
 | ----- | ----------- | ---- |
 | name | name is the identifier for the distributed shared lock to be acquired. | bytes |
-| lease | lease is the ID of the lease that will be attached to ownership of the lock. If the lease expires or is revoked and currently holds the lock, the lock is automatically released. Calls to Lock with the same lease will be treated as a single acquistion; locking twice with the same lease is a no-op. | int64 |
+| lease | lease is the ID of the lease that will be attached to ownership of the lock. If the lease expires or is revoked and currently holds the lock, the lock is automatically released. Calls to Lock with the same lease will be treated as a single acquisition; locking twice with the same lease is a no-op. | int64 |
 
 
 

diff --git a/Documentation/dev-guide/api_grpc_gateway.md b/Documentation/dev-guide/api_grpc_gateway.md
@@ -1,16 +1,29 @@
+---
+title: Why gRPC gateway
+---
 
-## Why grpc-gateway
+etcd v3 uses [gRPC][grpc] for its messaging protocol. The etcd project includes a gRPC-based [Go client][go-client] and a command line utility, [etcdctl][etcdctl], for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON [gRPC gateway][grpc-gateway]. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.
 
-etcd v3 uses [gRPC][grpc] for its messaging protocol. The etcd project includes a gRPC-based [Go client][go-client] and a command line utility, [etcdctl][etcdctl], for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON [grpc-gateway][grpc-gateway]. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.
+## Using gRPC gateway
 
+The gateway accepts a [JSON mapping][json-mapping] for etcd's [protocol buffer][api-ref] message definitions. Note that `key` and `value` fields are defined as byte arrays and therefore must be base64 encoded in JSON. The following examples use `curl`, but any HTTP/JSON client should work all the same.
 
-## Using grpc-gateway
+### Notes
 
-The gateway accepts a [JSON mapping][json-mapping] for etcd's [protocol buffer][api-ref] message definitions. Note that `key` and `value` fields are defined as byte arrays and therefore must be base64 encoded in JSON. The following examples use `curl`, but any HTTP/JSON client should work all the same.
+gRPC gateway endpoint has changed since etcd v3.3:
+
+- etcd v3.2 or before uses only `[CLIENT-URL]/v3alpha/*`.
+- etcd v3.3 uses `[CLIENT-URL]/v3beta/*` while keeping `[CLIENT-URL]/v3alpha/*`.
+- etcd v3.4 uses `[CLIENT-URL]/v3/*` while keeping `[CLIENT-URL]/v3beta/*`.
+  - **`[CLIENT-URL]/v3alpha/*` is deprecated**.
+- etcd v3.5 or later uses only `[CLIENT-URL]/v3/*`.
+  - **`[CLIENT-URL]/v3beta/*` is deprecated**.
+
+gRPC-gateway does not support authentication using TLS Common Name.
 
 ### Put and get keys
 
-Use the `/v3beta/kv/range` and `/v3beta/kv/put` services to read and write keys:
+Use the `/v3/kv/range` and `/v3/kv/put` services to read and write keys:
 
 ```bash
 <<COMMENT
@@ -19,85 +32,94 @@ foo is 'Zm9v' in Base64
 bar is 'YmFy'
 COMMENT
 
-curl -L http://localhost:2379/v3beta/kv/put \
-	-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
+curl -L http://localhost:2379/v3/kv/put \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}}
 
-curl -L http://localhost:2379/v3beta/kv/range \
-	-X POST -d '{"key": "Zm9v"}'
+curl -L http://localhost:2379/v3/kv/range \
+  -X POST -d '{"key": "Zm9v"}'
 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}
 
 # get all keys prefixed with "foo"
-curl -L http://localhost:2379/v3beta/kv/range \
-	-X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'
+curl -L http://localhost:2379/v3/kv/range \
+  -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}'
 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"}
 ```
 
 ### Watch keys
 
-Use the `/v3beta/watch` service to watch keys:
+Use the `/v3/watch` service to watch keys:
 
 ```bash
-curl http://localhost:2379/v3beta/watch \
-        -X POST -d '{"create_request": {"key":"Zm9v"} }' &
+curl -N http://localhost:2379/v3/watch \
+  -X POST -d '{"create_request": {"key":"Zm9v"} }' &
 # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}}
 
-curl -L http://localhost:2379/v3beta/kv/put \
-	-X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1
+curl -L http://localhost:2379/v3/kv/put \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1
 # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"2"},"events":[{"kv":{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}}]}}
 ```
 
 ### Transactions
 
-Issue a transaction with `/v3beta/kv/txn`:
+Issue a transaction with `/v3/kv/txn`:
 
 ```bash
-curl -L http://localhost:2379/v3beta/kv/txn \
-	-X POST \
-	-d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'
+# target CREATE
+curl -L http://localhost:2379/v3/kv/txn \
+  -X POST \
+  -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}'
 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]}
 ```
 
+```bash
+# target VERSION
+curl -L http://localhost:2379/v3/kv/txn \
+  -X POST \
+  -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}'
+# {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"6","raft_term":"3"},"succeeded":true,"responses":[{"response_range":{"header":{"revision":"6"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"6","version":"4","value":"YmF6"}],"count":"1"}}]}
+```
+
 ### Authentication
 
-Set up authentication with the `/v3beta/auth` service:
+Set up authentication with the `/v3/auth` service:
 
 ```bash
 # create root user
-curl -L http://localhost:2379/v3beta/auth/user/add \
-	-X POST -d '{"name": "root", "password": "pass"}'
+curl -L http://localhost:2379/v3/auth/user/add \
+  -X POST -d '{"name": "root", "password": "pass"}'
 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
 
 # create root role
-curl -L http://localhost:2379/v3beta/auth/role/add \
-	-X POST -d '{"name": "root"}'
+curl -L http://localhost:2379/v3/auth/role/add \
+  -X POST -d '{"name": "root"}'
 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
 
 # grant root role
-curl -L http://localhost:2379/v3beta/auth/user/grant \
-	-X POST -d '{"user": "root", "role": "root"}'
+curl -L http://localhost:2379/v3/auth/user/grant \
+  -X POST -d '{"user": "root", "role": "root"}'
 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
 
 # enable auth
-curl -L http://localhost:2379/v3beta/auth/enable -X POST -d '{}'
+curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}'
 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}}
 ```
 
-Authenticate with etcd for an authentication token using `/v3beta/auth/authenticate`:
+Authenticate with etcd for an authentication token using `/v3/auth/authenticate`:
 
 ```bash
 # get the auth token for the root user
-curl -L http://localhost:2379/v3beta/auth/authenticate \
-	-X POST -d '{"name": "root", "password": "pass"}'
+curl -L http://localhost:2379/v3/auth/authenticate \
+  -X POST -d '{"name": "root", "password": "pass"}'
 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"}
 ```
 
 Set the `Authorization` header to the authentication token to fetch a key using authentication credentials:
 
 ```bash
-curl -L http://localhost:2379/v3beta/kv/put \
-	-H 'Authorization : sssvIpwfnLAcWAQH.9' \
-	-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
+curl -L http://localhost:2379/v3/kv/put \
+  -H 'Authorization : sssvIpwfnLAcWAQH.9' \
+  -X POST -d '{"key": "Zm9v", "value": "YmFy"}'
 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}}
 ```
 
@@ -108,9 +130,8 @@ Generated [Swagger][swagger] API definitions can be found at [rpc.swagger.json][
 [api-ref]: ./api_reference_v3.md
 [go-client]: https://github.com/coreos/etcd/tree/master/clientv3
 [etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl
-[grpc]: http://www.grpc.io/
+[grpc]: https://www.grpc.io/
 [grpc-gateway]: https://github.com/grpc-ecosystem/grpc-gateway
 [json-mapping]: https://developers.google.com/protocol-buffers/docs/proto3#json
 [swagger]: http://swagger.io/
 [swagger-doc]: apispec/swagger/rpc.swagger.json
-