Document installing the undercloud with SSL endpoints

Adds a new admonition that covers how to install the undercloud
with ssl endpoints.  I would anticipate the admonition being
reused for the overcloud when that is documented.

Also covers how to generate a self-signed certificate appropriate
for use with HAProxy.

Change-Id: Iec58f79b83db6cbb684ff309b818d1a8f437dfa1

doc/source/_custom/custom.css

@@ -67,6 +67,7 @@
 .virtual {background: #efe;}
 .ceph {background: #eff;}
 .source {background: #bbb;}
+.ssl {background: #ffe;}
 
 /* admonition selector */
 #admonition_selector {

doc/source/_templates/layout.html

@@ -30,6 +30,7 @@
       <ul>
         <li><input type="checkbox" id="baremetal" checked="checked"><label for="baremetal" title="Step that should only be run when deploying to baremetal.">Baremetal</label></li>
         <li><input type="checkbox" id="virtual" checked="checked"><label for="virtual" title="Step that should only be run when deploying to virtual machines.">Virtual</label></li>
+        <li><input type="checkbox" id="ssl" checked="checked"><label for="ssl" title="Step that should only be run when deploying with SSL OpenStack endpoints.">SSL</label></li>
       </ul>
 
       <span class="title">Additional Overcloud Roles</span>

doc/source/index.rst

@@ -72,5 +72,10 @@ steps are marked as follows:
    Step that should only be run when choosing to use components from their
    stable branches rather than using packages/source based on current master.
 
+.. admonition:: SSL
+   :class: ssl
+
+   Step that should only be run when deploying with SSL OpenStack endpoints
+
 Any such steps should *not* be run if the target environment does not match
 the section marking.

doc/source/installation/installing.rst

@@ -107,6 +107,46 @@ Installing the Undercloud
      The correct value for the ``reporef`` can be found in the ``Download`` section
      of the Gerrit UI.  Look for a string that matches the format of the example above.
 
+  .. admonition:: SSL
+     :class: ssl
+
+     To enable SSL on the undercloud, you must set the ``undercloud_service_certificate``
+     option in ``undercloud.conf`` to an appropriate certificate file.  Important:
+     The certificate file's Common Name *must* be set to the value of
+     ``undercloud_public_vip`` in undercloud.conf.
+
+     If you do not have a trusted CA signed certificate file, you can alternatively
+     generate a self-signed certificate file using the following commands::
+
+         openssl genrsa -out privkey.pem 2048
+
+     The next command will prompt for some identification details.  Most of these don't
+     matter, but make sure the ``Common Name`` entered matches the value of
+     ``undercloud_public_vip`` in undercloud.conf::
+
+         openssl req -new -x509 -key privkey.pem -out cacert.pem -days 365
+
+     Combine the two files into one for HAProxy to use.  The order of the
+     files in this command matters, so do not change it::
+
+         cat cacert.pem privkey.pem > undercloud.pem
+
+     Move the file to a more appropriate location and set the SELinux context::
+
+         sudo mkdir /etc/pki/instack-certs
+         sudo cp undercloud.pem /etc/pki/instack-certs
+         sudo semanage fcontext -a -t etc_t "/etc/pki/instack-certs(/.*)?"
+         sudo restorecon -R /etc/pki/instack-certs
+
+     ``undercloud_service_certificate`` should then be set to
+     ``/etc/pki/instack-certs/undercloud.pem``.
+
+     Add the self-signed CA certificate to the undercloud system's trusted
+     certificate store::
+
+        sudo cp cacert.pem /etc/pki/ca-trust/source/anchors/
+        sudo update-ca-trust extract
+
   Install the undercloud::
 
       openstack undercloud install