{"action":"created","comment":{"url":"https://api.github.com/repos/coreos/etcd/pulls/comments/24441954","id":24441954,"diff_hunk":"@@ -0,0 +1,101 @@\n+## Allow-legacy mode\n+\n+etcd v2.0 uses internal API v2 protocol, which is not compatible with the v1 protocol.\n+\n+Allow-legacy mode is introduced to help user upgrade v0.4 etcd cluster easily, and ensures cluster has a short unavailable period, which is less than 1 minute in most cases (based on the size of the actual data).\n+\n+### Setup\n+\n+This mode is on if `ETCD_ALLOW_LEGACY_MODE` is set to true, or etcd is running in CoreOS system.\n+\n+It treats `ETCD_BINARY_DIR` as the directory for etcd binaries, which is organized in this way:\n+\n+```\n+ETCD_BINARY_DIR\n+  |\n+  -- 1\n+  |\n+  -- 2\n+```\n+\n+`1` is etcd with internal API v1 protocol. You should use etcd v0.4.7 here. `2` is etcd with internal API v2 protocol, which is etcd v2.0.\n+\n+The default value for `ETCD_BINARY_DIR` is `/usr/libexec/etcd/internal_versions/`.\n+\n+### Usage\n+\n+When bootstrapping with v1 data directory and v1 flags, etcd executes v0.4.7 binary and runs exactly the same as before.\n+\n+Before upgrade, you SHOULD check the health of the cluster by running:\n+\n+```\n+$ etcdctl cluster-health\n+```\n+\n+If the cluster and all members are healthy, you can start the upgrading process. Or you should check the unhealthy machines and fix them.\n+\n+\n+Call upgrade command to upgrade etcd cluster to v2.0 now:\n+\n+```\n+$ etcdctl upgrade --old-version=1 --new-version=2 --peer-url=$PEER_URL\n+```\n+\n+`PEER_URL` is any accessible peer url of the cluster.\n+\n+All peer-mode members will print out:\n+\n+```\n+detected next internal version 2, exit after 10 seconds.\n+```\n+\n+etcd does some internal coordination within the cluster in this period and then exits.\n+\n+You need to restart them after they exit. When restart, it upgrades the data directory, and executes etcd v2.0. If it runs in CoreOS system, the init system can take care of restart for you.\n+\n+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 memeber, you need to start [failure recovery](#failure-recovery).\n+\n+Standby-mode members will exit after etcd cluster is upgraded to v2.0:\n+\n+```\n+Detect the cluster has been upgraded to internal API v2. Exit now.\n+```\n+\n+When restart, standbys run in v2.0 proxy mode, which proxy user requests to etcd cluster.\n+\n+### Downgrade\n+\n+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.\n+\n+### Unavailable window\n+\n+etcd cluster is unavailable between the time that the upgrade command is sent and the time that the whole cluster is restarted.\n+\n+Usually, the window should be shorter than 1 minute.\n+\n+### In CoreOS system\n+\n+When you are in CoreOS system, allow-legacy mode is on automatically. Moreover, etcd process will restart automatically, so you don't need to do anything after calling upgrade command.\n+\n+### Internal Details\n+\n+etcd v0.4.7 registers versions of available etcd binary in its local machine into the key space at bootstrap stage. When the upgrade command is executed, etcdctl checks whether each member has internal-version-v2 etcd binary around. If that is true, each member is asked to record the fact that it needs to be upgraded the next time it reboots, and exits after 10 seconds.\n+\n+When reboot, etcd v2.0 sees the upgrade mark. It upgrades the data directory, and executes etcd v2.0.\n+\n+### Failure Recovery\n+\n+If `etcdctl cluster-health` says that the cluster is unhealthy, the upgrade process fails, which may happen if the network is broken, or the disk cannot work.\n+\n+The way to recover it is to manually upgrade the whole cluster to v2.0:\n+\n+- Log into machines that ran v0.4 peer-mode etcd\n+- Stop all etcd services\n+- Remove the `member` directory under etcd data-dir","path":"Documentation/allow_legacy_mode.md","position":94,"original_position":94,"commit_id":"e2ef3b50355df5e516c9a357d5cf6d5f5a2bea60","original_commit_id":"e2ef3b50355df5e516c9a357d5cf6d5f5a2bea60","user":{"login":"barakmich","id":98356,"avatar_url":"https://avatars.githubusercontent.com/u/98356?v=3","gravatar_id":"","url":"https://api.github.com/users/barakmich","html_url":"https://github.com/barakmich","followers_url":"https://api.github.com/users/barakmich/followers","following_url":"https://api.github.com/users/barakmich/following{/other_user}","gists_url":"https://api.github.com/users/barakmich/gists{/gist_id}","starred_url":"https://api.github.com/users/barakmich/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/barakmich/subscriptions","organizations_url":"https://api.github.com/users/barakmich/orgs","repos_url":"https://api.github.com/users/barakmich/repos","events_url":"https://api.github.com/users/barakmich/events{/privacy}","received_events_url":"https://api.github.com/users/barakmich/received_events","type":"User","site_admin":false},"body":"s/under/under the/","created_at":"2015-02-10T19:24:27Z","updated_at":"2015-02-10T19:24:27Z","html_url":"https://github.com/coreos/etcd/pull/2233#discussion_r24441954","pull_request_url":"https://api.github.com/repos/coreos/etcd/pulls/2233","_links":{"self":{"href":"https://api.github.com/repos/coreos/etcd/pulls/comments/24441954"},"html":{"href":"https://github.com/coreos/etcd/pull/2233#discussion_r24441954"},"pull_request":{"href":"https://api.github.com/repos/coreos/etcd/pulls/2233"}}},"pull_request":{"url":"https://api.github.com/repos/coreos/etcd/pulls/2233","id":28691503,"html_url":"https://github.com/coreos/etcd/pull/2233","diff_url":"https://github.com/coreos/etcd/pull/2233.diff","patch_url":"https://github.com/coreos/etcd/pull/2233.patch","issue_url":"https://api.github.com/repos/coreos/etcd/issues/2233","number":2233,"state":"open","locked":false,"title":"docs: add allow_legacy_mode.md","user":{"login":"yichengq","id":2976232,"avatar_url":"https://avatars.githubusercontent.com/u/2976232?v=3","gravatar_id":"","url":"https://api.github.com/users/yichengq","html_url":"https://github.com/yichengq","followers_url":"https://api.github.com/users/yichengq/followers","following_url":"https://api.github.com/users/yichengq/following{/other_user}","gists_url":"https://api.github.com/users/yichengq/gists{/gist_id}","starred_url":"https://api.github.com/users/yichengq/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yichengq/subscriptions","organizations_url":"https://api.github.com/users/yichengq/orgs","repos_url":"https://api.github.com/users/yichengq/repos","events_url":"https://api.github.com/users/yichengq/events{/privacy}","received_events_url":"https://api.github.com/users/yichengq/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-02-05T01:19:05Z","updated_at":"2015-02-10T19:24:27Z","closed_at":null,"merged_at":null,"merge_commit_sha":"6d02e10f2d08e55e14e39e7d976a019f6f1661a9","assignee":null,"milestone":{"url":"https://api.github.com/repos/coreos/etcd/milestones/16","labels_url":"https://api.github.com/repos/coreos/etcd/milestones/16/labels","id":949212,"number":16,"title":"autoupdate-on-coreos","description":"","creator":{"login":"xiang90","id":4479947,"avatar_url":"https://avatars.githubusercontent.com/u/4479947?v=3","gravatar_id":"","url":"https://api.github.com/users/xiang90","html_url":"https://github.com/xiang90","followers_url":"https://api.github.com/users/xiang90/followers","following_url":"https://api.github.com/users/xiang90/following{/other_user}","gists_url":"https://api.github.com/users/xiang90/gists{/gist_id}","starred_url":"https://api.github.com/users/xiang90/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/xiang90/subscriptions","organizations_url":"https://api.github.com/users/xiang90/orgs","repos_url":"https://api.github.com/users/xiang90/repos","events_url":"https://api.github.com/users/xiang90/events{/privacy}","received_events_url":"https://api.github.com/users/xiang90/received_events","type":"User","site_admin":false},"open_issues":3,"closed_issues":5,"state":"open","created_at":"2015-01-23T22:14:48Z","updated_at":"2015-02-10T19:24:19Z","due_on":"2015-02-10T08:00:00Z","closed_at":null},"commits_url":"https://api.github.com/repos/coreos/etcd/pulls/2233/commits","review_comments_url":"https://api.github.com/repos/coreos/etcd/pulls/2233/comments","review_comment_url":"https://api.github.com/repos/coreos/etcd/pulls/comments/{number}","comments_url":"https://api.github.com/repos/coreos/etcd/issues/2233/comments","statuses_url":"https://api.github.com/repos/coreos/etcd/statuses/e2ef3b50355df5e516c9a357d5cf6d5f5a2bea60","head":{"label":"yichengq:315","ref":"315","sha":"e2ef3b50355df5e516c9a357d5cf6d5f5a2bea60","user":{"login":"yichengq","id":2976232,"avatar_url":"https://avatars.githubusercontent.com/u/2976232?v=3","gravatar_id":"","url":"https://api.github.com/users/yichengq","html_url":"https://github.com/yichengq","followers_url":"https://api.github.com/users/yichengq/followers","following_url":"https://api.github.com/users/yichengq/following{/other_user}","gists_url":"https://api.github.com/users/yichengq/gists{/gist_id}","starred_url":"https://api.github.com/users/yichengq/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yichengq/subscriptions","organizations_url":"https://api.github.com/users/yichengq/orgs","repos_url":"https://api.github.com/users/yichengq/repos","events_url":"https://api.github.com/users/yichengq/events{/privacy}","received_events_url":"https://api.github.com/users/yichengq/received_events","type":"User","site_admin":false},"repo":{"id":16744058,"name":"etcd","full_name":"yichengq/etcd","owner":{"login":"yichengq","id":2976232,"avatar_url":"https://avatars.githubusercontent.com/u/2976232?v=3","gravatar_id":"","url":"https://api.github.com/users/yichengq","html_url":"https://github.com/yichengq","followers_url":"https://api.github.com/users/yichengq/followers","following_url":"https://api.github.com/users/yichengq/following{/other_user}","gists_url":"https://api.github.com/users/yichengq/gists{/gist_id}","starred_url":"https://api.github.com/users/yichengq/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yichengq/subscriptions","organizations_url":"https://api.github.com/users/yichengq/orgs","repos_url":"https://api.github.com/users/yichengq/repos","events_url":"https://api.github.com/users/yichengq/events{/privacy}","received_events_url":"https://api.github.com/users/yichengq/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/yichengq/etcd","description":"A highly-available key value store for shared configuration and service discovery","fork":true,"url":"https://api.github.com/repos/yichengq/etcd","forks_url":"https://api.github.com/repos/yichengq/etcd/forks","keys_url":"https://api.github.com/repos/yichengq/etcd/keys{/key_id}","collaborators_url":"https://api.github.com/repos/yichengq/etcd/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/yichengq/etcd/teams","hooks_url":"https://api.github.com/repos/yichengq/etcd/hooks","issue_events_url":"https://api.github.com/repos/yichengq/etcd/issues/events{/number}","events_url":"https://api.github.com/repos/yichengq/etcd/events","assignees_url":"https://api.github.com/repos/yichengq/etcd/assignees{/user}","branches_url":"https://api.github.com/repos/yichengq/etcd/branches{/branch}","tags_url":"https://api.github.com/repos/yichengq/etcd/tags","blobs_url":"https://api.github.com/repos/yichengq/etcd/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/yichengq/etcd/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/yichengq/etcd/git/refs{/sha}","trees_url":"https://api.github.com/repos/yichengq/etcd/git/trees{/sha}","statuses_url":"https://api.github.com/repos/yichengq/etcd/statuses/{sha}","languages_url":"https://api.github.com/repos/yichengq/etcd/languages","stargazers_url":"https://api.github.com/repos/yichengq/etcd/stargazers","contributors_url":"https://api.github.com/repos/yichengq/etcd/contributors","subscribers_url":"https://api.github.com/repos/yichengq/etcd/subscribers","subscription_url":"https://api.github.com/repos/yichengq/etcd/subscription","commits_url":"https://api.github.com/repos/yichengq/etcd/commits{/sha}","git_commits_url":"https://api.github.com/repos/yichengq/etcd/git/commits{/sha}","comments_url":"https://api.github.com/repos/yichengq/etcd/comments{/number}","issue_comment_url":"https://api.github.com/repos/yichengq/etcd/issues/comments/{number}","contents_url":"https://api.github.com/repos/yichengq/etcd/contents/{+path}","compare_url":"https://api.github.com/repos/yichengq/etcd/compare/{base}...{head}","merges_url":"https://api.github.com/repos/yichengq/etcd/merges","archive_url":"https://api.github.com/repos/yichengq/etcd/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/yichengq/etcd/downloads","issues_url":"https://api.github.com/repos/yichengq/etcd/issues{/number}","pulls_url":"https://api.github.com/repos/yichengq/etcd/pulls{/number}","milestones_url":"https://api.github.com/repos/yichengq/etcd/milestones{/number}","notifications_url":"https://api.github.com/repos/yichengq/etcd/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/yichengq/etcd/labels{/name}","releases_url":"https://api.github.com/repos/yichengq/etcd/releases{/id}","created_at":"2014-02-11T20:18:23Z","updated_at":"2014-11-05T21:47:43Z","pushed_at":"2015-02-10T18:51:06Z","git_url":"git://github.com/yichengq/etcd.git","ssh_url":"git@github.com:yichengq/etcd.git","clone_url":"https://github.com/yichengq/etcd.git","svn_url":"https://github.com/yichengq/etcd","homepage":"","size":16731,"stargazers_count":0,"watchers_count":0,"language":"Go","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"coreos:master","ref":"master","sha":"d74e74d320666044a554205ac6307349239d4b4f","user":{"login":"coreos","id":3730757,"avatar_url":"https://avatars.githubusercontent.com/u/3730757?v=3","gravatar_id":"","url":"https://api.github.com/users/coreos","html_url":"https://github.com/coreos","followers_url":"https://api.github.com/users/coreos/followers","following_url":"https://api.github.com/users/coreos/following{/other_user}","gists_url":"https://api.github.com/users/coreos/gists{/gist_id}","starred_url":"https://api.github.com/users/coreos/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/coreos/subscriptions","organizations_url":"https://api.github.com/users/coreos/orgs","repos_url":"https://api.github.com/users/coreos/repos","events_url":"https://api.github.com/users/coreos/events{/privacy}","received_events_url":"https://api.github.com/users/coreos/received_events","type":"Organization","site_admin":false},"repo":{"id":11225014,"name":"etcd","full_name":"coreos/etcd","owner":{"login":"coreos","id":3730757,"avatar_url":"https://avatars.githubusercontent.com/u/3730757?v=3","gravatar_id":"","url":"https://api.github.com/users/coreos","html_url":"https://github.com/coreos","followers_url":"https://api.github.com/users/coreos/followers","following_url":"https://api.github.com/users/coreos/following{/other_user}","gists_url":"https://api.github.com/users/coreos/gists{/gist_id}","starred_url":"https://api.github.com/users/coreos/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/coreos/subscriptions","organizations_url":"https://api.github.com/users/coreos/orgs","repos_url":"https://api.github.com/users/coreos/repos","events_url":"https://api.github.com/users/coreos/events{/privacy}","received_events_url":"https://api.github.com/users/coreos/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/coreos/etcd","description":"A highly-available key value store for shared configuration and service discovery","fork":false,"url":"https://api.github.com/repos/coreos/etcd","forks_url":"https://api.github.com/repos/coreos/etcd/forks","keys_url":"https://api.github.com/repos/coreos/etcd/keys{/key_id}","collaborators_url":"https://api.github.com/repos/coreos/etcd/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/coreos/etcd/teams","hooks_url":"https://api.github.com/repos/coreos/etcd/hooks","issue_events_url":"https://api.github.com/repos/coreos/etcd/issues/events{/number}","events_url":"https://api.github.com/repos/coreos/etcd/events","assignees_url":"https://api.github.com/repos/coreos/etcd/assignees{/user}","branches_url":"https://api.github.com/repos/coreos/etcd/branches{/branch}","tags_url":"https://api.github.com/repos/coreos/etcd/tags","blobs_url":"https://api.github.com/repos/coreos/etcd/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/coreos/etcd/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/coreos/etcd/git/refs{/sha}","trees_url":"https://api.github.com/repos/coreos/etcd/git/trees{/sha}","statuses_url":"https://api.github.com/repos/coreos/etcd/statuses/{sha}","languages_url":"https://api.github.com/repos/coreos/etcd/languages","stargazers_url":"https://api.github.com/repos/coreos/etcd/stargazers","contributors_url":"https://api.github.com/repos/coreos/etcd/contributors","subscribers_url":"https://api.github.com/repos/coreos/etcd/subscribers","subscription_url":"https://api.github.com/repos/coreos/etcd/subscription","commits_url":"https://api.github.com/repos/coreos/etcd/commits{/sha}","git_commits_url":"https://api.github.com/repos/coreos/etcd/git/commits{/sha}","comments_url":"https://api.github.com/repos/coreos/etcd/comments{/number}","issue_comment_url":"https://api.github.com/repos/coreos/etcd/issues/comments/{number}","contents_url":"https://api.github.com/repos/coreos/etcd/contents/{+path}","compare_url":"https://api.github.com/repos/coreos/etcd/compare/{base}...{head}","merges_url":"https://api.github.com/repos/coreos/etcd/merges","archive_url":"https://api.github.com/repos/coreos/etcd/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/coreos/etcd/downloads","issues_url":"https://api.github.com/repos/coreos/etcd/issues{/number}","pulls_url":"https://api.github.com/repos/coreos/etcd/pulls{/number}","milestones_url":"https://api.github.com/repos/coreos/etcd/milestones{/number}","notifications_url":"https://api.github.com/repos/coreos/etcd/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/coreos/etcd/labels{/name}","releases_url":"https://api.github.com/repos/coreos/etcd/releases{/id}","created_at":"2013-07-06T21:57:21Z","updated_at":"2015-02-10T18:50:46Z","pushed_at":"2015-02-10T18:01:17Z","git_url":"git://github.com/coreos/etcd.git","ssh_url":"git@github.com:coreos/etcd.git","clone_url":"https://github.com/coreos/etcd.git","svn_url":"https://github.com/coreos/etcd","homepage":"","size":27875,"stargazers_count":5564,"watchers_count":5564,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":644,"mirror_url":null,"open_issues_count":120,"forks":644,"open_issues":120,"watchers":5564,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/coreos/etcd/pulls/2233"},"html":{"href":"https://github.com/coreos/etcd/pull/2233"},"issue":{"href":"https://api.github.com/repos/coreos/etcd/issues/2233"},"comments":{"href":"https://api.github.com/repos/coreos/etcd/issues/2233/comments"},"review_comments":{"href":"https://api.github.com/repos/coreos/etcd/pulls/2233/comments"},"review_comment":{"href":"https://api.github.com/repos/coreos/etcd/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/coreos/etcd/pulls/2233/commits"},"statuses":{"href":"https://api.github.com/repos/coreos/etcd/statuses/e2ef3b50355df5e516c9a357d5cf6d5f5a2bea60"}}}}