mirror of
https://github.com/etcd-io/etcd.git
synced 2024-09-27 06:25:44 +00:00
Documentation: update to 2.0
In anticipation for a 2.0.0-rc.0 release update and move the documentation.
This commit is contained in:
parent
35a772753c
commit
fa35363f74
@ -1,10 +1,10 @@
|
||||
## etcd 0.4.x -> 0.5.0 Data Migration Tool
|
||||
## etcd 0.4.x -> 2.0.0 Data Migration Tool
|
||||
|
||||
### Upgrading from 0.4.x
|
||||
|
||||
Between 0.4.x and 0.5, the on-disk data formats have changed. In order to allow users to convert to 0.5, a migration tool is provided.
|
||||
Between 0.4.x and 2.0, the on-disk data formats have changed. In order to allow users to convert to 2.0, a migration tool is provided.
|
||||
|
||||
In the early 0.5.0-alpha series, we're providing this tool early to encourage adoption. However, before 0.5.0-release, etcd will autodetect the 0.4.x data dir upon upgrade and automatically update the data too (while leaving a backup, in case of emergency).
|
||||
In the early 2.0.0-alpha series, we're providing this tool early to encourage adoption. However, before 2.0.0-release, etcd will autodetect the 0.4.x data dir upon upgrade and automatically update the data too (while leaving a backup, in case of emergency).
|
||||
|
||||
### Data Migration Tips
|
||||
|
||||
@ -18,7 +18,7 @@ The tool can be run via:
|
||||
./bin/etcd-migrate --data-dir=<PATH TO YOUR DATA>
|
||||
```
|
||||
|
||||
It should autodetect everything and convert the data-dir to be 0.5 compatible. It does not remove the 0.4.x data, and is safe to convert multiple times; the 0.5 data will be overwritten. Recovering the disk space once everything is settled is covered later in the document.
|
||||
It should autodetect everything and convert the data-dir to be 2.0 compatible. It does not remove the 0.4.x data, and is safe to convert multiple times; the 2.0 data will be overwritten. Recovering the disk space once everything is settled is covered later in the document.
|
||||
|
||||
If, however, it complains about autodetecting the name (which can happen, depending on how the cluster was configured), you need to supply the name of this particular node. This is equivalent to the `--name` flag (or `ETCD_NAME` variable) that etcd was run with, which can also be found by accessing the self api, eg:
|
||||
|
||||
@ -38,10 +38,10 @@ And the tool should migrate successfully. If it still has an error at this time,
|
||||
|
||||
### Recovering Disk Space
|
||||
|
||||
If the conversion has completed, the entire cluster is running on something 0.5-based, and the disk space is important, the following command will clear 0.4.x data from the data-dir:
|
||||
If the conversion has completed, the entire cluster is running on something 2.0-based, and the disk space is important, the following command will clear 0.4.x data from the data-dir:
|
||||
|
||||
```sh
|
||||
rm -ri snapshot conf log
|
||||
```
|
||||
|
||||
It will ask before every deletion, but these are the 0.4.x files and will not affect the working 0.5 data.
|
||||
It will ask before every deletion, but these are the 0.4.x files and will not affect the working 2.0 data.
|
@ -15,7 +15,7 @@ Using an out-of-date data directory can lead to inconsistency as the member had
|
||||
For maximum safety, if an etcd member suffers any sort of data corruption or loss, it must be removed from the cluster.
|
||||
Once removed the member can be re-added with an empty data directory.
|
||||
|
||||
[members-api]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md#members-api
|
||||
[members-api]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/other_apis.md#members-api
|
||||
|
||||
#### Contents
|
||||
|
||||
@ -106,7 +106,7 @@ etcd -name node1 \
|
||||
-advertise-client-urls http://10.0.1.13:2379,http://127.0.0.1:2379
|
||||
```
|
||||
|
||||
[change peer url]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md#change-the-peer-urls-of-a-member
|
||||
[change peer url]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/other_apis.md#change-the-peer-urls-of-a-member
|
||||
|
||||
### Disaster Recovery
|
||||
|
@ -1,6 +1,6 @@
|
||||
### Backward Compatibility
|
||||
|
||||
The main goal of etcd 0.5 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 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.
|
||||
|
||||
@ -16,35 +16,35 @@ The major flag changes are to mostly related to bootstrapping. The `initial-*` f
|
||||
- `-peers-file` is replaced by `-initial-cluster`.
|
||||
|
||||
The documentation of new command line flags can be found at
|
||||
https://github.com/coreos/etcd/blob/master/Documentation/0.5/configuration.md.
|
||||
https://github.com/coreos/etcd/blob/master/Documentation/2.0/configuration.md.
|
||||
|
||||
#### Data Dir
|
||||
- Default data dir location has changed from {$hostname}.etcd to {name}.etcd.
|
||||
|
||||
- The disk format within the data dir has changed. etcd 0.5 should be able to auto upgrade the old data format. Instructions on doing so manually are in the [migration tool doc][migrationtooldoc].
|
||||
- The disk format within the data dir has changed. etcd 2.0 should be able to auto upgrade the old data format. Instructions on doing so manually are in the [migration tool doc][migrationtooldoc].
|
||||
|
||||
[migrationtooldoc]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/0_4_migration_tool.md
|
||||
[migrationtooldoc]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/0_4_migration_tool.md
|
||||
|
||||
#### Standby
|
||||
|
||||
etcd 0.4’s standby mode has been deprecated by 0.5’s [proxy mode][proxymode].
|
||||
etcd 0.4’s standby mode has been deprecated by 2.0’s [proxy mode][proxymode].
|
||||
|
||||
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 0.5 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.
|
||||
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]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/proxy.md
|
||||
[proxymode]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/proxy.md
|
||||
|
||||
#### Discovery Service
|
||||
|
||||
A size key needs to be provided inside a [discovery token][discoverytoken].
|
||||
[discoverytoken]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/clustering.md#custom-etcd-discovery-service
|
||||
[discoverytoken]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/clustering.md#custom-etcd-discovery-service
|
||||
|
||||
#### HTTP Admin API
|
||||
|
||||
`v2/admin` on peer url and `v2/keys/_etcd` are unified under the new [v2/member API][memberapi] to better explain which machines are part of an etcd cluster, and to simplify the keyspace for all your use cases.
|
||||
|
||||
[memberapi]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md
|
||||
[memberapi]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/other_apis.md
|
||||
|
||||
#### HTTP Key Value API
|
||||
- The follower can now transparently proxy write equests to the leader. Clients will no longer see 307 redirections to the leader from etcd.
|
@ -97,7 +97,7 @@ A discovery URL identifies a unique etcd cluster. Instead of reusing a discovery
|
||||
|
||||
Moreover, discovery URLs should ONLY be used for the initial bootstrapping of a cluster. To change cluster membership after the cluster is already running, see the [runtime reconfiguration][runtime] guide.
|
||||
|
||||
[runtime]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/runtime-configuration.md
|
||||
[runtime]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/runtime-configuration.md
|
||||
|
||||
### Custom etcd discovery service
|
||||
|
||||
@ -217,9 +217,9 @@ $ etcd -name infra0 -initial-advertise-peer-urls http://10.0.1.10:2380 \
|
||||
etcdserver: discovery token ignored since a cluster has already been initialized. Valid log found at /var/lib/etcd
|
||||
```
|
||||
|
||||
# 0.4 to 0.5+ Migration Guide
|
||||
# 0.4 to 2.0+ Migration Guide
|
||||
|
||||
In etcd 0.5 we introduced the ability to listen on more than one address and to advertise multiple addresses. This makes using etcd easier when you have complex networking, such as private and public networks on various cloud providers.
|
||||
In etcd 2.0 we introduced the ability to listen on more than one address and to advertise multiple addresses. This makes using etcd easier when you have complex networking, such as private and public networks on various cloud providers.
|
||||
|
||||
To make understanding this feature easier, we changed the naming of some flags, but we support the old flags to make the migration from the old to new version easier.
|
||||
|
@ -131,9 +131,9 @@ Be CAUTIOUS to use unsafe flags because it will break the guarantee given by con
|
||||
+ Print the version and exit.
|
||||
+ default: false
|
||||
|
||||
[build-cluster]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/clustering.md#static
|
||||
[reconfig]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/runtime-configuration.md
|
||||
[discovery]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/clustering.md#discovery
|
||||
[proxy]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/proxy.md
|
||||
[build-cluster]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/clustering.md#static
|
||||
[reconfig]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/runtime-configuration.md
|
||||
[discovery]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/clustering.md#discovery
|
||||
[proxy]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/proxy.md
|
||||
[security]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
|
||||
[restore]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/admin_guide.md#restoring-a-backup
|
||||
[restore]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/admin_guide.md#restoring-a-backup
|
@ -28,4 +28,4 @@ Client is a caller of the cluster's HTTP API.
|
||||
|
||||
### Machine (deprecated)
|
||||
|
||||
The alternative of Member in etcd before 0.5
|
||||
The alternative of Member in etcd before 2.0
|
@ -29,4 +29,4 @@ etcd -proxy on -client-listen-urls 127.0.0.1:8080 -discovery https://discovery.
|
||||
#### Fallback to proxy mode with discovery service
|
||||
If you bootstrap a etcd cluster using [discovery service][discovery-service] with more than the expected number of etcd members, the extra etcd processes will fall back to being `readwrite` proxies by default. They will forward the requests to the cluster as described above. For example, if you create a discovery url with `size=5`, and start ten etcd processes using that same discovery URL, the result will be a cluster with five etcd members and five proxies. Note that this behaviour can be disabled with the `proxy-fallback` flag.
|
||||
|
||||
[discovery-service]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/clustering.md#discovery
|
||||
[discovery-service]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/clustering.md#discovery
|
@ -14,7 +14,7 @@ If etcd falls below a simple majority of members it can no longer accept writes:
|
||||
|
||||
If you want to migrate a running member to another machine, please refer [member migration section][member migration].
|
||||
|
||||
[member migration]: https://github.com/coreos/etcd/blob/master/Documentation/0.5/admin_guide.md#member-migration
|
||||
[member migration]: https://github.com/coreos/etcd/blob/master/Documentation/2.0/admin_guide.md#member-migration
|
||||
|
||||
### Increase Cluster Size
|
||||
|
||||
@ -53,7 +53,7 @@ To increase from 3 to 5 members you will make two add operations
|
||||
To decrease from 5 to 3 you will make two remove operations
|
||||
|
||||
All of these examples will use the `etcdctl` command line tool that ships with etcd.
|
||||
If you want to use the member API directly you can find the documentation [here](https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md).
|
||||
If you want to use the member API directly you can find the documentation [here](https://github.com/coreos/etcd/blob/master/Documentation/2.0/other_apis.md).
|
||||
|
||||
### Remove a Member
|
||||
|
||||
@ -86,7 +86,7 @@ Removal of the leader is safe, but the cluster will be out of progress for a per
|
||||
|
||||
Adding a member is a two step process:
|
||||
|
||||
* Add the new member to the cluster via the [members API](https://github.com/coreos/etcd/blob/master/Documentation/0.5/other_apis.md#post-v2members) or the `etcdctl member add` command.
|
||||
* Add the new member to the cluster via the [members API](https://github.com/coreos/etcd/blob/master/Documentation/2.0/other_apis.md#post-v2members) or the `etcdctl member add` command.
|
||||
* Start the member with the correct configuration.
|
||||
|
||||
Using `etcdctl` let's add the new member to the cluster:
|
@ -3,13 +3,14 @@
|
||||
[](https://travis-ci.org/coreos/etcd)
|
||||
[](https://quay.io/repository/coreos/etcd-git)
|
||||
|
||||
### WARNING ###
|
||||
### Release Candidate Warning ###
|
||||
|
||||
The current `master` branch of etcd is under heavy development in anticipation of the forthcoming 0.5.0 release.
|
||||
The current `master` branch of etcd is under development in anticipation of the forthcoming 2.0.0 release.
|
||||
|
||||
It is strongly recommended that users work with the latest 0.4.x release (0.4.6), which can be found on the [releases](https://github.com/coreos/etcd/releases) page.
|
||||
|
||||
Unless otherwise noted, the etcd documentation refers to configuring and running 0.4.x releases.
|
||||
Documentation related to the 2.0.0 release candidates can be found in the `Documentation/2.0` directory.
|
||||
|
||||
## README version 0.4.6
|
||||
|
||||
|
@ -42,7 +42,7 @@ function package {
|
||||
cp etcd/README.md ${target}/README.md
|
||||
cp etcd/etcdctl/README.md ${target}/README-etcdctl.md
|
||||
|
||||
cp -R etcd/Documentation/0.5 ${target}/Documentation
|
||||
cp -R etcd/Documentation/2.0 ${target}/Documentation
|
||||
}
|
||||
|
||||
function main {
|
||||
|
Loading…
x
Reference in New Issue
Block a user