diff --git a/content/docs/v2/04_to_2_snapshot_migration.md b/content/docs/v2/04_to_2_snapshot_migration.md index 7f30ade679e8e..86c6a5a0a738d 100644 --- a/content/docs/v2/04_to_2_snapshot_migration.md +++ b/content/docs/v2/04_to_2_snapshot_migration.md @@ -2,21 +2,17 @@ title: Snapshot Migration --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - You can migrate a snapshot of your data from a v0.4.9+ cluster into a new etcd 2.2 cluster using a snapshot migration. After snapshot migration, the etcd indexes of your data will change. Many etcd applications rely on these indexes to behave correctly. This operation should only be done while all etcd applications are stopped. To get started get the newest data snapshot from the 0.4.9+ cluster: -``` +```shell curl http://cluster.example.com:4001/v2/migration/snapshot > backup.snap ``` Now, import the snapshot into your new cluster: -``` +```shell etcdctl --endpoint new_cluster.example.com import --snap backup.snap ``` diff --git a/content/docs/v2/admin_guide.md b/content/docs/v2/admin_guide.md index b946762f20f57..131f0a4d87112 100644 --- a/content/docs/v2/admin_guide.md +++ b/content/docs/v2/admin_guide.md @@ -2,8 +2,6 @@ title: Administration --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - ## Data Directory ### Lifecycle @@ -305,15 +303,15 @@ By default, etcd uses the default configuration of the Go 1.4 runtime, which mea When using etcd in heavy-load scenarios on machines with multiple cores it will usually be desirable to increase the number of threads that etcd can utilize. To do this, simply set the environment variable GOMAXPROCS to the desired number when starting etcd. For more information on this variable, see the [Go runtime documentation][golang-runtime]. -[add-a-member]: runtime-configuration.md#add-a-new-member +[add-a-member]: ../runtime-configuration#add-a-new-member [golang1.5-runtime]: https://golang.org/doc/go1.5#runtime [golang-memstats]: https://golang.org/pkg/runtime/#MemStats [golang-runtime]: https://golang.org/pkg/runtime -[metrics]: metrics.md +[metrics]: ../metrics [prometheus]: http://prometheus.io/ -[remove-a-member]: runtime-configuration.md#remove-a-member -[runtime-reconfig]: runtime-configuration.md#cluster-reconfiguration-operations +[remove-a-member]: ../runtime-configuration#remove-a-member +[runtime-reconfig]: ../runtime-configuration#cluster-reconfiguration-operations [snap-pkg]: http://godoc.org/github.com/coreos/etcd/snap -[update-a-member]: runtime-configuration.md#update-a-member +[update-a-member]: ../runtime-configuration#update-a-member [v3-docs]: /docs/latest [wal-pkg]: http://godoc.org/github.com/coreos/etcd/wal diff --git a/content/docs/v2/api.md b/content/docs/v2/api.md index 94ef6f49dd829..9a661a43b8dcd 100644 --- a/content/docs/v2/api.md +++ b/content/docs/v2/api.md @@ -2,10 +2,6 @@ title: etcd API --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - ## Running a Single Machine Cluster These examples will use a single member cluster to show you the basics of the etcd REST API. diff --git a/content/docs/v2/api_v3.md b/content/docs/v2/api_v3.md deleted file mode 100644 index 628adb2222fed..0000000000000 --- a/content/docs/v2/api_v3.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: etcd3 API ---- - -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - -TODO: API doc - -## Data Model - -etcd is designed to reliably store infrequently updated data and provide reliable watch queries. etcd exposes previous versions of key-value pairs to support inexpensive snapshots and watch history events (“time travel queries”). A persistent, multi-version, concurrency-control data model is a good fit for these use cases. - -etcd stores data in a multiversion [persistent][persistent-ds] key-value store. The persistent key-value store preserves the previous version of a key-value pair when its value is superseded with new data. The key-value store is effectively immutable; its operations do not update the structure in-place, but instead always generates a new updated structure. All past versions of keys are still accessible and watchable after modification. To prevent the data store from growing indefinitely over time from maintaining old versions, the store may be compacted to shed the oldest versions of superseded data. - -### Logical View - -The store’s logical view is a flat binary key space. The key space has a lexically sorted index on byte string keys so range queries are inexpensive. - -The key space maintains multiple revisions. Each atomic mutative operation (e.g., a transaction operation may contain multiple operations) creates a new revision on the key space. All data held by previous revisions remains unchanged. Old versions of key can still be accessed through previous revisions. Likewise, revisions are indexed as well; ranging over revisions with watchers is efficient. If the store is compacted to recover space, revisions before the compact revision will be removed. - -A key’s lifetime spans a generation. Each key may have one or multiple generations. Creating a key increments the generation of that key, starting at 1 if the key never existed. Deleting a key generates a key tombstone, concluding the key’s current generation. Each modification of a key creates a new version of the key. Once a compaction happens, any generation ended before the given revision will be removed and values set before the compaction revision except the latest one will be removed. - -### Physical View - -etcd stores the physical data as key-value pairs in a persistent [b+tree][b+tree]. Each revision of the store’s state only contains the delta from its previous revision to be efficient. A single revision may correspond to multiple keys in the tree. - -The key of key-value pair is a 3-tuple (major, sub, type). Major is the store revision holding the key. Sub differentiates among keys within the same revision. Type is an optional suffix for special value (e.g., `t` if the value contains a tombstone). The value of the key-value pair contains the modification from previous revision, thus one delta from previous revision. The b+tree is ordered by key in lexical byte-order. Ranged lookups over revision deltas are fast; this enables quickly finding modifications from one specific revision to another. Compaction removes out-of-date keys-value pairs. - -etcd also keeps a secondary in-memory [btree][btree] index to speed up range queries over keys. The keys in the btree index are the keys of the store exposed to user. The value is a pointer to the modification of the persistent b+tree. Compaction removes dead pointers. - -## KV API Guarantees - -etcd is a consistent and durable key value store with mini-transaction(TODO: link to txn doc when we have it) support. The key value store is exposed through the KV APIs. etcd tries to ensure the strongest consistency and durability guarantees for a distributed system. This specification enumerates the KV API guarantees made by etcd. - -### APIs to consider - -* Read APIs - * range - * watch -* Write APIs - * put - * delete -* Combination (read-modify-write) APIs - * txn - -### etcd Specific Definitions - -#### operation completed - -An etcd operation is considered complete when it is committed through consensus, and therefore “executed” -- permanently stored -- by the etcd storage engine. The client knows an operation is completed when it receives a response from the etcd server. Note that the client may be uncertain about the status of an operation if it times out, or there is a network disruption between the client and the etcd member. etcd may also abort operations when there is a leader election. etcd does not send `abort` responses to clients’ outstanding requests in this event. - -#### revision - -An etcd operation that modifies the key value store is assigned with a single increasing revision. A transaction operation might modify the key value store multiple times, but only one revision is assigned. The revision attribute of a key value pair that modified by the operation has the same value as the revision of the operation. The revision can be used as a logical clock for key value store. A key value pair that has a larger revision is modified after a key value pair with a smaller revision. Two key value pairs that have the same revision are modified by an operation "concurrently". - -### Guarantees Provided - -#### Atomicity - -All API requests are atomic; an operation either completes entirely or not at all. For watch requests, all events generated by one operation will be in one watch response. Watch never observes partial events for a single operation. - -#### Consistency - -All API calls ensure [sequential consistency][seq_consistency], the strongest consistency guarantee available from distributed systems. No matter which etcd member server a client makes requests to, a client reads the same events in the same order. If two members complete the same number of operations, the state of the two members is consistent. - -For watch operations, etcd guarantees to return the same value for the same key across all members for the same revision. For range operations, etcd has a similar guarantee for [linearized][Linearizability] access; serialized access may be behind the quorum state, so that the later revision is not yet available. - -As with all distributed systems, it is impossible for etcd to ensure [strict consistency][strict_consistency]. etcd does not guarantee that it will return to a read the “most recent” value (as measured by a wall clock when a request is completed) available on any cluster member. - -#### Isolation - -etcd ensures [serializable isolation][serializable_isolation], which is the highest isolation level available in distributed systems. Read operations will never observe any intermediate data. - -#### Durability - -Any completed operations are durable. All accessible data is also durable data. A read will never return data that has not been made durable. - -#### Linearizability - -Linearizability (also known as Atomic Consistency or External Consistency) is a consistency level between strict consistency and sequential consistency. - -For linearizability, suppose each operation receives a timestamp from a loosely synchronized global clock. Operations are linearized if and only if they always complete as though they were executed in a sequential order and each operation appears to complete in the order specified by the program. Likewise, if an operation’s timestamp precedes another, that operation must also precede the other operation in the sequence. - -For example, consider a client completing a write at time point 1 (*t1*). A client issuing a read at *t2* (for *t2* > *t1*) should receive a value at least as recent as the previous write, completed at *t1*. However, the read might actually complete only by *t3*, and the returned value, current at *t2* when the read began, might be "stale" by *t3*. - -etcd does not ensure linearizability for watch operations. Users are expected to verify the revision of watch responses to ensure correct ordering. - -etcd ensures linearizability for all other operations by default. Linearizability comes with a cost, however, because linearized requests must go through the Raft consensus process. To obtain lower latencies and higher throughput for read requests, clients can configure a request’s consistency mode to `serializable`, which may access stale data with respect to quorum, but removes the performance penalty of linearized accesses' reliance on live consensus. - -[persistent-ds]: https://en.wikipedia.org/wiki/Persistent_data_structure -[btree]: https://en.wikipedia.org/wiki/B-tree -[b+tree]: https://en.wikipedia.org/wiki/B%2B_tree -[seq_consistency]: https://en.wikipedia.org/wiki/Consistency_model#Sequential_consistency -[strict_consistency]: https://en.wikipedia.org/wiki/Consistency_model#Strict_consistency -[serializable_isolation]: https://en.wikipedia.org/wiki/Isolation_(database_systems)#Serializable -[Linearizability]: #linearizability diff --git a/content/docs/v2/auth_api.md b/content/docs/v2/auth_api.md index f62428ebf6da7..0147a9e55ac30 100644 --- a/content/docs/v2/auth_api.md +++ b/content/docs/v2/auth_api.md @@ -2,11 +2,8 @@ title: v2 Auth and Security --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - ## etcd Resources + There are three types of resources in etcd 1. permission resources: users and roles in the user store diff --git a/content/docs/v2/authentication.md b/content/docs/v2/authentication.md index 2d7559e03fa2f..42541dd1b11b6 100644 --- a/content/docs/v2/authentication.md +++ b/content/docs/v2/authentication.md @@ -2,10 +2,6 @@ title: Authentication Guide --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - ## Overview Authentication -- having users and roles in etcd -- was added in etcd 2.1. This guide will help you set up basic authentication in etcd. @@ -183,4 +179,4 @@ $ etcdctl -u user get foo Otherwise, all `etcdctl` commands remain the same. Users and roles can still be created and modified, but require authentication by a user with the root role. -[auth-api]: auth_api.md +[auth-api]: ../auth_api diff --git a/content/docs/v2/backward_compatibility.md b/content/docs/v2/backward_compatibility.md index 5af66d7673cb5..3e3c3905eff89 100644 --- a/content/docs/v2/backward_compatibility.md +++ b/content/docs/v2/backward_compatibility.md @@ -2,10 +2,6 @@ title: Backward Compatibility --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - The main goal of etcd 2.0 release is to improve cluster safety around bootstrapping and dynamic reconfiguration. To do this, we deprecated the old error-prone APIs and provide a new set of APIs. The other main focus of this release was a more reliable Raft implementation, but as this change is internal it should not have any notable effects to users. @@ -51,27 +47,22 @@ We added an option for a consistent read in the old version of etcd since etcd 0 ## Standby -etcd 0.4’s standby mode has been deprecated. [Proxy mode][proxymode] is introduced to solve a subset of problems standby was solving. +etcd 0.4’s standby mode has been deprecated. [Proxy mode](../proxy) is introduced to solve a subset of problems standby was solving. Standby mode was intended for large clusters that had a subset of the members acting in the consensus process. Overall this process was too magical and allowed for operators to back themselves into a corner. Proxy mode in 2.0 will provide similar functionality, and with improved control over which machines act as proxies due to the operator specifically configuring them. Proxies also support read only or read/write modes for increased security and durability. -[proxymode]: proxy.md - ## Discovery Service -A size key needs to be provided inside a [discovery token][discoverytoken]. - -[discoverytoken]: clustering.md#custom-etcd-discovery-service +A size key needs to be provided inside a [discovery token](../clustering#custom-etcd-discovery-service). ## HTTP Admin API -`v2/admin` on peer url and `v2/keys/_etcd` are unified under the new [v2/members API][members-api] to better explain which machines are part of an etcd cluster, and to simplify the keyspace for all your use cases. - -[members-api]: members_api.md +`v2/admin` on peer url and `v2/keys/_etcd` are unified under the new [v2/members API](../members-api) to better explain which machines are part of an etcd cluster, and to simplify the keyspace for all your use cases. ## HTTP Key Value API + - The follower can now transparently proxy write requests to the leader. Clients will no longer see 307 redirections to the leader from etcd. - Expiration time is in UTC instead of local time. diff --git a/content/docs/v2/benchmarks/README.md b/content/docs/v2/benchmarks/README.md deleted file mode 100644 index 881641a79c854..0000000000000 --- a/content/docs/v2/benchmarks/README.md +++ /dev/null @@ -1,23 +0,0 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - -# 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/v2/benchmarks/_index.md b/content/docs/v2/benchmarks/_index.md new file mode 100644 index 0000000000000..ccd3d62fd5dbb --- /dev/null +++ b/content/docs/v2/benchmarks/_index.md @@ -0,0 +1,3 @@ +--- +title: Benchmarks +--- diff --git a/content/docs/v2/benchmarks/etcd-2-1-0-alpha-benchmarks.md b/content/docs/v2/benchmarks/etcd-2-1-0-alpha-benchmarks.md index 1fc808ec4d74e..8215978b66307 100644 --- a/content/docs/v2/benchmarks/etcd-2-1-0-alpha-benchmarks.md +++ b/content/docs/v2/benchmarks/etcd-2-1-0-alpha-benchmarks.md @@ -1,7 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - +--- +title: etcd 2.1.0-alpha benchmarks +--- ## Physical machines diff --git a/content/docs/v2/benchmarks/etcd-2-2-0-benchmarks.md b/content/docs/v2/benchmarks/etcd-2-2-0-benchmarks.md index b99e82d50ed1b..c2513617a2724 100644 --- a/content/docs/v2/benchmarks/etcd-2-2-0-benchmarks.md +++ b/content/docs/v2/benchmarks/etcd-2-2-0-benchmarks.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - -# Benchmarking etcd v2.2.0 +--- +title: Benchmarking etcd v2.2.0 +--- ## Physical Machines diff --git a/content/docs/v2/benchmarks/etcd-2-2-0-rc-benchmarks.md b/content/docs/v2/benchmarks/etcd-2-2-0-rc-benchmarks.md index 9170a644ba3ee..3cb1e0b0fd1cb 100644 --- a/content/docs/v2/benchmarks/etcd-2-2-0-rc-benchmarks.md +++ b/content/docs/v2/benchmarks/etcd-2-2-0-rc-benchmarks.md @@ -1,7 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - +--- +title: etcd 2.2.0-rc benchmarks +--- ## Physical machines diff --git a/content/docs/v2/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md b/content/docs/v2/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md index 40c220eaa9591..69e964a886377 100644 --- a/content/docs/v2/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md +++ b/content/docs/v2/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md @@ -1,7 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - +--- +title: etcd 2.2.0-rc memory benchmarks +--- ## Physical machine diff --git a/content/docs/v2/benchmarks/etcd-3-demo-benchmarks.md b/content/docs/v2/benchmarks/etcd-3-demo-benchmarks.md index cb59d173ccf0b..9fac9f43ef8a1 100644 --- a/content/docs/v2/benchmarks/etcd-3-demo-benchmarks.md +++ b/content/docs/v2/benchmarks/etcd-3-demo-benchmarks.md @@ -1,7 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - +--- +title: etcd 3 demo benchmarks +--- ## Physical machines diff --git a/content/docs/v2/benchmarks/etcd-3-watch-memory-benchmark.md b/content/docs/v2/benchmarks/etcd-3-watch-memory-benchmark.md index 56ae1a2398c0d..1de658ada38b5 100644 --- a/content/docs/v2/benchmarks/etcd-3-watch-memory-benchmark.md +++ b/content/docs/v2/benchmarks/etcd-3-watch-memory-benchmark.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - -# 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/content/docs/v2/benchmarks/etcd-storage-memory-benchmark.md b/content/docs/v2/benchmarks/etcd-storage-memory-benchmark.md index 3f75b79205f80..8d9e2053eaba8 100644 --- a/content/docs/v2/benchmarks/etcd-storage-memory-benchmark.md +++ b/content/docs/v2/benchmarks/etcd-storage-memory-benchmark.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - -# Storage Memory Usage Benchmark +--- +title: Storage Memory Usage Benchmark +--- 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/content/docs/v2/branch_management.md b/content/docs/v2/branch_management.md index b20e6db1677aa..0604321b7c423 100644 --- a/content/docs/v2/branch_management.md +++ b/content/docs/v2/branch_management.md @@ -2,10 +2,6 @@ title: Branch Management --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - ## Guide * New development occurs on the [master branch][master]. @@ -27,6 +23,6 @@ Before the release of the next stable version, feature PRs will be frozen. We wi All branches with prefix `release-` are considered _stable_ branches. -After every minor release (http://semver.org/), we will have a new stable branch for that release. We will keep fixing the backwards-compatible bugs for the latest stable release, but not previous releases. The _patch_ release, incorporating any bug fixes, will be once every two weeks, given any patches. +After every minor release (https://semver.org/), we will have a new stable branch for that release. We will keep fixing the backwards-compatible bugs for the latest stable release, but not previous releases. The _patch_ release, incorporating any bug fixes, will be once every two weeks, given any patches. [master]: https://github.com/coreos/etcd/tree/master diff --git a/content/docs/v2/clustering.md b/content/docs/v2/clustering.md index 7acca9dea5881..5d5f87b036d36 100644 --- a/content/docs/v2/clustering.md +++ b/content/docs/v2/clustering.md @@ -2,10 +2,6 @@ title: Clustering Guide --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - ## Overview Starting an etcd cluster statically requires that each member knows another in the cluster. In a number of cases, you might not know the IPs of your cluster members ahead of time. In these cases, you can bootstrap an etcd cluster with the help of a discovery service. diff --git a/content/docs/v2/configuration.md b/content/docs/v2/configuration.md index e64de1aafaf99..1e7533a237014 100644 --- a/content/docs/v2/configuration.md +++ b/content/docs/v2/configuration.md @@ -2,10 +2,6 @@ title: Configuration Flags --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - etcd is configurable through command-line flags and environment variables. Options set on the command line take precedence over those from the environment. The format of environment variable for flag `--my-flag` is `ETCD_MY_FLAG`. It applies to all flags. @@ -45,7 +41,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [ + env variable: ETCD_HEARTBEAT_INTERVAL ### --election-timeout -+ Time (in milliseconds) for an election to timeout. See [tuning.md](tuning.md#time-parameters) for details. ++ Time (in milliseconds) for an election to timeout. See [tuning.md](../tuning#time-parameters) for details. + default: "1000" + env variable: ETCD_ELECTION_TIMEOUT @@ -104,7 +100,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [ + default: "new" + env variable: ETCD_INITIAL_CLUSTER_STATE -[static bootstrap]: clustering.md#static +[static bootstrap]: ../clustering#static ### --initial-cluster-token + Initial cluster token for the etcd cluster during bootstrap. @@ -270,7 +266,8 @@ Follow the instructions when using these flags. ## Experimental Flags ### --experimental-v3demo -+ Enable experimental [v3 demo API][rfc-v3]. + ++ Enable experimental v3 demo API + default: false + env variable: ETCD_EXPERIMENTAL_V3DEMO @@ -286,14 +283,13 @@ Follow the instructions when using these flags. + Enable runtime profiling data via HTTP server. Address is at client URL + "/debug/pprof/" + default: false -[build-cluster]: clustering.md#static -[reconfig]: runtime-configuration.md -[discovery]: clustering.md#discovery +[build-cluster]: ../clustering#static +[reconfig]: ../runtime-configuration +[discovery]: ../clustering#discovery [iana-ports]: http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt -[proxy]: proxy.md -[reconfig]: runtime-configuration.md -[restore]: admin_guide.md#restoring-a-backup -[rfc-v3]: rfc/v3api.md -[security]: security.md +[proxy]: ../proxy +[reconfig]: ../runtime-configuration +[restore]: ../admin_guide#restoring-a-backup +[security]: ../security [systemd-intro]: http://freedesktop.org/wiki/Software/systemd/ -[tuning]: tuning.md#time-parameters +[tuning]: ../tuning#time-parameters diff --git a/content/docs/v2/dev/_index.md b/content/docs/v2/dev/_index.md new file mode 100644 index 0000000000000..4cb3f607fc5b7 --- /dev/null +++ b/content/docs/v2/dev/_index.md @@ -0,0 +1,3 @@ +--- +title: Development +--- diff --git a/content/docs/v2/dev/release.md b/content/docs/v2/dev/release.md index 324258204e181..8e8f632534ff6 100644 --- a/content/docs/v2/dev/release.md +++ b/content/docs/v2/dev/release.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - -# etcd release guide +--- +title: etcd release guide +--- The guide talks about how to release a new version of etcd. diff --git a/content/docs/v2/discovery_protocol.md b/content/docs/v2/discovery_protocol.md index bd9eb76f2fd64..d34be196e8b17 100644 --- a/content/docs/v2/discovery_protocol.md +++ b/content/docs/v2/discovery_protocol.md @@ -2,10 +2,6 @@ title: Discovery Service Protocol --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - Discovery service protocol helps new etcd member to discover all other members in cluster bootstrap phase using a shared discovery URL. Discovery service protocol is _only_ used in cluster bootstrap phase, and cannot be used for runtime reconfiguration or cluster monitoring. @@ -114,7 +110,7 @@ You can check the status for this discovery token, including the machines that h The repository is located at https://github.com/coreos/discovery.etcd.io. You could use it to build your own public discovery service. -[api]: api.md#waiting-for-a-change -[cluster-size]: admin_guide.md#optimal-cluster-size +[api]: ../api#waiting-for-a-change +[cluster-size]: ../admin_guide#optimal-cluster-size [expected-cluster-size]: #specifying-the-expected-cluster-size [new-discovery-token]: #creating-a-new-discovery-token diff --git a/content/docs/v2/docker_guide.md b/content/docs/v2/docker_guide.md index 8f924573ad4f1..5fe252281bc11 100644 --- a/content/docs/v2/docker_guide.md +++ b/content/docs/v2/docker_guide.md @@ -2,12 +2,7 @@ title: Running etcd under Docker --- - -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - -The following guide will show you how to run etcd under Docker using the [static bootstrap process](clustering.md#static). +The following guide will show you how to run etcd under Docker using the [static bootstrap process](../clustering#static). ## Running etcd in standalone mode diff --git a/content/docs/v2/errorcode.md b/content/docs/v2/errorcode.md index 8c75a19e777ec..05044916fda50 100644 --- a/content/docs/v2/errorcode.md +++ b/content/docs/v2/errorcode.md @@ -2,10 +2,6 @@ title: Error Code --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - This document describes the error code used in key space '/v2/keys'. Feel free to import 'github.com/coreos/etcd/error' to use. It's categorized into four groups: diff --git a/content/docs/v2/faq.md b/content/docs/v2/faq.md index c0faa41e08d46..f589a809d360e 100644 --- a/content/docs/v2/faq.md +++ b/content/docs/v2/faq.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# FAQ +--- +title: FAQ +--- ## 1) Why can an etcd client read an old version of data when a majority of the etcd cluster members are down? diff --git a/content/docs/v2/glossary.md b/content/docs/v2/glossary.md index 70c2d40ee847a..1acf3ce7e73eb 100644 --- a/content/docs/v2/glossary.md +++ b/content/docs/v2/glossary.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Glossary +--- +title: Glossary +--- This document defines the various terms used in etcd documentation, command line and source code. diff --git a/content/docs/v2/internal-protocol-versioning.md b/content/docs/v2/internal-protocol-versioning.md index 68d716e5f9f16..558a4774d711a 100644 --- a/content/docs/v2/internal-protocol-versioning.md +++ b/content/docs/v2/internal-protocol-versioning.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Versioning +--- +title: Versioning +--- Goal: We want to be able to upgrade an individual peer in an etcd cluster to a newer version of etcd. The process will take the form of individual followers upgrading to the latest version until the entire cluster is on the new version. diff --git a/content/docs/v2/libraries-and-tools.md b/content/docs/v2/libraries-and-tools.md index fb70ff2fc5d59..684d58dd8a8e9 100644 --- a/content/docs/v2/libraries-and-tools.md +++ b/content/docs/v2/libraries-and-tools.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Libraries and Tools +--- +title: Libraries and Tools +--- **Tools** diff --git a/content/docs/v2/members_api.md b/content/docs/v2/members_api.md index a9ff6a04396ab..05188fc2e017d 100644 --- a/content/docs/v2/members_api.md +++ b/content/docs/v2/members_api.md @@ -1,14 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Members API - -* [List members](#list-members) -* [Add a member](#add-a-member) -* [Delete a member](#delete-a-member) -* [Change the peer urls of a member](#change-the-peer-urls-of-a-member) +--- +title: Members API +--- ## List members @@ -28,28 +20,28 @@ curl http://10.0.0.10:2379/v2/members ```json { - "members": [ - { - "id": "272e204152", - "name": "infra1", - "peerURLs": [ - "http://10.0.0.10:2380" - ], - "clientURLs": [ - "http://10.0.0.10:2379" - ] - }, - { - "id": "2225373f43", - "name": "infra2", - "peerURLs": [ - "http://10.0.0.11:2380" - ], - "clientURLs": [ - "http://10.0.0.11:2379" - ] - }, - ] + "members": [ + { + "id": "272e204152", + "name": "infra1", + "peerURLs": [ + "http://10.0.0.10:2380" + ], + "clientURLs": [ + "http://10.0.0.10:2379" + ] + }, + { + "id": "2225373f43", + "name": "infra2", + "peerURLs": [ + "http://10.0.0.11:2380" + ], + "clientURLs": [ + "http://10.0.0.11:2379" + ] + }, + ] } ``` @@ -76,10 +68,10 @@ curl http://10.0.0.10:2379/v2/members -XPOST \ ```json { - "id": "3777296169", - "peerURLs": [ - "http://10.0.0.10:2380" - ] + "id": "3777296169", + "peerURLs": [ + "http://10.0.0.10:2380" + ] } ``` @@ -122,4 +114,3 @@ PUT /v2/members/ HTTP/1.1 curl http://10.0.0.10:2379/v2/members/272e204152 -XPUT \ -H "Content-Type: application/json" -d '{"peerURLs":["http://10.0.0.10:2380"]}' ``` - diff --git a/content/docs/v2/metrics.md b/content/docs/v2/metrics.md index b0971d9da38d9..c26eec4fb2e36 100644 --- a/content/docs/v2/metrics.md +++ b/content/docs/v2/metrics.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Metrics +--- +title: Metrics +--- etcd uses [Prometheus][prometheus] for metrics reporting. The metrics can be used for real-time monitoring and debugging. etcd does not persist its metrics; if a member restarts, the metrics will be reset. diff --git a/content/docs/v2/other_apis.md b/content/docs/v2/other_apis.md index ec21a886cbdd9..812085ebb11af 100644 --- a/content/docs/v2/other_apis.md +++ b/content/docs/v2/other_apis.md @@ -1,12 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Miscellaneous APIs - -* [Getting the etcd version](#getting-the-etcd-version) -* [Checking health of an etcd member node](#checking-health-of-an-etcd-member-node) +--- +title: Miscellaneous APIs +--- ## Getting the etcd version diff --git a/content/docs/v2/platforms/_index.md b/content/docs/v2/platforms/_index.md new file mode 100644 index 0000000000000..48a164f011b0d --- /dev/null +++ b/content/docs/v2/platforms/_index.md @@ -0,0 +1,3 @@ +--- +title: Platforms +--- diff --git a/content/docs/v2/platforms/freebsd.md b/content/docs/v2/platforms/freebsd.md index 891ea6f53dccd..1bba26cccce24 100644 --- a/content/docs/v2/platforms/freebsd.md +++ b/content/docs/v2/platforms/freebsd.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - -# FreeBSD +--- +title: FreeBS +--- Starting with version 0.1.2 both etcd and etcdctl have been ported to FreeBSD and can be installed either via packages or ports system. Their versions have been recently diff --git a/content/docs/v2/production-users.md b/content/docs/v2/production-users.md index addef2a926786..96a0cd722305a 100644 --- a/content/docs/v2/production-users.md +++ b/content/docs/v2/production-users.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Production Users +--- +title: Production Users +--- This document tracks people and use cases for etcd in production. By creating a list of production use cases we hope to build a community of advisors that we can reach out to with experience using various etcd applications, operation environments, and cluster sizes. The etcd development team may reach out periodically to check-in on your experience and update this list. diff --git a/content/docs/v2/proxy.md b/content/docs/v2/proxy.md index cba2cdf20886c..dce2779766617 100644 --- a/content/docs/v2/proxy.md +++ b/content/docs/v2/proxy.md @@ -1,9 +1,6 @@ -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - - -# Proxy +--- +title: Proxy +--- etcd can run as a transparent proxy. Doing so allows for easy discovery of etcd within your infrastructure, since it can run on each machine as a local service. In this mode, etcd acts as a reverse proxy and forwards client requests to an active etcd cluster. The etcd proxy does not participate in the consensus replication of the etcd cluster, thus it neither increases the resilience nor decreases the write performance of the etcd cluster. diff --git a/content/docs/v2/reporting_bugs.md b/content/docs/v2/reporting_bugs.md index 08291ea14dacf..34197cdede0cd 100644 --- a/content/docs/v2/reporting_bugs.md +++ b/content/docs/v2/reporting_bugs.md @@ -2,10 +2,6 @@ title: Reporting Bugs --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - If you find bugs or documentation mistakes in the etcd project, please let us know by [opening an issue][etcd-issue]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist. To make your bug report accurate and easy to understand, please try to create bug reports that are: @@ -28,19 +24,19 @@ We might ask you for further information to locate a bug. A duplicated bug repor ### How to get a stack trace -``` bash +```bash $ kill -QUIT $PID ``` ### How to get etcd version -``` bash +```bash $ etcd --version ``` ### How to get etcd configuration and log when it runs as systemd service ‘etcd2.service’ -``` bash +```bash $ sudo systemctl cat etcd2 $ sudo journalctl -u etcd2 ``` diff --git a/content/docs/v2/rfc/v3api.md b/content/docs/v2/rfc/v3api.md index dad1af31cbd30..4546dcc07c0dd 100644 --- a/content/docs/v2/rfc/v3api.md +++ b/content/docs/v2/rfc/v3api.md @@ -2,11 +2,6 @@ title: etcd v3 API --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../../docs.md#documentation - - # Overview The etcd v3 API is designed to give users a more efficient and cleaner abstraction compared to etcd v2. There are a number of semantic and protocol changes in this new API. For an overview [see Xiang Li's video](https://youtu.be/J5AioGtEPeQ?t=211). diff --git a/content/docs/v2/runtime-configuration.md b/content/docs/v2/runtime-configuration.md index fb1e920c7ffc1..3b1f8afa25eab 100644 --- a/content/docs/v2/runtime-configuration.md +++ b/content/docs/v2/runtime-configuration.md @@ -2,10 +2,6 @@ title: Runtime Reconfiguration --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - etcd comes with support for incremental runtime reconfiguration, which allows users to update the membership of the cluster at run time. Reconfiguration requests can only be processed when the majority of the cluster members are functioning. It is **highly recommended** to always have a cluster size greater than two in production. It is unsafe to remove a member from a two member cluster. The majority of a two member cluster is also two. If there is a failure during the removal process, the cluster might not able to make progress and need to [restart from majority failure][majority failure]. @@ -179,12 +175,12 @@ It is recommended to enable this option. However, it is disabled by default beca [add member]: #add-a-new-member [cluster-reconf]: #cluster-reconfiguration-operations -[conf-adv-peer]: configuration.md#-initial-advertise-peer-urls -[conf-name]: configuration.md#-name -[disaster recovery]: admin_guide.md#disaster-recovery -[fault tolerance table]: admin_guide.md#fault-tolerance-table +[conf-adv-peer]: ../configuration#-initial-advertise-peer-urls +[conf-name]: ../configuration#-name +[disaster recovery]: ../admin_guide#disaster-recovery +[fault tolerance table]: ../admin_guide#fault-tolerance-table [majority failure]: #restart-cluster-from-majority-failure -[member-api]: members_api.md -[member migration]: admin_guide.md#member-migration +[member-api]: ../members_api +[member migration]: ../admin_guide#member-migration [remove member]: #remove-a-member -[runtime-reconf]: runtime-reconf-design.md +[runtime-reconf]: ../runtime-reconf-design diff --git a/content/docs/v2/runtime-reconf-design.md b/content/docs/v2/runtime-reconf-design.md index 3ebdc75a5cba6..30e82bc6a9d73 100644 --- a/content/docs/v2/runtime-reconf-design.md +++ b/content/docs/v2/runtime-reconf-design.md @@ -2,10 +2,6 @@ title: Design of Runtime Reconfiguration --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - Runtime reconfiguration is one of the hardest and most error prone features in a distributed system, especially in a consensus based system like etcd. Read on to learn about the design of etcd's runtime reconfiguration commands and how we tackled these problems. @@ -52,5 +48,5 @@ It seems that using public discovery service is a convenient way to do runtime r If you want to have a discovery service that supports runtime reconfiguration, the best choice is to build your private one. -[add-member]: runtime-configuration.md#add-a-new-member -[disaster-recovery]: admin_guide.md#disaster-recovery +[add-member]: ../runtime-configuration#add-a-new-member +[disaster-recovery]: ../admin_guide#disaster-recovery diff --git a/content/docs/v2/security.md b/content/docs/v2/security.md index d551e1bd3924f..217397322269b 100644 --- a/content/docs/v2/security.md +++ b/content/docs/v2/security.md @@ -2,10 +2,6 @@ title: Security Model --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - etcd supports SSL/TLS as well as authentication through client certificates, both for clients to server as well as peer (server to server / cluster) communication. To get up and running you first need to have a CA certificate and a signed key pair for one member. It is recommended to create and sign a new key pair for every member in a cluster. @@ -197,4 +193,4 @@ If you need your certificate to be signed for your member's FQDN in its Subject [tls-setup]: ../../hack/tls-setup [tls-guide]: https://github.com/coreos/docs/blob/master/os/generate-self-signed-certificates.md [alt-name]: http://wiki.cacert.org/FAQ/subjectAltName -[auth]: authentication.md +[auth]: ../authentication diff --git a/content/docs/v2/tuning.md b/content/docs/v2/tuning.md index 59286986a2264..c676def7e4ac2 100644 --- a/content/docs/v2/tuning.md +++ b/content/docs/v2/tuning.md @@ -2,10 +2,6 @@ title: Tuning --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - The default settings in etcd should work well for installations on a local network where the average network latency is low. However, when using etcd across multiple data centers or over networks with high latency you may need to tweak the heartbeat interval and election timeout settings. diff --git a/content/docs/v2/upgrade_2_1.md b/content/docs/v2/upgrade_2_1.md index c73c186a9525c..0fb5374cdcedf 100644 --- a/content/docs/v2/upgrade_2_1.md +++ b/content/docs/v2/upgrade_2_1.md @@ -2,10 +2,6 @@ title: Upgrade etcd from 2.1 to 2.2 --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - In the general case, upgrading from etcd 2.0 to 2.1 can be a zero-downtime, rolling upgrade: - one by one, stop the etcd v2.0 processes and replace them with etcd v2.1 processes - after you are running all v2.1 processes, new features in v2.1 are available to the cluster @@ -117,6 +113,6 @@ $ curl http://127.0.0.1:4001/version {"etcdserver":"2.1.x","etcdcluster":"2.1.0"} ``` -[auth]: auth_api.md -[backup-datastore]: admin_guide.md#backing-up-the-datastore +[auth]: ../auth_api +[backup-datastore]: ../admin_guide#backing-up-the-datastore [v2.0]: https://github.com/coreos/etcd/releases/tag/v2.0.13 diff --git a/content/docs/v2/upgrade_2_2.md b/content/docs/v2/upgrade_2_2.md index 9ded0c27b74a3..6c9c7f12ec5f3 100644 --- a/content/docs/v2/upgrade_2_2.md +++ b/content/docs/v2/upgrade_2_2.md @@ -2,10 +2,6 @@ title: Upgrade etcd from 2.1 to 2.2 --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - In the general case, upgrading from etcd 2.1 to 2.2 can be a zero-downtime, rolling upgrade: - one by one, stop the etcd v2.1 processes and replace them with etcd v2.2 processes @@ -133,6 +129,6 @@ $ curl http://127.0.0.1:4001/version {"etcdserver":"2.2.x","etcdcluster":"2.2.0"} ``` -[backup-datastore]: admin_guide.md#backing-up-the-datastore +[backup-datastore]: ../admin_guide#backing-up-the-datastore [downgrade]: #downgrade [v2.1]: https://github.com/coreos/etcd/releases/tag/v2.1.2 diff --git a/content/docs/v2/upgrade_2_3.md b/content/docs/v2/upgrade_2_3.md index ef3f8d4c83be8..b69647c5c7995 100644 --- a/content/docs/v2/upgrade_2_3.md +++ b/content/docs/v2/upgrade_2_3.md @@ -2,10 +2,6 @@ title: Upgrade etcd from 2.2 to 2.3 --- -**This is the documentation for etcd2 releases. Read [etcd3 doc][v3-docs] for etcd3 releases.** - -[v3-docs]: ../docs.md#documentation - In the general case, upgrading from etcd 2.2 to 2.3 can be a zero-downtime, rolling upgrade: - one by one, stop the etcd v2.2 processes and replace them with etcd v2.3 processes - after running all v2.3 processes, new features in v2.3 are available to the cluster