From f4b8e878edfb5fb192008418ffe5c1ac63bb0987 Mon Sep 17 00:00:00 2001 From: Gyu-Ho Lee Date: Wed, 27 Apr 2016 11:29:36 -0700 Subject: [PATCH] Documentation: delete upgrade_2_* from v3 doc dir --- Documentation/upgrade_2_1.md | 116 ------------------------------ Documentation/upgrade_2_2.md | 132 ----------------------------------- Documentation/upgrade_2_3.md | 121 -------------------------------- 3 files changed, 369 deletions(-) delete mode 100644 Documentation/upgrade_2_1.md delete mode 100644 Documentation/upgrade_2_2.md delete mode 100644 Documentation/upgrade_2_3.md diff --git a/Documentation/upgrade_2_1.md b/Documentation/upgrade_2_1.md deleted file mode 100644 index 8c83db953..000000000 --- a/Documentation/upgrade_2_1.md +++ /dev/null @@ -1,116 +0,0 @@ -# Upgrade etcd to 2.1 - -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 - -Before [starting an upgrade](#upgrade-procedure), read through the rest of this guide to prepare. - -## Upgrade Checklists - -### Upgrade Requirements - -To upgrade an existing etcd deployment to 2.1, you must be running 2.0. If you’re running a version of etcd before 2.0, you must upgrade to [2.0][v2.0] before upgrading to 2.1. - -Also, to ensure a smooth rolling upgrade, your running cluster must be healthy. You can check the health of the cluster by using `etcdctl cluster-health` command. - -### Preparedness - -Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. - -You might also want to [backup your data directory][backup-datastore] for a potential [downgrade](#downgrade). - -etcd 2.1 introduces a new [authentication][auth] feature, which is disabled by default. If your deployment depends on these, you may want to test the auth features before enabling them in production. - -### Mixed Versions - -While upgrading, an etcd cluster supports mixed versions of etcd members. The cluster is only considered upgraded once all its members are upgraded to 2.1. - -Internally, etcd members negotiate with each other to determine the overall etcd cluster version, which controls the reported cluster version and the supported features. For example, if you are mid-upgrade, any 2.1 features (such as the the authentication feature mentioned above) won’t be available. - -### Limitations - -If you encounter any issues during the upgrade, you can attempt to restart the etcd process in trouble using a newer v2.1 binary to solve the problem. One known issue is that etcd v2.0.0 and v2.0.2 may panic during rolling upgrades due to an existing bug, which has been fixed since etcd v2.0.3. - -It might take up to 2 minutes for the newly upgraded member to catch up with the existing cluster when the total data size is larger than 50MB (You can check the size of the existing snapshot to know about the rough data size). In other words, it is safest to wait for 2 minutes before upgrading the next member. - -If you have even more data, this might take more time. If you have a data size larger than 100MB you should contact us before upgrading, so we can make sure the upgrades work smoothly. - -### Downgrade - -If all members have been upgraded to v2.1, the cluster will be upgraded to v2.1, and downgrade is **not possible**. If any member is still v2.0, the cluster will remain in v2.0, and you can go back to use v2.0 binary. - -Please [backup your data directory][backup-datastore] of all etcd members if you want to downgrade the cluster, even if it is upgraded. - -### Upgrade Procedure - -#### 1. Check upgrade requirements. - -``` -$ etcdctl cluster-health -cluster is healthy -member 6e3bd23ae5f1eae0 is healthy -member 924e2e83e93f2560 is healthy -member a8266ecf031671f3 is healthy - -$ curl http://127.0.0.1:4001/version -etcd 2.0.x -``` - -#### 2. Stop the existing etcd process - -You will see similar error logging from other etcd processes in your cluster. This is normal, since you just shut down a member. - -``` -2015/06/23 15:45:09 sender: error posting to 6e3bd23ae5f1eae0: dial tcp 127.0.0.1:7002: connection refused -2015/06/23 15:45:09 sender: the connection with 6e3bd23ae5f1eae0 became inactive -2015/06/23 15:45:11 rafthttp: encountered error writing to server log stream: write tcp 127.0.0.1:53783: broken pipe -2015/06/23 15:45:11 rafthttp: server streaming to 6e3bd23ae5f1eae0 at term 2 has been stopped -2015/06/23 15:45:11 stream: error sending message: stopped -2015/06/23 15:45:11 stream: stopping the stream server... -``` - -You could [backup your data directory][backup-datastore] for data safety. - -``` -$ etcdctl backup \ - --data-dir /var/lib/etcd \ - --backup-dir /tmp/etcd_backup -``` - -#### 3. Drop-in etcd v2.1 binary and start the new etcd process - -You will see the etcd publish its information to the cluster. - -``` -2015/06/23 15:45:39 etcdserver: published {Name:infra2 ClientURLs:[http://localhost:4002]} to cluster e9c7614f68f35fb2 -``` - -You could verify the cluster becomes healthy. - -``` -$ etcdctl cluster-health -cluster is healthy -member 6e3bd23ae5f1eae0 is healthy -member 924e2e83e93f2560 is healthy -member a8266ecf031671f3 is healthy -``` - -#### 4. Repeat step 2 to step 3 for all other members - -#### 5. Finish - -When all members are upgraded, you will see the cluster is upgraded to 2.1 successfully: - -``` -2015/06/23 15:46:35 etcdserver: updated the cluster version from 2.0.0 to 2.1.0 -``` - -``` -$ 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 -[v2.0]: https://github.com/coreos/etcd/releases/tag/v2.0.13 diff --git a/Documentation/upgrade_2_2.md b/Documentation/upgrade_2_2.md deleted file mode 100644 index 2f3edb005..000000000 --- a/Documentation/upgrade_2_2.md +++ /dev/null @@ -1,132 +0,0 @@ -# Upgrade etcd from 2.1 to 2.2 - -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 - - after you are running all v2.2 processes, new features in v2.2 are available to the cluster - -Before [starting an upgrade](#upgrade-procedure), read through the rest of this guide to prepare. - -## Upgrade Checklists - -### Upgrade Requirement - -To upgrade an existing etcd deployment to 2.2, you must be running 2.1. If you’re running a version of etcd before 2.1, you must upgrade to [2.1][v2.1] before upgrading to 2.2. - -Also, to ensure a smooth rolling upgrade, your running cluster must be healthy. You can check the health of the cluster by using `etcdctl cluster-health` command. - -### Preparedness - -Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. - -You might also want to [backup the data directory][backup-datastore] for a potential [downgrade]. - -### Mixed Versions - -While upgrading, an etcd cluster supports mixed versions of etcd members. The cluster is only considered upgraded once all its members are upgraded to 2.2. - -Internally, etcd members negotiate with each other to determine the overall etcd cluster version, which controls the reported cluster version and the supported features. - -### Limitations - -If you have a data size larger than 100MB you should contact us before upgrading, so we can make sure the upgrades work smoothly. - -Every etcd 2.2 member will do health checking across the cluster periodically. etcd 2.1 member does not support health checking. During the upgrade, etcd 2.2 member will log warning about the unhealthy state of etcd 2.1 member. You can ignore the warning. - -### Downgrade - -If all members have been upgraded to v2.2, the cluster will be upgraded to v2.2, and downgrade is **not possible**. If any member is still v2.1, the cluster will remain in v2.1, and you can go back to use v2.1 binary. - -Please [backup the data directory][backup-datastore] of all etcd members if you want to downgrade the cluster, even if it is upgraded. - -### Upgrade Procedure - -In the example, we upgrade a three member v2.1 cluster running on local machine. - -#### 1. Check upgrade requirements. - -``` -$ etcdctl cluster-health -member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379 -member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379 -member a8266ecf031671f3 is healthy: got healthy result from http://localhost:12379 -cluster is healthy - -$ curl http://localhost:4001/version -{"etcdserver":"2.1.x","etcdcluster":"2.1.0"} -``` - -#### 2. Stop the existing etcd process - -You will see similar error logging from other etcd processes in your cluster. This is normal, since you just shut down a member and the connection is broken. - -``` -2015/09/2 09:48:35 etcdserver: failed to reach the peerURL(http://localhost:12380) of member a8266ecf031671f3 (Get http://localhost:12380/version: dial tcp [::1]:12380: getsockopt: connection refused) -2015/09/2 09:48:35 etcdserver: cannot get the version of member a8266ecf031671f3 (Get http://localhost:12380/version: dial tcp [::1]:12380: getsockopt: connection refused) -2015/09/2 09:48:35 rafthttp: failed to write a8266ecf031671f3 on stream Message (write tcp 127.0.0.1:32380->127.0.0.1:64394: write: broken pipe) -2015/09/2 09:48:35 rafthttp: failed to write a8266ecf031671f3 on pipeline (dial tcp [::1]:12380: getsockopt: connection refused) -2015/09/2 09:48:40 etcdserver: failed to reach the peerURL(http://localhost:7001) of member a8266ecf031671f3 (Get http://localhost:7001/version: dial tcp [::1]:12380: getsockopt: connection refused) -2015/09/2 09:48:40 etcdserver: cannot get the version of member a8266ecf031671f3 (Get http://localhost:12380/version: dial tcp [::1]:12380: getsockopt: connection refused) -2015/09/2 09:48:40 rafthttp: failed to heartbeat a8266ecf031671f3 on stream MsgApp v2 (write tcp 127.0.0.1:32380->127.0.0.1:64393: write: broken pipe) -``` - -You will see logging output like this from ungraded member due to a mixed version cluster. You can ignore this while upgrading. - -``` -2015/09/2 09:48:45 etcdserver: the etcd version 2.1.2+git is not up-to-date -2015/09/2 09:48:45 etcdserver: member a8266ecf031671f3 has a higher version &{2.2.0-rc.0+git 2.1.0} -``` - -You will also see logging output like this from the newly upgraded member, since etcd 2.1 member does not support health checking. You can ignore this while upgrading. - -``` -2015-09-02 09:55:42.691384 W | rafthttp: the connection to peer 6e3bd23ae5f1eae0 is unhealthy -2015-09-02 09:55:42.705626 W | rafthttp: the connection to peer 924e2e83e93f2560 is unhealthy - -``` - -[Backup your data directory][backup-datastore] for data safety. - -``` -$ etcdctl backup \ - --data-dir /var/lib/etcd \ - --backup-dir /tmp/etcd_backup -``` - -#### 3. Drop-in etcd v2.2 binary and start the new etcd process - -Now, you can start the etcd v2.2 binary with the previous configuration. -You will see the etcd start and publish its information to the cluster. - -``` -2015-09-02 09:56:46.117609 I | etcdserver: published {Name:infra2 ClientURLs:[http://localhost:22380]} to cluster e9c7614f68f35fb2 -``` - -You could verify the cluster becomes healthy. - -``` -$ etcdctl cluster-health -member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379 -member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379 -member a8266ecf031671f3 is healthy: got healthy result from http://localhost:12379 -cluster is healthy -``` - -#### 4. Repeat step 2 to step 3 for all other members - -#### 5. Finish - -When all members are upgraded, you will see the cluster is upgraded to 2.2 successfully: - -``` -2015-09-02 09:56:54.896848 N | etcdserver: updated the cluster version from 2.1 to 2.2 -``` - -``` -$ 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 -[downgrade]: #downgrade -[v2.1]: https://github.com/coreos/etcd/releases/tag/v2.1.2 diff --git a/Documentation/upgrade_2_3.md b/Documentation/upgrade_2_3.md deleted file mode 100644 index 34d948e6a..000000000 --- a/Documentation/upgrade_2_3.md +++ /dev/null @@ -1,121 +0,0 @@ -## Upgrade etcd from 2.2 to 2.3 - -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 - -Before [starting an upgrade](#upgrade-procedure), read through the rest of this guide to prepare. - -### Upgrade Checklists - -#### Upgrade Requirements - -To upgrade an existing etcd deployment to 2.3, the running cluster must be 2.2 or greater. If it's before 2.2, please upgrade to [2.2](https://github.com/coreos/etcd/releases/tag/v2.2.0) before upgrading to 2.3. - -Also, to ensure a smooth rolling upgrade, the running cluster must be healthy. You can check the health of the cluster by using the `etcdctl cluster-health` command. - -#### Preparation - -Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. - -Before beginning, [backup the etcd data directory](admin_guide.md#backing-up-the-datastore). Should something go wrong with the upgrade, it is possible to use this backup to[downgrade](#downgrade) back to existing etcd version. - -#### Mixed Versions - -While upgrading, an etcd cluster supports mixed versions of etcd members, and operates with the protocol of the lowest common version. The cluster is only considered upgraded once all of its members are upgraded to version 2.3. Internally, etcd members negotiate with each other to determine the overall cluster version, which controls the reported version and the supported features. - -#### Limitations - -It might take up to 2 minutes for the newly upgraded member to catch up with the existing cluster when the total data size is larger than 50MB. Check the size of a recent snapshot to estimate the total data size. In other words, it is safest to wait for 2 minutes between upgrading each member. - -For a much larger total data size, 100MB or more , this one-time process might take even more time. Administrators of very large etcd clusters of this magnitude can feel free to contact the [etcd team][etcd-contact] before upgrading, and we’ll be happy to provide advice on the procedure. - -#### Downgrade - -If all members have been upgraded to v2.3, the cluster will be upgraded to v2.3, and downgrade from this completed state is **not possible**. If any single member is still v2.2, however, the cluster and its operations remains “v2.2”, and it is possible from this mixed cluster state to return to using a v2.2 etcd binary on all members. - -Please [backup the data directory](admin_guide.md#backing-up-the-datastore) of all etcd members to make downgrading the cluster possible even after it has been completely upgraded. - -### Upgrade Procedure - - -This example details the upgrade of a three-member v2.2 ectd cluster running on a local machine. - -#### 1. Check upgrade requirements. - -Is the the cluster healthy and running v.2.2.x? - -``` -$ etcdctl cluster-health -member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379 -member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379 -member a8266ecf031671f3 is healthy: got healthy result from http://localhost:12379 -cluster is healthy - -$ curl http://localhost:4001/version -{"etcdserver":"2.2.x","etcdcluster":"2.2.0"} -``` - -#### 2. Stop the existing etcd process - -When each etcd process is stopped, expected errors will be logged by other cluster members. This is normal since a cluster member connection has been (temporarily) broken: - -``` -2016-03-11 09:50:49.860319 E | rafthttp: failed to read 8211f1d0f64f3269 on stream Message (unexpected EOF) -2016-03-11 09:50:49.860335 I | rafthttp: the connection with 8211f1d0f64f3269 became inactive -2016-03-11 09:50:51.023804 W | etcdserver: failed to reach the peerURL(http://127.0.0.1:12380) of member 8211f1d0f64f3269 (Get http://127.0.0.1:12380/version: dial tcp 127.0.0.1:12380: getsockopt: connection refused) -2016-03-11 09:50:51.023821 W | etcdserver: cannot get the version of member 8211f1d0f64f3269 (Get http://127.0.0.1:12380/version: dial tcp 127.0.0.1:12380: getsockopt: connection refused) -``` - -It’s a good idea at this point to [backup the etcd data directory](https://github.com/coreos/etcd/blob/7f7e2cc79d9c5c342a6eb1e48c386b0223cf934e/Documentation/admin_guide.md#backing-up-the-datastore) to provide a downgrade path should any problems occur: - -``` -$ etcdctl backup \ - --data-dir /var/lib/etcd \ - --backup-dir /tmp/etcd_backup -``` - -#### 3. Drop-in etcd v2.3 binary and start the new etcd process - -The new v2.3 etcd will publish its information to the cluster: - -``` -09:58:25.938673 I | etcdserver: published {Name:infra1 ClientURLs:[http://localhost:12379]} to cluster 524400597fb1d5f6 -``` - -Verify that each member, and then the entire cluster, becomes healthy with the new v2.3 etcd binary: - -``` -$ etcdctl cluster-health -member 6e3bd23ae5f1eae0 is healthy: got healthy result from http://localhost:22379 -member 924e2e83e93f2560 is healthy: got healthy result from http://localhost:32379 -member a8266ecf031671f3 is healthy: got healthy result from http://localhost:12379 -cluster is healthy -``` - - -Upgraded members will log warnings like the following until the entire cluster is upgraded. This is expected and will cease after all etcd cluster members are upgraded to v2.3: - -``` -2016-03-11 09:58:26.851837 W | etcdserver: the local etcd version 2.2.0 is not up-to-date -2016-03-11 09:58:26.851854 W | etcdserver: member c02c70ede158499f has a higher version 2.3.0 -``` - -#### 4. Repeat step 2 to step 3 for all other members - -#### 5. Finish - -When all members are upgraded, the cluster will report upgrading to 2.3 successfully: - -``` -2016-03-11 10:03:01.583392 N | etcdserver: updated the cluster version from 2.2 to 2.3 -``` - -``` -$ curl http://127.0.0.1:4001/version -{"etcdserver":"2.3.x","etcdcluster":"2.3.0"} -``` - - -[etcd-contact]: https://coreos.com/etcd/? -