docs(*): add Deis resource requirements

carmstrong · carmstrong · commit 2af6c3e8449a · 2014-11-10T18:06:55.000-08:00
diff --git a/docs/installing_deis/baremetal.rst b/docs/installing_deis/baremetal.rst
@@ -15,6 +15,12 @@ machine running entirely from RAM. Then, you can `install CoreOS to disk`_.
     Deis requires CoreOS version 472.0.0 or more recent.
 
 
+Check System Requirements
+-------------------------
+
+Please refer to :ref:`system-requirements` for resource considerations when choosing a
+machine size to run Deis.
+
 Generate SSH Key
 ----------------
 
@@ -104,14 +110,6 @@ Install Deis Platform
 Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
 start installing the platform.
 
-
-Considerations when deploying Deis
-----------------------------------
-
-* Use machines with ample disk space and RAM (for comparison, we use m3.large instances on EC2)
-* Choose an appropriate `cluster size`_
-
-
 Known Problems
 --------------
 
diff --git a/docs/installing_deis/digitalocean.rst b/docs/installing_deis/digitalocean.rst
@@ -21,6 +21,12 @@ In order to provision the cluster, we will need to install a couple of administr
 `Deis Control Utility`_, which will assist us with installing, configuring and managing the Deis
 platform.
 
+Check System Requirements
+-------------------------
+
+Please refer to :ref:`system-requirements` for resource considerations when choosing a droplet
+size to run Deis.
+
 Generate SSH Key
 ----------------
 
@@ -40,7 +46,6 @@ by supplying a script that does all the heavy lifting for you. If you want to pr
 however, start by uploading the SSH key you wish to use to log into each of these servers. After
 that, create at least three Droplets with the following specifications:
 
- - At least 2GB -- more is recommended
  - All Droplets deployed in the same region
  - Region must have private networking enabled
  - Region must have User Data enabled. Supply the user-data file here
diff --git a/docs/installing_deis/gce.rst b/docs/installing_deis/gce.rst
@@ -81,7 +81,6 @@ Finally, create the ``gce-user-data`` file:
 
 We should have a ``gce-user-data`` file ready to launch CoreOS nodes with.
 
-
 Launch Instances
 ----------------
 
@@ -131,6 +130,11 @@ Launch 3 instances. You can choose another starting CoreOS image from the listin
     | core3 | 10.240.28.163 | 108.59.85.85 | us-central1-a | RUNNING |
     +-------+---------------+--------------+---------------+---------+
 
+.. note::
+
+    The provision script will by default provision ``n1-standard-2`` instances. Choosing a smaller
+    instance size is not recommended. Please refer to :ref:`system-requirements` for resource
+    considerations when choosing an instance size to run Deis.
 
 Load Balancing
 --------------
diff --git a/docs/installing_deis/index.rst b/docs/installing_deis/index.rst
@@ -21,7 +21,7 @@ with CoreOS.
 .. toctree::
 
     quick-start
-
+    system-requirements
     aws
     digitalocean
     gce
diff --git a/docs/installing_deis/quick-start.rst b/docs/installing_deis/quick-start.rst
@@ -37,6 +37,12 @@ running the following from the root of the repository:
 This will write a new discovery URL to the user-data file. Some essential scripts are supplied in
 this user-data file, so it is mandatory for provisioning Deis.
 
+Check System Requirements
+-------------------------
+
+The Deis provision scripts default to a machine size which should be adequate to run Deis, but this
+can be customized. Please refer to :ref:`system-requirements` for resource considerations when
+choosing a machine size to run Deis.
 
 Choose a Provider
 -----------------
diff --git a/docs/installing_deis/rackspace.rst b/docs/installing_deis/rackspace.rst
@@ -76,7 +76,6 @@ For more information, see `optimal etcd cluster size`_.
 
 Deis clusters of less than 3 nodes are unsupported.
 
-
 Run the Provision Script
 ------------------------
 
@@ -90,6 +89,11 @@ of the key pair you just added. Optionally, you can also specify a flavor name,
     Usage: provision-rackspace-cluster.sh <key pair name> [flavor] [environment]
     $ ./provision-rackspace-cluster.sh deis-key
 
+.. note::
+
+    The provision script will by default provision ``performance1-2`` servers. Choosing a smaller
+    server size is not recommended. Please refer to :ref:`system-requirements` for resource
+    considerations when choosing a server size to run Deis.
 
 Configure DNS
 -------------
diff --git a/docs/installing_deis/system-requirements.rst b/docs/installing_deis/system-requirements.rst
@@ -0,0 +1,28 @@
+:title: System Requirements
+:description: System requirements for provisioning Deis.
+
+.. _system-requirements:
+
+System Requirements
+===================
+
+When deploying Deis, it's important to provision machines with adequate resources. Deis is a
+highly-available distributed system, which means that Deis components and your deployed applications
+will move around the cluster onto healthy hosts as hosts leave the cluster for various reasons
+(failures, reboots, autoscalers, etc.). Because of this, you should have ample spare resources on
+any machine in your cluster to withstand the additional load of running services for failed machines.
+
+Machines must have:
+
+* At least 4GB of RAM (Deis uses 2 - 2.5GB, plus room for failover and deployed applications)
+* At least 40GB of hard disk space
+
+Running smaller machines will likely result in increased system load and has been known to result
+in component failures, issues with etcd/fleet, and other problems.
+
+If running multiple (at least 3) machines of an adequate size is unreasonable, it is recommended to
+investigate the `Dokku`_ project instead. Dokku is `sponsored`_ by Deis and is ideal for environments
+where a highly-available distributed system is not necessary (i.e. local development, testing, etc.).
+
+.. _`dokku`: https://github.com/progrium/dokku
+.. _`sponsored`: http://deis.io/deis-sponsors-dokku/
