content: add v3.4.0 documentation

Signed-off-by: Gyuho Lee <[email protected]>
ksa-real · Aug 30, 2019 · 1546314 · 1546314
1 parent 337b4d4
commit 1546314
Show file tree

Hide file tree

Showing 207 changed files with 58,839 additions and 2 deletions.
diff --git a/config.toml b/config.toml
@@ -36,8 +36,8 @@ Latency from the etcd leader is the most important metric to track and the built
 """
 
 [params.versions]
-latest = "3.3.12"
-all    = ["3.3.12", "3.2.17", "3.1.12"]
+latest = "3.4.0"
+all    = ["3.4.0", "3.3.12", "3.2.17", "3.1.12"]
 
 [params.logos]
 hero   = "https://raw.githubusercontent.com/cncf/artwork/master/projects/etcd/horizontal/white/etcd-horizontal-white.png"

diff --git a/content/docs/v3.4.0/README.md b/content/docs/v3.4.0/README.md
@@ -0,0 +1,118 @@
+# Documentation
+
+etcd is a distributed key-value store designed to reliably and quickly preserve and provide access to critical data. It enables reliable distributed coordination through distributed locking, leader elections, and write barriers. An etcd cluster is intended for high availability and permanent data storage and retrieval.
+
+## Getting started
+
+New etcd users and developers should get started by [downloading and building][download_build] etcd. After getting etcd, follow this [quick demo][demo] to see the basics of creating and working with an etcd cluster.
+
+## Developing with etcd
+
+The easiest way to get started using etcd as a distributed key-value store is to [set up a local cluster][local_cluster].
+
+ - [Setting up local clusters][local_cluster]
+ - [Interacting with etcd][interacting]
+ - gRPC [etcd core][api_ref] and [etcd concurrency][api_concurrency_ref] API references
+ - [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]
+
+## Operating etcd clusters
+
+Administrators who need a fault-tolerant etcd cluster for either development or production should begin with a [cluster on multiple machines][clustering].
+
+### Setting up etcd
+
+ - [Configuration flags][conf]
+ - [Multi-member cluster][clustering]
+ - [gRPC proxy][grpc_proxy]
+ - [L4 gateway][gateway]
+
+### System configuration
+
+ - [Supported systems][supported_platforms]
+ - [Hardware recommendations][hardware]
+ - [Performance benchmarking][performance]
+ - [Tuning][tuning]
+
+### Platform guides
+
+ - [Amazon Web Services][aws_platform]
+ - [Container Linux, systemd][container_linux_platform]
+ - [FreeBSD][freebsd_platform]
+ - [Docker container][container_docker]
+ - [rkt container][container_rkt]
+
+### Security
+
+ - [TLS][security]
+ - [Role-based access control][authentication]
+
+### Maintenance and troubleshooting
+
+ - [Frequently asked questions][faq]
+ - [Monitoring][monitoring]
+ - [Maintenance][maintenance]
+ - [Failure modes][failures]
+ - [Disaster recovery][recovery]
+ - [Upgrading][upgrading]
+
+## Learning
+
+To learn more about the concepts and internals behind etcd, read the following pages:
+
+ - [Why etcd?][why]
+ - [Understand data model][data_model]
+ - [Understand APIs][understand_apis]
+ - [Glossary][glossary]
+ - Design
+   - [Auth subsystem][design-auth-v3]
+   - [Client][design-client]
+   - [Learner][design-learner]
+
+[api_ref]: dev-guide/api_reference_v3.md
+[api_concurrency_ref]: dev-guide/api_concurrency_reference_v3.md
+[api_grpc_gateway]: dev-guide/api_grpc_gateway.md
+[clustering]: op-guide/clustering.md
+[conf]: op-guide/configuration.md
+[system-limit]: dev-guide/limit.md
+[faq]: faq.md
+[why]: learning/why.md
+[data_model]: learning/data_model.md
+[demo]: demo.md
+[download_build]: dl_build.md
+[embed_etcd]: https://godoc.org/github.com/etcd-io/etcd/embed
+[grpc_naming]: dev-guide/grpc_naming.md
+[failures]: op-guide/failures.md
+[gateway]: op-guide/gateway.md
+[glossary]: learning/glossary.md
+[namespace_client]: https://godoc.org/github.com/etcd-io/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
+[local_cluster]: dev-guide/local_cluster.md
+[performance]: op-guide/performance.md
+[recovery]: op-guide/recovery.md
+[maintenance]: op-guide/maintenance.md
+[security]: op-guide/security.md
+[monitoring]: op-guide/monitoring.md
+[v2_migration]: op-guide/v2-migration.md
+[container_rkt]: op-guide/container.md#rkt
+[container_docker]: op-guide/container.md#docker
+[understand_apis]: learning/api.md
+[versioning]: op-guide/versioning.md
+[supported_platforms]: op-guide/supported-platform.md
+[container_linux_platform]: platforms/container-linux-systemd.md
+[freebsd_platform]: platforms/freebsd.md
+[aws_platform]: platforms/aws.md
+[experimental]: dev-guide/experimental_apis.md
+[authentication]: op-guide/authentication.md
+[design-auth-v3]: learning/design-auth-v3.md
+[design-client]: learning/design-client.md
+[design-learner]: learning/design-learner.md
+[tuning]: tuning.md
+[upgrading]: upgrades/upgrading-etcd.md
diff --git a/content/docs/v3.4.0/_index.md b/content/docs/v3.4.0/_index.md
@@ -0,0 +1,5 @@
+---
+title: etcd version 3.4.0
+---
+
+These docs cover everything from setting up and running an etcd cluster to using etcd in your applications. Improvements to these docs are encouraged through [pull requests](https://help.github.com/en/articles/about-pull-requests) to the [etcd project](https://github.com/etcd-io/etcd) on GitHub.
diff --git a/content/docs/v3.4.0/benchmarks/README.md b/content/docs/v3.4.0/benchmarks/README.md
@@ -0,0 +1,18 @@
+# Benchmarks
+
+etcd benchmarks will be published regularly and tracked for each release below:
+
+- [etcd v2.1.0-alpha][2.1]
+- [etcd v2.2.0-rc][2.2]
+- [etcd v3 demo][3.0]
+
+# Memory Usage Benchmarks
+
+It records expected memory usage in different scenarios.
+
+- [etcd v2.2.0-rc][2.2-mem]
+
+[2.1]: etcd-2-1-0-alpha-benchmarks.md
+[2.2]: etcd-2-2-0-rc-benchmarks.md
+[2.2-mem]: etcd-2-2-0-rc-memory-benchmarks.md
+[3.0]: etcd-3-demo-benchmarks.md
diff --git a/content/docs/v3.4.0/benchmarks/etcd-2-1-0-alpha-benchmarks.md b/content/docs/v3.4.0/benchmarks/etcd-2-1-0-alpha-benchmarks.md
@@ -0,0 +1,56 @@
+---
+title: Benchmarking etcd v2.1.0
+---
+
+## Physical machines
+
+GCE n1-highcpu-2 machine type
+
+- 1x dedicated local SSD mounted under /var/lib/etcd
+- 1x dedicated slow disk for the OS
+- 1.8 GB memory
+- 2x CPUs
+- etcd version 2.1.0 alpha
+
+## etcd Cluster
+
+3 etcd members, each runs on a single machine
+
+## Testing
+
+Bootstrap another machine and use the [hey HTTP benchmark tool][hey] to send requests to each etcd member. Check the [benchmark hacking guide][hack-benchmark] for detailed instructions.
+
+## Performance
+
+### reading one single key
+
+| key size in bytes | number of clients | target etcd server | read QPS | 90th Percentile Latency (ms) |
+|-------------------|-------------------|--------------------|----------|---------------|
+| 64                | 1                 | leader only        | 1534     | 0.7        |
+| 64                | 64                | leader only        | 10125    | 9.1      |
+| 64                | 256               | leader only        | 13892    | 27.1      |
+| 256               | 1                 | leader only        | 1530     | 0.8       |
+| 256               | 64                | leader only        | 10106    | 10.1      |
+| 256               | 256               | leader only        | 14667    | 27.0      |
+| 64                | 64                | all servers        | 24200    | 3.9      |
+| 64                | 256               | all servers        | 33300    | 11.8      |
+| 256               | 64                | all servers        | 24800    | 3.9      |
+| 256               | 256               | all servers        | 33000    | 11.5      |
+
+### writing one single key
+
+| key size in bytes | number of clients | target etcd server | write QPS | 90th Percentile Latency (ms) |
+|-------------------|-------------------|--------------------|-----------|---------------|
+| 64                | 1                 | leader only        | 60        | 21.4 |
+| 64                | 64                | leader only        | 1742      | 46.8 |
+| 64                | 256               | leader only        | 3982      | 90.5 |
+| 256               | 1                 | leader only        | 58        | 20.3 |
+| 256               | 64                | leader only        | 1770      | 47.8 |
+| 256               | 256               | leader only        | 4157      | 105.3 |
+| 64                | 64                | all servers        | 1028      | 123.4 |
+| 64                | 256               | all servers        | 3260      | 123.8 |
+| 256               | 64                | all servers        | 1033      | 121.5 |
+| 256               | 256               | all servers        | 3061      | 119.3 |
+
+[hey]: https://github.com/rakyll/hey
+[hack-benchmark]: https://github.com/coreos/etcd/tree/master/hack/benchmark
diff --git a/content/docs/v3.4.0/benchmarks/etcd-2-2-0-benchmarks.md b/content/docs/v3.4.0/benchmarks/etcd-2-2-0-benchmarks.md
@@ -0,0 +1,71 @@
+---
+title: Benchmarking etcd v2.2.0
+---
+
+## Physical Machines
+
+GCE n1-highcpu-2 machine type
+
+- 1x dedicated local SSD mounted as etcd data directory
+- 1x dedicated slow disk for the OS
+- 1.8 GB memory
+- 2x CPUs
+
+## etcd Cluster
+
+3 etcd 2.2.0 members, each runs on a single machine.
+
+Detailed versions:
+
+```
+etcd Version: 2.2.0
+Git SHA: e4561dd
+Go Version: go1.5
+Go OS/Arch: linux/amd64
+```
+
+## Testing
+
+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 calculated through results of 100 benchmark rounds.
+
+## Performance
+
+### Single Key Read Performance
+
+| key size in bytes | number of clients | target etcd server | average read QPS | read QPS stddev | average 90th Percentile Latency (ms) | latency stddev |
+|-------------------|-------------------|--------------------|------------------|-----------------|--------------------------------------|----------------|
+| 64 | 1 | leader only | 2303 | 200 | 0.49 | 0.06 |
+| 64 | 64 | leader only | 15048 | 685 | 7.60 | 0.46 |
+| 64 | 256 | leader only | 14508 | 434 | 29.76 | 1.05 |
+| 256 | 1 | leader only | 2162 | 214 | 0.52 | 0.06 |
+| 256 | 64 | leader only | 14789 | 792 | 7.69| 0.48 |
+| 256 | 256 | leader only | 14424 | 512 | 29.92 | 1.42 |
+| 64 | 64 | all servers | 45752 | 2048 | 2.47 | 0.14 |
+| 64 | 256 | all servers | 46592 | 1273 | 10.14 | 0.59 |
+| 256 | 64 | all servers | 45332 | 1847 | 2.48| 0.12 |
+| 256 | 256 | all servers | 46485 | 1340 | 10.18 | 0.74 |
+
+### Single Key Write Performance
+
+| key size in bytes | number of clients | target etcd server | average write QPS | write QPS stddev | average 90th Percentile Latency (ms) | latency stddev |
+|-------------------|-------------------|--------------------|------------------|-----------------|--------------------------------------|----------------|
+| 64 | 1 | leader only | 55 | 4 | 24.51 | 13.26 |
+| 64 | 64 | leader only | 2139 | 125 | 35.23 | 3.40 |
+| 64 | 256 | leader only | 4581 | 581 | 70.53 | 10.22 |
+| 256 | 1 | leader only | 56 | 4 | 22.37| 4.33 |
+| 256 | 64 | leader only | 2052 | 151 | 36.83 | 4.20 |
+| 256 | 256 | leader only | 4442 | 560 | 71.59 | 10.03 |
+| 64 | 64 | all servers | 1625 | 85 | 58.51 | 5.14 |
+| 64 | 256 | all servers | 4461 | 298 | 89.47 | 36.48 |
+| 256 | 64 | all servers | 1599 | 94 | 60.11| 6.43 |
+| 256 | 256 | all servers | 4315 | 193 | 88.98 | 7.01 |
+
+## Performance Changes
+
+- Because etcd now records metrics for each API call, read QPS performance seems to see a minor decrease in most scenarios. This minimal performance impact was judged a reasonable investment for the breadth of monitoring and debugging information returned.
+
+- Write QPS to cluster leaders seems to be increased by a small margin. This is because the main loop and entry apply loops were decoupled in the etcd raft logic, eliminating several blocks between them.
+
+- Write QPS to all members seems to be increased by a significant margin, because followers now receive the latest commit index sooner, and commit proposals more quickly.
diff --git a/content/docs/v3.4.0/benchmarks/etcd-2-2-0-rc-benchmarks.md b/content/docs/v3.4.0/benchmarks/etcd-2-2-0-rc-benchmarks.md
@@ -0,0 +1,76 @@
+---
+title: Benchmarking etcd v2.2.0-rc
+---
+
+## Physical machine
+
+GCE n1-highcpu-2 machine type
+
+- 1x dedicated local SSD mounted under /var/lib/etcd
+- 1x dedicated slow disk for the OS
+- 1.8 GB memory
+- 2x CPUs
+
+## etcd Cluster
+
+3 etcd 2.2.0-rc members, each runs on a single machine.
+
+Detailed versions:
+
+```
+etcd Version: 2.2.0-alpha.1+git
+Git SHA: 59a5a7e
+Go Version: go1.4.2
+Go OS/Arch: linux/amd64
+```
+
+Also, we use 3 etcd 2.1.0 alpha-stage members to form cluster to get base performance. etcd's commit head is at [c7146bd5][c7146bd5], which is the same as the one that we use in [etcd 2.1 benchmark][etcd-2.1-benchmark].
+
+## Testing
+
+Bootstrap another machine and use the [hey HTTP benchmark tool][hey] to send requests to each etcd member. Check the [benchmark hacking guide][hack-benchmark] for detailed instructions.
+
+## Performance
+
+### reading one single key
+
+| key size in bytes | number of clients | target etcd server | read QPS | 90th Percentile Latency (ms) |
+|-------------------|-------------------|--------------------|----------|---------------|
+| 64                | 1                 | leader only        | 2804 (-5%) | 0.4 (+0%) |
+| 64                | 64                | leader only        | 17816 (+0%) | 5.7 (-6%) |
+| 64                | 256               | leader only        | 18667 (-6%) | 20.4 (+2%) |
+| 256               | 1                 | leader only        | 2181 (-15%) | 0.5 (+25%) |
+| 256               | 64                | leader only        | 17435 (-7%) | 6.0 (+9%) |
+| 256               | 256               | leader only        | 18180 (-8%) | 21.3 (+3%) |
+| 64                | 64                | all servers        | 46965 (-4%) | 2.1 (+0%) |
+| 64                | 256               | all servers        | 55286 (-6%) | 7.4 (+6%) |
+| 256               | 64                | all servers        | 46603 (-6%) | 2.1 (+5%) |
+| 256               | 256               | all servers        | 55291 (-6%) | 7.3 (+4%) |
+
+### writing one single key
+
+| key size in bytes | number of clients | target etcd server | write QPS | 90th Percentile Latency (ms) |
+|-------------------|-------------------|--------------------|-----------|---------------|
+| 64                | 1                 | leader only        | 76 (+22%)  | 19.4 (-15%) |
+| 64                | 64                | leader only        | 2461 (+45%) | 31.8 (-32%) |
+| 64                | 256               | leader only        | 4275 (+1%) | 69.6 (-10%) |
+| 256               | 1                 | leader only        | 64 (+20%)  | 16.7 (-30%) |
+| 256               | 64                | leader only        | 2385 (+30%) | 31.5 (-19%) |
+| 256               | 256               | leader only        | 4353 (-3%) | 74.0 (+9%) |
+| 64                | 64                | all servers        | 2005 (+81%) | 49.8 (-55%) |
+| 64                | 256               | all servers        | 4868 (+35%) | 81.5 (-40%) |
+| 256               | 64                | all servers        | 1925 (+72%) | 47.7 (-59%) |
+| 256               | 256               | all servers        | 4975 (+36%) | 70.3 (-36%) |
+
+### performance changes explanation
+
+- read QPS in most scenarios is decreased by 5~8%. The reason is that etcd records store metrics for each store operation. The metrics is important for monitoring and debugging, so this is acceptable.
+
+- write QPS to leader is increased by 20~30%. This is because we decouple raft main loop and entry apply loop, which avoids them blocking each other.
+
+- write QPS to all servers is increased by 30~80% because follower could receive latest commit index earlier and commit proposals faster.
+
+[hey]: https://github.com/rakyll/hey
+[c7146bd5]: https://github.com/coreos/etcd/commits/c7146bd5f2c73716091262edc638401bb8229144
+[etcd-2.1-benchmark]: etcd-2-1-0-alpha-benchmarks.md
+[hack-benchmark]: ../../hack/benchmark/