Merge pull request #1184 from deis/ssl-docs

docs(installing) add section on installing SSL

Author: Matthew Fisher

docs/installing_deis/configure-load-balancers.rst

@@ -21,9 +21,7 @@ These ports need to be open on the load balancers:
 * 80 (for application traffic and for API calls to the controller)
 * 2222 (for traffic to the builder)
 
-Optionally, you can also open port 443 and configure SSL termination on the load balancers, but
-requests should still be forwarded to port 80 on the routers. Communication between Deis components
-is currently unencrypted.
+If you want to configure SSL termination on your load balancer, see :ref:`ssl-endpoints`.
 
 A health check should be configured on the load balancer to send an HTTP request to /health-check at
 port 80 on all nodes in the Deis cluster. The health check endpoint returns an HTTP 200. This enables

docs/installing_deis/create-cluster.rst

@@ -4,7 +4,7 @@
 .. _create_cluster:
 
 Create a Cluster
-======================
+================
 
 Applications on Deis are deployed to a :ref:`cluster`. Before you can deploy
 applications, you need to create a cluster.

docs/installing_deis/index.rst

@@ -17,4 +17,5 @@ Installing Deis
     create-cluster
     configure-load-balancers
     configure-dns
+    ssl-endpoints
     upgrading-deis

docs/installing_deis/provision-controller.rst

@@ -6,6 +6,7 @@
 
 Provision a Controller
 ======================
+
 The `controller` is the brains of a Deis platform. Provisioning a Deis
 controller is a matter of creating one or more :ref:`concepts_coreos`
 machines and installing a few necessary *systemd* units to manage
@@ -18,6 +19,7 @@ with CoreOS.
 
 Amazon EC2
 ----------
+
 The `contrib/ec2` section of the Deis project includes shell scripts,
 documentation, and a customized CloudFormation template to make it easy
 to provision a multi-node Deis cluster on `Amazon EC2`_.
@@ -26,6 +28,7 @@ Please see `contrib/ec2`_ for details on using Deis on Amazon EC2.
 
 Rackspace
 ---------
+
 The `contrib/rackspace` section of the Deis project includes shell
 scripts, documentation, and a cloud-config template to make it easy to
 provision a multi-node Deis cluster on Rackspace_ cloud.
@@ -35,13 +38,15 @@ Rackspace cloud.
 
 Bare Metal
 ----------
+
 The `contrib/bare-metal` section of the Deis project includes documentation in
 README.md to help with provisioning a multi-node cluster on your own hardware.
 
 Please see `contrib/bare-metal`_ for details on using Deis on bare metal.
 
 Vagrant
 -------
+
 The root of the Deis project includes documentation in README.md, a
 Makefile and a Vagrantfile to make it easy to provision a single- or
 multi-node Deis cluster on Vagrant_ virtual machines.

docs/installing_deis/ssl-endpoints.rst

@@ -0,0 +1,71 @@
+:title: SSL Endpoints
+:description: Configure SSL termination for your Deis cluster
+
+
+.. _ssl-endpoints:
+
+SSL Endpoints
+=============
+
+SSL (Secure Sockets Layer) is the standard security technology for establishing an encrypted link
+between a web server and a browser. This link ensures that all data passed between the web server
+and browsers remain private and integral.
+
+To enable SSL for your cluster and all apps running upon it, you can add an SSL key to your load
+balancer. You must either provide an SSL certificate that was registered with a CA or provide your
+own self-signed SSL certificate.
+
+
+Generating an SSL Certificate
+-----------------------------
+
+To generate your own self-signed SSL certificate for testing purposes, you can run the following:
+
+.. code-block:: console
+
+    $ openssl genrsa -out server.key 2048
+    $ openssl req -new -key server.key -out server.csr
+
+This will create a private key and a Certificate Signing Request. This CSR is typically sent to a
+CA such as Verisign, but in this example we will be using it to sign our own SSL certificate.
+
+Though most fields are self-explanatory, pay close attention to the following:
+
++--------------+-------------------------------------------------------------------------+
+| Field        | Description                                                             |
++==============+=========================================================================+
+| Country Name | The two letter code, in ISO 3166-1 format, of the country in which your |
+|              | organization is based.                                                  |
++--------------+-------------------------------------------------------------------------+
+| Common Name  | This is the fully qualified domain name that you wish to secure. In     |
+|              | most cases, this will be a wildcard subdomain.                          |
++--------------+-------------------------------------------------------------------------+
+
+To generate a temporary certificate which is good for 365 days, issue the following command:
+
+.. code-block:: console
+
+    $ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
+
+.. note::
+
+    Some SSL vendors like RapidSSL will secure both the root domain and the www subdomain if you
+    set the Common Name to www.example.com
+
+    See your vendor's documentation for more information.
+
+
+Installing the SSL Certificate
+------------------------------
+
+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. To enable SSL, you will need to open port 443 on the load balancer and forward it to port 80
+on the routers. See your vendor's specific instructions on installing SSL on your load balancer.
+
+For EC2, see their documentation on `installing an SSL cert for load balancing`_. For
+Rackspace, see their `Product FAQ`_.
+
+.. _`installing an SSL cert for load balancing`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/ssl-server-cert.html
+.. _`Product FAQ`: http://www.rackspace.com/knowledge_center/product-faq/cloud-load-balancers