Merge pull request #3951 from mboersma/doc-proxy-proto-upgrade

docs(router+upgrading): clarify EC2 PROXY protocol use

Author: mboersma

docs/customizing_deis/router_settings.rst

@@ -99,8 +99,12 @@ Deis. Specifically, ensure that it sets and reads appropriate etcd keys.
 
 .. _`stock router image`: https://github.com/deis/deis/tree/master/router
 
+
+.. _proxy_protocol:
+
 PROXY Protocol
----------------
+--------------
+
 PROXY is a simple protocol supported by nginx, HAProxy, Amazon ELB, and others. It provides a method
 to obtain information about the original requests IP address sent to a load
 balancer in front of Deis :ref:`router`.

docs/managing_deis/ssl-endpoints.rst

@@ -22,9 +22,16 @@ Installing SSL on a Load Balancer
 ---------------------------------
 
 On most cloud-based load balancers, you can install a SSL certificate onto the load balancer
-itself. This is the recommended way of enabling SSL onto a cluster, as any communication inbound to
-the cluster will be encrypted while the internal components of Deis will still communicate over
-HTTP.
+itself. Any communication inbound to the cluster will be encrypted while the internal components
+of Deis will still communicate over HTTP.
+
+.. note::
+
+    On Amazon EC2, Deis enables the :ref:`PROXY protocol <proxy_protocol>` by default, requiring
+    installation of :ref:`SSL on the Deis routers <router_ssl>`, as described below.
+    Disable the PROXY protocol with ``deisctl config router rm proxyProtocol`` and change
+    existing targets and health checks from TCP to HTTP to terminate SSL connections at an
+    Amazon ELB instead.
 
 To enable SSL, you will need to open port 443 on the load balancer and forward it to port 80 on the
 routers. For EC2, you'll also need to add port 443 in the security group settings for your load

docs/managing_deis/upgrading-deis.rst

@@ -53,12 +53,24 @@ Finally, update ``deisctl`` to the new version and reinstall:
     In-place upgrades incur approximately 10-30 minutes of downtime for deployed applications, the router mesh
     and the platform control plane.  Please plan your maintenance windows accordingly.
 
+.. note::
+
+    When upgrading an Amazon EC2 cluster older than Deis v1.6, a :ref:`migration_upgrade` is
+    preferable.
+
+    On Amazon EC2, Deis enables the :ref:`PROXY protocol <proxy_protocol>` by default.
+    If an in-place upgrade is required, run ``deisctl config router set proxyProtocol=1``,
+    enable PROXY protocol for ports 80 and 443 on the ELB, add a ``TCP 443:443`` listener, and
+    change existing targets and health checks from HTTP to TCP.
+
 Upgrade Deis clients
 ^^^^^^^^^^^^^^^^^^^^
 As well as upgrading ``deisctl``, make sure to upgrade the :ref:`deis client <install-client>` to
 match the new version of Deis.
 
 
+.. _migration_upgrade:
+
 Migration Upgrade
 -----------------