docs: boot order to find peers

Documentation/cluster-discovery.md

@@ -4,6 +4,8 @@
 
 Starting an etcd cluster can be painful since each node needs to know of another node in the cluster to get started. If you are trying to bring up a cluster all at once, say using a cloud formation, you also need to coordinate who will be the initial cluster leader. The discovery protocol helps you by providing an automated way to discover other existing peers in a cluster.
 
+Peer discovery for etcd is processed by `-discovery`, `-peers` and lastly log data in `-data-dir`. For more information see the [discovery design][discovery-design].
+
 ## Using discovery.etcd.io
 
 ### Create a Token
@@ -43,3 +45,5 @@ The Discovery API submits the `-peer-addr` of each etcd instance to the configur
 ## Stale Peers
 
 The discovery API will automatically clean up the address of a stale peer that is no longer part of the cluster. The TTL for this process is a week, which should be long enough to handle any extremely long outage you may encounter. There is no harm in having stale peers in the list until they are cleaned up, since an etcd instance only needs to connect to one valid peer in the cluster to join.
+
+[discovery-design]: https://github.com/coreos/etcd/blob/master/Documentation/design/discovery.md

Documentation/design/discovery.md

@@ -0,0 +1,45 @@
+## Discovery Rule
+
+Peer discovery uses the following sources in this order: `-discovery`, `-peers`, log data in `-data-dir`.
+
+If none of these is set, it will start a new cluster by itself. If any of them is set, it will make
+best efforts to find cluster, and panic if none is reachable.
+
+If a discover URL is provided and the discovery process succeeds then it will find peers specified by the discover URL only.
+This is because we assume that it has been registered in discover URL and
+should not join other clusters.
+
+If a discover URL is provided but the discovery process fails then we will prevent the node from forming
+a new cluster. We assume the user doesn't want to start a brand new cluster without noticing discover URL.
+
+## Logical Workflow
+
+Start a etcd machine:
+
+```
+If discovery url is given:
+    Do discovery
+    If Success:
+        Join to the cluster discovered
+		return
+
+If peer list is given:
+    Try to join as follower via peer list
+    If Success: return
+
+If log data is given:
+    Try to join as follower via peers in previous cluster
+    If Success: return
+
+If log data is given:
+    Restart the previous cluster which is down
+    return
+
+If discovery url is given:
+    Panic
+
+If peer list is given:
+    Panic
+
+Start as the leader of a new cluster
+```