From 24b953a55d07b7e043e2096de554ecc0ba309971 Mon Sep 17 00:00:00 2001 From: Rob Szumski Date: Tue, 10 Feb 2015 16:45:02 -0800 Subject: [PATCH] docs: add diagram and restructure for clarity --- Documentation/allow_legacy_mode.md | 54 ++++++++++++++++--------- Documentation/etcd-migration-steps.png | Bin 0 -> 8140 bytes 2 files changed, 36 insertions(+), 18 deletions(-) create mode 100644 Documentation/etcd-migration-steps.png diff --git a/Documentation/allow_legacy_mode.md b/Documentation/allow_legacy_mode.md index 50edbb2c5..70bd04307 100644 --- a/Documentation/allow_legacy_mode.md +++ b/Documentation/allow_legacy_mode.md @@ -26,37 +26,57 @@ The default value for `ETCD_BINARY_DIR` is `/usr/libexec/etcd/internal_versions/ ### Upgrading a Cluster -When starting etcd with a v1 data directory and v1 flags, etcd executes the v0.4.7 binary and runs exactly the same as before. +When starting etcd with a v1 data directory and v1 flags, etcd executes the v0.4.7 binary and runs exactly the same as before. To start the migration, follow the steps below: -Before upgrading, you SHOULD check the health of the cluster by running: +![Migration Steps](etcd-migration-steps.png) + +#### 1. Check the Cluster Health + +Before upgrading, you should check the health of the cluster to double check that everything working perfectly. Check the health by running: ``` $ etcdctl cluster-health +cluster is healthy +member 6e3bd23ae5f1eae0 is healthy +member 924e2e83e93f2560 is healthy +member a8266ecf031671f3 is healthy ``` If the cluster and all members are healthy, you can start the upgrading process. If not, check the unhealthy machines and repair them using [admin guide](./admin_guide.md). -**The critical moment**: Use the `etcdctl upgrade` command to upgrade the etcd cluster to 2.0 now: +#### 2. Trigger the Upgrade + +When you're ready, use the `etcdctl upgrade` command to start the upgrade the etcd cluster to 2.0: ``` +# Defaults work on a CoreOS machine running etcd +$ etcdctl upgrade +``` + +``` +# Advanced example specifying a peer url $ etcdctl upgrade --old-version=1 --new-version=2 --peer-url=$PEER_URL ``` -`PEER_URL` is any accessible peer url of the cluster. +`PEER_URL` can be any accessible peer url of the cluster. -All peer-mode members will print out: +Once triggered, all peer-mode members will print out: ``` detected next internal version 2, exit after 10 seconds. ``` -etcd does internal coordination for the upgrade within the cluster in this period and then exits. +#### Parallel Coordinated Upgrade -You need to restart them after they exit. When restarted, it upgrades the data directory, and executes etcd v2.0. If it runs on a CoreOS system, the init system can take care of restart for you. +As part of the upgrade, etcd does internal coordination within the cluster for a brief period and then exits. Clusters storing 50 MB should be unavailable for less than 1 minute. -After the upgrade process, you can run the health check again to verify the upgrade. If the cluster is unhealthy or there is an unhealthy member, please refer to start [failure recovery](#failure-recovery). +#### Restart etcd Processes -Standby-mode members will exit after etcd cluster is upgraded to v2.0 with the message: +After the etcd processes exit, they need to be restarted. You can do this manually or configure your unit system to do this automatically. On CoreOS, etcd is already configured to start automatically with systemd. + +When restarted, the data directory of each member is upgraded, and afterwards etcd v2.0 will be running and servicing requests. The upgrade is now complete! + +Standby-mode members are a special case — they will be upgraded into proxy mode (a new feature in etcd 2.0) upon restarting. When the upgrade is triggered, any standbys will exit with the message: ``` Detect the cluster has been upgraded to internal API v2. Exit now. @@ -64,19 +84,17 @@ Detect the cluster has been upgraded to internal API v2. Exit now. Once restarted, standbys run in v2.0 proxy mode, which proxy user requests to the etcd cluster. +#### 3. Check the Cluster Health + +After the upgrade process, you can run the health check again to verify the upgrade. If the cluster is unhealthy or there is an unhealthy member, please refer to start [failure recovery](#failure-recovery). + ### Downgrade -If the upgrading fails due to disk/network issues, you still can restart the upgrading process manually. However, once you upgrade etcd to internal API v2, you CANNOT downgrade it back to internal API v1. If you want to downgrade etcd in the future, please backup your v1 data dir beforehand. +If the upgrading fails due to disk/network issues, you still can restart the upgrading process manually. However, once you upgrade etcd to internal v2 protocol, you CANNOT downgrade it back to internal v1 protocol. If you want to downgrade etcd in the future, please backup your v1 data dir beforehand. -### Unavailable window +### Upgrade Process on CoreOS -etcd cluster will be unavailable between the time that the upgrade command is sent and the time that each etcd process is upgraded and restarted. - -Usually, the window should be shorter than 1 minute for clusters storing up to 50 MB. - -### In CoreOS system - -When running on a CoreOS system, allow-legacy mode is enabled by default. Moreover, etcd process will restart automatically, so you don't need to do anything after running the upgrade command. +When running on a CoreOS system, allow-legacy mode is enabled by default and an automatic update will set up everything needed to execute the upgrade. The `etcd.service` on CoreOS is already configured to restart automatically. All you need to do is run `etcdctl upgrade` when you're ready, as described ### Internal Details diff --git a/Documentation/etcd-migration-steps.png b/Documentation/etcd-migration-steps.png new file mode 100644 index 0000000000000000000000000000000000000000..aac82fd69dd364b141ebaafc44d804b6ae1791ae GIT binary patch literal 8140 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 ZL$B8vrSs*Vz|K0J$|DWMVwid8e*v5W>X-lk literal 0 HcmV?d00001