bug(docs): clarify object storage requirements (#444)

* ref(docs): move system requirements above install instructions

* ref(docs): add system requirements to prerequisites

* ref(docs): callout deployment options in install doc

* ref(docs): add storage callout to system requirements

Author: slack

mkdocs.yml

@@ -27,8 +27,8 @@ pages:
     - Architecture: understanding-workflow/architecture.md
     - Components: understanding-workflow/components.md
   - Installing Workflow:
-    - Installing Workflow: installing-workflow/index.md
     - System Requirements: installing-workflow/system-requirements.md
+    - Installing Workflow: installing-workflow/index.md
     - Configuring Object Storage: installing-workflow/configuring-object-storage.md
     - Configuring Postgres: installing-workflow/configuring-postgres.md
     - Configuring the Registry: installing-workflow/configuring-registry.md

src/installing-workflow/index.md

@@ -4,10 +4,10 @@ This document is aimed at those who have already provisioned a [Kubernetes v1.2
 and want to install Deis Workflow. If you are just getting started with Kubernetes and
 Deis Workflow, follow our [quickstart guide](../quickstart/index.md) for help.
 
-
 ## Prerequisites
 
-You need to [install Helm Classic and Deis Workflow CLI before continuing](../quickstart/install-cli-tools.md).
+1. Verify the [Kubernetes system requirements](system-requirements.md)
+1. Install [Helm Classic and Deis Workflow CLI](../quickstart/install-cli-tools.md) tools
 
 ## Check Your Setup
 
@@ -38,6 +38,20 @@ InfluxDB is running at https://52.9.206.49/api/v1/proxy/namespaces/kube-system/s
 If you see a list of targets like the one above, `helmc` can communicate with the Kubernetes master. Double check that
 the master returned by `helmc target` matches the expected cluster.
 
+## Choose Your Deployment Strategy
+
+Deis Workflow includes everything it needs to run out of the box. However, these defaults are aimed at simplicity rather than
+production readiness. Production and staging deployments of Workflow should, at a minimum, use off-cluster storage.
+Which is used by Workflow components to store and backup critical data. Should an operator need to completely re-install
+Workflow, the required components can recover from off-cluster storage. See our documentation for [configuring object
+storage](configuring-object-storage.md) for more details.
+
+Workflow may also be configured to use off-cluster persistence for [Postgres](configuring-postgres.md) and
+Redis. A deployment strategy that mirrors the "stateless" clusters from Deis v1 PaaS.
+
+Last but not least, Workflow may also use a dedicated off-cluster image registry, including Docker Hub, Quay.io, ECR or
+GCR for all container images. Read more about [configuring your registry](configuring-registry.md).
+
 ## Add the Deis Chart Repository
 
 The [Deis Chart Repository](https://github.com/deis/charts) contains everything you need to install Deis Workflow onto

src/installing-workflow/system-requirements.md

@@ -9,6 +9,17 @@ Kubernetes v1.1, and Kubernetes v1.3.0 through v1.3.3 have
 [a bug when mounting secrets](https://github.com/deis/workflow/issues/372) which prevents Deis
 Workflow from starting.
 
+## Storage Requirements
+
+A variety of Deis Workflow components rely on an object storage system to do their work, including storing application
+slugs, Docker images and database logs.
+
+Deis Workflow ships with Minio by default, which provides in-cluster, ephemeral object storage. This means that if the
+Minio server crashes, all data will be lost. Therefore, Minio should be used for development or testing only.
+
+Workflow supports Amazon Simple Storage Service (S3), Google Cloud Storage (GCS), OpenShift Swift, and Azure Blob
+Storage. See [configuring object storage][storage-configuration] for setup instructions.
+
 ## Resource Requirements
 
 When deploying Deis Workflow, it's important to provision machines with adequate resources. Deis is a highly-available
@@ -39,5 +50,6 @@ and instability.
 If you are using Docker with OverlayFS, you must disable SELinux by adding `--selinux-enabled=false` to
 `EXTRA_DOCKER_OPTS`. For more background information, see:
 
+* [storage-configuration](configuring-object-storage.md)
 * [https://github.com/docker/docker/issues/7952](https://github.com/docker/docker/issues/7952)
 * [https://github.com/deis/workflow/issues/63](https://github.com/deis/postgres/issues/63)