docs(*): strongly suggest Deis clusters of 3+ nodes

Due to fleet and the Raft consensus algorithm, Deis clusters must consist
of at least 3 nodes, and always be an odd number of members to ensure a quorum
can be reached. This commit updates our documentation to reflect this.

Author: carmstrong

README.md

@@ -35,8 +35,13 @@ If you're on Ubuntu, you need to install the nfs-kernel-server package as it's r
 
 ## Additional setup for a multi-node cluster
 If you'd like to spin up more than one VM to test an entire cluster, there are a few additional prerequisites:
-* Set `DEIS_NUM_INSTANCES` to the desired size of your cluster: ```$ export DEIS_NUM_INSTANCES=3```
 * Edit [contrib/coreos/user-data](contrib/coreos/user-data) and add a unique discovery URL generated from `https://discovery.etcd.io/new`
+* Set `DEIS_NUM_INSTANCES` to the desired size of your cluster: ```$ export DEIS_NUM_INSTANCES=3```
+
+Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
+For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
+
+Deis clusters of less than 3 nodes are unsupported for anything other than local development. A painless 3+ node development environment is a priority.
 
 ## Boot CoreOS
 

contrib/ec2/README.md

@@ -31,6 +31,11 @@ By default, the script will provision 3 servers. You can override this by settin
 $ export DEIS_NUM_INSTANCES=5
 ```
 
+Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
+For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
+
+Deis clusters of less than 3 nodes are unsupported.
+
 ## Customize user-data
 Edit [user-data](../coreos/user-data) and add a new discovery URL.
 You can get a new one by sending a request to http://discovery.etcd.io/new.

contrib/rackspace/README.md

@@ -48,6 +48,11 @@ By default, the script will provision 3 servers. You can override this by settin
 $ DEIS_NUM_INSTANCES=5 ./provision-rackspace-cluster.sh deis-key
 ```
 
+Note that for scheduling to work properly, clusters must consist of at least 3 nodes and always have an odd number of members.
+For more information, see [optimal etcd cluster size](https://github.com/coreos/etcd/blob/master/Documentation/optimal-cluster-size.md).
+
+Deis clusters of less than 3 nodes are unsupported.
+
 ### Initialize the cluster
 Once the cluster is up, get the hostname of any of the machines from Rackspace, set
 FLEETCTL_TUNNEL, and issue a `make run` from the project root: