Merge pull request #3204 from endocode/kayrus/recovery

Improved "disaster restore" doc, added "member update" command descri…

Documentation/admin_guide.md

@@ -11,14 +11,14 @@ The write ahead log and snapshot files are used during member operation and to r
 Having a dedicated disk to store wal files can improve the throughput and stabilize the cluster. 
 It is highly recommended to dedicate a wal disk and set `--wal-dir` to point to a directory on that device for a production cluster deployment.
 
-If a member’s data directory is ever lost or corrupted then the user should remove the etcd member from the cluster via the [members API][members-api].
+If a member’s data directory is ever lost or corrupted then the user should [remove][remove-a-member] the etcd member from the cluster using `etcdctl` tool.
 
 A user should avoid restarting an etcd member with a data directory from an out-of-date backup.
 Using an out-of-date data directory can lead to inconsistency as the member had agreed to store information via raft then re-joins saying it needs that information again.
 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]: other_apis.md#members-api
+[remove-a-member]: runtime-configuration.md#remove-a-member
 
 #### Contents
 
@@ -130,7 +130,7 @@ As you can see, adding another member to bring the size of cluster up to an odd
 
 #### Changing Cluster Size
 
-After your cluster is up and running, adding or removing members is done via [runtime reconfiguration](runtime-configuration.md), which allows the cluster to be modified without downtime. The `etcdctl` tool has a `member list`, `member add` and `member remove` commands to complete this process.
+After your cluster is up and running, adding or removing members is done via [runtime reconfiguration](runtime-configuration.md#cluster-reconfiguration-operations), which allows the cluster to be modified without downtime. The `etcdctl` tool has a `member list`, `member add` and `member remove` commands to complete this process.
 
 ### Member Migration
 
@@ -140,7 +140,7 @@ The data directory contains all the data to recover a member to its point-in-tim
 
 * Stop the member process
 * Copy the data directory of the now-idle member to the new machine
-* Update the peer URLs for that member to reflect the new machine according to the [member api] [change peer url]
+* Update the peer URLs for that member to reflect the new machine according to the [runtime configuration] [change peer url]
 * Start etcd on the new machine, using the same configuration and the copy of the data directory
 
 This example will walk you through the process of migrating the infra1 member to a new machine:
@@ -151,11 +151,11 @@ This example will walk you through the process of migrating the infra1 member to
 |infra1|10.0.1.11:2380|
 |infra2|10.0.1.12:2380|
 
-```
+```sh
 $ export ETCDCTL_PEERS=http://10.0.1.10:2379,http://10.0.1.11:2379,http://10.0.1.12:2379
 ```
 
-```
+```sh
 $ etcdctl member list
 84194f7c5edd8b37: name=infra0 peerURLs=http://10.0.1.10:2380 clientURLs=http://127.0.0.1:2379,http://10.0.1.10:2379
 b4db3bf5e495e255: name=infra1 peerURLs=http://10.0.1.11:2380 clientURLs=http://127.0.0.1:2379,http://10.0.1.11:2379
@@ -164,11 +164,11 @@ bc1083c870280d44: name=infra2 peerURLs=http://10.0.1.12:2380 clientURLs=http://1
 
 #### Stop the member etcd process
 
-```
+```sh
 $ ssh 10.0.1.11
 ```
 
-```
+```sh
 $ kill `pgrep etcd`
 ```
 
@@ -178,24 +178,30 @@ $ kill `pgrep etcd`
 $ tar -cvzf infra1.etcd.tar.gz %data_dir%
 ```
 
-```
+```sh
 $ scp infra1.etcd.tar.gz 10.0.1.13:~/
 ```
 
 #### Update the peer URLs for that member to reflect the new machine
 
-```
+```sh
 $ curl http://10.0.1.10:2379/v2/members/b4db3bf5e495e255 -XPUT \
 -H "Content-Type: application/json" -d '{"peerURLs":["http://10.0.1.13:2380"]}'
 ```
 
-#### Start etcd on the new machine, using the same configuration and the copy of the data directory
+Or use `etcdctl member update` command
 
+```sh
+$ etcdctl member update b4db3bf5e495e255 http://10.0.1.13:2380
 ```
+
+#### Start etcd on the new machine, using the same configuration and the copy of the data directory
+
+```sh
 $ ssh 10.0.1.13
 ```
 
-```
+```sh
 $ tar -xzvf infra1.etcd.tar.gz -C %data_dir%
 ```
 
@@ -206,7 +212,7 @@ etcd -name infra1 \
 -advertise-client-urls http://10.0.1.13:2379,http://127.0.0.1:2379
 ```
 
-[change peer url]: other_apis.md#change-the-peer-urls-of-a-member
+[change peer url]: runtime-configuration.md#update-a-member
 
 ### Disaster Recovery
 
@@ -254,9 +260,9 @@ Once you have verified that etcd has started successfully, shut it down and move
 
 #### Restoring the cluster
 
-Now that the node is running successfully, you should [change its advertised peer URLs](other_apis.md#change-the-peer-urls-of-a-member), as the `--force-new-cluster` has set the peer URL to the default (listening on localhost).
+Now that if the node is running successfully, you should [change its advertised peer URLs](runtime-configuration.md#update-a-member), as the `--force-new-cluster` has set the peer URL to the default (listening on localhost).
 
-You can then add more nodes to the cluster and restore resiliency. See the [runtime configuration](runtime-configuration.md) guide for more details.
+You can then add more nodes to the cluster and restore resiliency. See the [add a new member](runtime-configuration.md#add-a-new-member) guide for more details. **NB:** If you are trying to restore your cluster using old failed etcd nodes, please make sure you have stopped old etcd instances and removed their old data directories specified by the data-dir configuration parameter.
 
 ### Client Request Timeout
 

Documentation/runtime-configuration.md

@@ -39,7 +39,7 @@ To replace the machine, follow the instructions for [removing the member][remove
 
 ### Restart Cluster from Majority Failure
 
-If the majority of your cluster is lost, then you need to take manual action in order to recover safely.
+If the majority of your cluster is lost or all of your nodes have changed IP addresses, then you need to take manual action in order to recover safely.
 The basic steps in the recovery process include [creating a new cluster using the old data][disaster recovery], forcing a single member to act as the leader, and finally using runtime configuration to [add new members][add member] to this new cluster one at a time.
 
 [add member]: #add-a-new-member
@@ -54,28 +54,38 @@ This is essentially the same requirement as for any other write to etcd.
 
 All changes to the cluster are done one at a time:
 
-To replace a single member you will make an add then a remove operation
-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
+* To update a single member peerURLs you will make an update operation
+* To replace a single member you will make an add then a remove operation
+* 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](other_apis.md).
 
-### Remove a Member
+### Update a Member
 
-First, we need to find the target member's ID. You can list all members with `etcdctl`:
+If you would like to update a member IP address (peerURLs), first, we need to find the target member's ID. You can list all members with `etcdctl`:
 
-```
+```sh
 $ etcdctl member list
-6e3bd23ae5f1eae0: name=node2 peerURLs=http://localhost:7002 clientURLs=http://127.0.0.1:4002
-924e2e83e93f2560: name=node3 peerURLs=http://localhost:7003 clientURLs=http://127.0.0.1:4003
-a8266ecf031671f3: name=node1 peerURLs=http://localhost:7001 clientURLs=http://127.0.0.1:4001
+6e3bd23ae5f1eae0: name=node2 peerURLs=http://localhost:23802 clientURLs=http://127.0.0.1:23792
+924e2e83e93f2560: name=node3 peerURLs=http://localhost:23803 clientURLs=http://127.0.0.1:23793
+a8266ecf031671f3: name=node1 peerURLs=http://localhost:23801 clientURLs=http://127.0.0.1:23791
 ```
 
+In this example let's `update` a8266ecf031671f3 member ID and change its peerURLs value to http://10.0.1.10:2380
+
+```sh
+$ etcdctl member update b4db3bf5e495e255 http://10.0.1.10:2380
+Updated member with ID b4db3bf5e495e255 in cluster
+```
+
+### Remove a Member
+
 Let us say the member ID we want to remove is a8266ecf031671f3.
 We then use the `remove` command to perform the removal:
 
-```
+```sh
 $ etcdctl member remove a8266ecf031671f3
 Removed member a8266ecf031671f3 from cluster
 ```
@@ -97,7 +107,7 @@ Adding a member is a two step process:
 
 Using `etcdctl` let's add the new member to the cluster by specifying its [name](configuration.md#-name) and [advertised peer URLs](configuration.md#-initial-advertise-peer-urls):
 
-```
+```sh
 $ etcdctl member add infra3 http://10.0.1.13:2380
 added member 9bf1b35fc7761a23 to cluster
 
@@ -109,11 +119,11 @@ ETCD_INITIAL_CLUSTER_STATE=existing
 `etcdctl` has informed the cluster about the new member and printed out the environment variables needed to successfully start it.
 Now start the new etcd process with the relevant flags for the new member:
 
-```
+```sh
 $ export ETCD_NAME="infra3"
 $ export ETCD_INITIAL_CLUSTER="infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380,infra3=http://10.0.1.13:2380"
 $ export ETCD_INITIAL_CLUSTER_STATE=existing
-$ etcd -listen-client-urls http://10.0.1.13:2379 -advertise-client-urls http://10.0.1.13:2379  -listen-peer-urls http://10.0.1.13:2380 -initial-advertise-peer-urls http://10.0.1.13:2380
+$ etcd -listen-client-urls http://10.0.1.13:2379 -advertise-client-urls http://10.0.1.13:2379  -listen-peer-urls http://10.0.1.13:2380 -initial-advertise-peer-urls http://10.0.1.13:2380 -data-dir %data_dir%
 ```
 
 The new member will run as a part of the cluster and immediately begin catching up with the rest of the cluster.
@@ -126,7 +136,7 @@ If you add a new member to a 1-node cluster, the cluster cannot make progress be
 In the following case we have not included our new host in the list of enumerated nodes.
 If this is a new cluster, the node must be added to the list of initial cluster members.
 
-```
+```sh
 $ etcd -name infra3 \
   -initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380 \
   -initial-cluster-state existing
@@ -136,7 +146,7 @@ exit 1
 
 In this case we give a different address (10.0.1.14:2380) to the one that we used to join the cluster (10.0.1.13:2380).
 
-```
+```sh
 $ etcd -name infra4 \
   -initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380,infra4=http://10.0.1.14:2380 \
   -initial-cluster-state existing
@@ -146,7 +156,7 @@ exit 1
 
 When we start etcd using the data directory of a removed member, etcd will exit automatically if it connects to any alive member in the cluster:
 
-```
+```sh
 $ etcd
 etcd: this member has been permanently removed from the cluster. Exiting.
 exit 1