Merge pull request etcd-io#99 from nate-double-u/93-add-docs-to-website

Migrate documentation: Add docs to etcd-io/website
sonalkr132 · Feb 2, 2021 · aec163d · aec163d
2 parents 6b69d4b + ff984ad
commit aec163d
Show file tree

Hide file tree

Showing 206 changed files with 81,436 additions and 8 deletions.
diff --git a/config.toml b/config.toml
@@ -41,7 +41,7 @@ unsafe = true
 
 [params.versions]
 latest = "v3.4.0"
-all    = ["v3.4.0", "v3.3.13", "v3.3.12", "v3.2.17", "v3.1.12", "v2"]
+all    = ["current", "v3.4.0", "v3.3.13", "v3.3.12", "v3.2.17", "v3.1.12", "v2"]
 
 [params.logos]
 hero   = "https://raw.githubusercontent.com/cncf/artwork/master/projects/etcd/horizontal/white/etcd-horizontal-white.png"

diff --git a/content/docs/current/README.md b/content/docs/current/README.md
@@ -0,0 +1,5 @@
+# The etcd 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.
+
+Please note that the files in this directory are *source files* for the built and rendered documentation that can be viewed at [etcd.io/docs](https://etcd.io/docs).
diff --git a/content/docs/current/_index.md b/content/docs/current/_index.md
@@ -0,0 +1,8 @@
+---
+title: etcd current version
+weight: 1000
+cascade:
+  version: current
+---
+
+These docs cover everything from setting up and running an etcd cluster to using etcd in applications. Improvements to these docs are encouraged through [pull requests](https://help.github.com/en/articles/about-pull-requests) to the [etcd-io/website project](https://github.com/etcd-io/website) on GitHub.
diff --git a/content/docs/current/benchmarks/README.md b/content/docs/current/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/current/benchmarks/_index.md b/content/docs/current/benchmarks/_index.md
@@ -0,0 +1,5 @@
+---
+title: Benchmarks
+weight: 5000
+description: Performance measures for etcd
+---
diff --git a/content/docs/current/benchmarks/etcd-2-1-0-alpha-benchmarks.md b/content/docs/current/benchmarks/etcd-2-1-0-alpha-benchmarks.md
@@ -0,0 +1,58 @@
+---
+title: Benchmarking etcd v2.1.0
+weight: 5875
+description: Performance measures for 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/current/benchmarks/etcd-2-2-0-benchmarks.md b/content/docs/current/benchmarks/etcd-2-2-0-benchmarks.md
@@ -0,0 +1,73 @@
+---
+title: Benchmarking etcd v2.2.0
+weight: 5750
+description: Performance measures for 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/current/benchmarks/etcd-2-2-0-rc-benchmarks.md b/content/docs/current/benchmarks/etcd-2-2-0-rc-benchmarks.md
@@ -0,0 +1,78 @@
+---
+title: Benchmarking etcd v2.2.0-rc
+weight: 5625
+description: Performance measures for 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/
diff --git a/content/docs/current/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md b/content/docs/current/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md
@@ -0,0 +1,53 @@
+---
+title: Benchmarking etcd v2.2.0-rc-memory
+weight: 5500
+description: Performance measures for etcd v2.2.0-rc-memory
+---
+
+## Physical machine
+
+GCE n1-standard-2 machine type
+
+- 1x dedicated local SSD mounted under /var/lib/etcd
+- 1x dedicated slow disk for the OS
+- 7.5 GB memory
+- 2x CPUs
+
+## etcd
+
+```
+etcd Version: 2.2.0-rc.0+git
+Git SHA: 103cb5c
+Go Version: go1.5
+Go OS/Arch: linux/amd64
+```
+
+## Testing
+
+Start 3-member etcd cluster, each of which uses 2 cores.
+
+The length of key name is always 64 bytes, which is a reasonable length of average key bytes.
+
+## Memory Maximal Usage
+
+- etcd may use maximal memory if one follower is dead and the leader keeps sending snapshots.
+- `max RSS` is the maximal memory usage recorded in 3 runs.
+
+| value bytes | key number  | data size(MB) | max RSS(MB) | max RSS/data rate on leader |
+|-------------|-------------|---------------|-------------|-----------------------------|
+| 128  | 50000  | 6 | 433 | 72x |
+| 128  | 100000 | 12 | 659 | 54x |
+| 128  | 200000 | 24 | 1466 | 61x |
+| 1024 | 50000  | 48 | 1253 | 26x |
+| 1024 | 100000 | 96 | 2344 | 24x |
+| 1024 | 200000 | 192 | 4361 | 22x |
+
+## Data Size Threshold
+
+- When etcd reaches data size threshold, it may trigger leader election easily and drop part of proposals.
+- For most cases, the etcd cluster should work smoothly if it doesn't hit the threshold. If it doesn't work well due to insufficient resources, decrease its data size.
+
+| value bytes | key number limitation | suggested data size threshold(MB) | consumed RSS(MB) |
+|-------------|-----------------------|-----------------------------------|------------------|
+| 128 | 400K | 48 | 2400 |
+| 1024 | 300K | 292 | 6500 |
diff --git a/content/docs/current/benchmarks/etcd-3-demo-benchmarks.md b/content/docs/current/benchmarks/etcd-3-demo-benchmarks.md
@@ -0,0 +1,48 @@
+---
+title: Benchmarking etcd v3
+weight: 5375
+description: Performance measures for etcd v3
+---
+
+## 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.2.0
+
+## etcd Cluster
+
+1 etcd member running in v3 demo mode
+
+## Testing
+
+Use [etcd v3 benchmark tool][etcd-v3-benchmark].
+
+## Performance
+
+### reading one single key
+
+| key size in bytes | number of clients | read QPS | 90th Percentile Latency (ms) |
+|-------------------|-------------------|----------|---------------|
+| 256               | 1                 | 2716  | 0.4      |
+| 256               | 64                | 16623 | 6.1      |
+| 256               | 256               | 16622 | 21.7     |
+
+The performance is nearly the same as the one with empty server handler.
+
+### reading one single key after putting
+
+| key size in bytes | number of clients | read QPS | 90th Percentile Latency (ms) |
+|-------------------|-------------------|----------|---------------|
+| 256               | 1                 | 2269  | 0.5      |
+| 256               | 64                | 13582 | 8.6      |
+| 256               | 256               | 13262 | 47.5     |
+
+The performance with empty server handler is not affected by one put. So the
+performance downgrade should be caused by storage package.
+
+[etcd-v3-benchmark]: ../../tools/benchmark/