Merge "Merge SSL documentation"

doc/source/install-guide/configure-haproxy.rst

@@ -23,52 +23,16 @@ balancer prior to deploying OSA.
          123458-infra03:
            ip: 172.29.236.53
 
-SSL certificates for HAProxy
+Securing HAProxy communication with SSL certificates
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are two options for deploying SSL certificates with HAProxy: self-signed
+The openstack-ansible project provides the ability to secure HAProxy
-and user-provided certificates.  Auto-generated self-signed certificates are
+communications with self-signed or user-provided SSL certificates.
-currently the default.
 
-Self-signed SSL certificates
+Refer to `Securing services with SSL certificates`_ for available configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+options.
 
-For self-signed certificates, users can configure the subject of the
+.. _Securing services with SSL certificates: configure-sslcertificates.html
-certificate using the ``haproxy_ssl_self_signed_subject`` variable.
-
-By default, the playbook won't regenerate a self-signed SSL certificate if one
-already exists on the target.  To force the certificate to be regenerated
-the next time the playbook runs, set ``haproxy_ssl_self_signed_regen`` to
-``true``.  To do a one-time SSL certificate regeneration, you can run:
-
-   .. code-block:: bash
-
-    openstack-ansible -e 'haproxy_ssl_self_signed_regen=True' haproxy-install.yml
-
-Keep in mind that regenerating self-signed certificates will overwrite any
-existing certificates and keys, including ones that were previously
-user-provided (see the following section).
-
-The playbook will then use memcached to distribute the certificates and keys to
-each HAProxy host.
-
-User-provided SSL certificates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Users can provide their own trusted certificates in a two step process:
-
-#. Copy the SSL certificate, key, and CA certificate to the deployment host
-#. Specify the path to those files on the deployment host
-
-The path to the SSL certificate, key and CA certificate on the `deployment
-host` must be specified in ``/etc/openstack_deploy/user_variables.yml``:
-
-* ``haproxy_user_ssl_cert`` - path to the SSL certificate
-* ``haproxy_user_ssl_key`` - path to the key
-* ``haproxy_user_ssl_ca_cert`` - path to the CA certificate
-
-If those three variables are provided, the playbook will deploy the files to
-each HAProxy host.
 
 --------------
 

doc/source/install-guide/configure-horizon.rst

@@ -1,43 +1,21 @@
 `Home <index.html>`__ OpenStack Ansible Installation Guide
 
-Configuring Horizon (optional)
+Configuring HAProxy (optional)
 ------------------------------
 
 Customizing the Horizon deployment is done within
 ``/etc/openstack_deploy/user_variables.yml``.
 
-SSL certificates
+Securing HAProxy communication with SSL certificates
-----------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-There are two options for deploying SSL certificates with Horizon: self-signed
+The openstack-ansible project provides the ability to secure Horizon
-and user-provided certificates.  Auto-generated self-signed certificates are
+communications with self-signed or user-provided SSL certificates.
-currently the default.
 
-Self-signed SSL certificates
+Refer to `Securing services with SSL certificates`_ for available configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+options.
 
-For self-signed certificates, users can configure the subject of the
+.. _Securing services with SSL certificates: configure-sslcertificates.html
-certificate using the ``horizon_ssl_self_signed_subject`` variable.  By
-default, the playbook won't regenerate a self-signed SSL certificate if one
-already exists in the container.  To force the certificate to be regenerated
-the next time the playbook runs, set ``horizon_ssl_self_signed_regen`` to
-``true``.
-
-The playbook will then use memcached to distribute the certificates and keys to
-each horizon container.
-
-User-provided SSL certificates
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Users can provide their own trusted certificates by setting three variables:
-
-* ``horizon_user_ssl_cert`` - path to the SSL certificate in the container
-* ``horizon_user_ssl_key`` - path to the key in the container
-* ``horizon_user_ssl_ca_cert`` - path to the CA certificate in the container
-
-If those three variables are provided, self-signed certificate generation and
-usage will be disabled.  However, it's up to the user to deploy those
-certificates and keys within each container.
 
 --------------
 

doc/source/install-guide/configure-keystone.rst

@@ -0,0 +1,22 @@
+`Home <index.html>`__ OpenStack Ansible Installation Guide
+
+Configuring Keystone (optional)
+-------------------------------
+
+Customizing the Keystone deployment is done within
+``/etc/openstack_deploy/user_variables.yml``.
+
+Securing Keystone communication with SSL certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The openstack-ansible project provides the ability to secure Keystone
+communications with self-signed or user-provided SSL certificates.
+
+Refer to `Securing services with SSL certificates`_ for available configuration
+options.
+
+.. _Securing services with SSL certificates: configure-sslcertificates.html
+
+--------------
+
+.. include:: navigation.txt

doc/source/install-guide/configure-sslcertificates.rst

@@ -0,0 +1,129 @@
+`Home <index.html>`__ OpenStack Ansible Installation Guide
+
+Securing services with SSL certificates
+---------------------------------------
+
+Providing secure communication between various services in an OpenStack
+deployment is highly recommended in the `OpenStack Security Guide`_.
+
+.. _OpenStack Security Guide: http://docs.openstack.org/security-guide/secure-communication.html
+
+The openstack-ansible project currently offers the ability to configure SSL
+certificates for secure communication with the following services:
+
+* HAProxy
+* Horizon
+* Keystone
+* RabbitMQ
+
+For each service, deployers have the option to use self-signed certificates
+generated during the deployment process or they can provide SSL certificates,
+keys and CA certificates from their own trusted certificate authority.  Highly
+secured environments should use trusted, user-provided, certificates for as
+many services as possible.
+
+All SSL certificate configuration should be done within
+``/etc/openstack_deploy/user_variables.yml`` and not within the playbook
+roles themselves.
+
+Self-signed certificates
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Self-signed certificates make it easy to get started quickly and they ensure
+data is encrypted in transit, but they don't provide a high level of trust
+for highly secure environments.  The use of self-signed certificates is
+currently the default in openstack-ansible.
+
+Setting self-signed certificate subject data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The subject data of any self-signed certificate can be changed using
+configuration variables.  The configuration variable for each service is
+``<servicename>_ssl_self_signed_subject``.  To change the SSL certificate
+subject data for HAProxy, simply make this adjustment in ``/etc/openstack_deploy/user_variables.yml``:
+
+.. code-block:: yaml
+
+    haproxy_ssl_self_signed_subject: "/C=US/ST=Texas/L=San Antonio/O=IT/CN=haproxy.example.com"
+
+For more information about the available fields in the certificate subject,
+refer to OpenSSL's documentation on the `req subcommand`_.
+
+.. _req subcommand: https://www.openssl.org/docs/manmaster/apps/req.html
+
+Generating and regenerating self-signed certificates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Self-signed certificates for each service are generated during the first run
+of the playbook.  Subsequent runs of the playbook **will not** generate new SSL
+certificates unless the user sets ``<servicename>_ssl_self_signed_regen`` to
+``true``.
+
+To force a self-signed certificate to regenerate you can pass the variable to
+``openstack-ansible`` on the command line:
+
+.. code-block:: bash
+
+    openstack-ansible -e "horizon_ssl_self_signed_regen=true" os-horizon-install.yml
+
+To force a self-signed certificate to regenerate **with every playbook run**,
+simply set the appropriate regeneration option to ``true``.  For example, if
+you've already run the ``os-horizon`` playbook, but you want to regenerate the
+self-signed certificate, set the ``horizon_ssl_self_signed_regen`` variable to
+``true`` in ``/etc/openstack_deploy/user_variables.yml``:
+
+.. code-block:: yaml
+
+    horizon_ssl_self_signed_regen: true
+
+Note that regenerating self-signed certificates will replace the existing
+certificates whether they are self-signed or user-provided.
+
+
+User-provided certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Deployers can provide their own SSL certificates, keys, and CA certificates
+for added trust in highly secure environments.  Acquiring certificates from a
+trusted certificate authority is outside the scope of this document, but `The
+Linux Documentation Project`_ has a section called `Certificate Management`_
+that explains to create your own certificate authority and sign certificates.
+
+.. _The Linux Documentation Project: http://www.tldp.org/
+.. _Certificate Management: http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/c118.html
+
+Deploying user-provided SSL certificates is a three step process:
+
+#. Copy your SSL certificate, key, and CA certificate to the *deployment host*
+#. Specify the path to your SSL certificate, key and CA certificate in
+   ``/etc/openstack_deploy/user_variables.yml``
+#. Run the playbook for that service
+
+As an example, if you wanted to deploy user-provided certificates for RabbitMQ,
+start by copying those certificates to the deployment host.  Then, edit
+``/etc/openstack_deploy/user_variables.yml`` and set the following three
+variables:
+
+.. code-block:: yaml
+
+    rabbitmq_user_ssl_cert:    /tmp/example.com.crt
+    rabbitmq_user_ssl_key:     /tmp/example.com.key
+    rabbitmq_user_ssl_ca_cert: /tmp/ExampleCA.crt
+
+Simply run the playbook to apply the certificates:
+
+.. code-block:: bash
+
+    openstack-ansible rabbitmq-install.yml
+
+The playbook will deploy your user-provided SSL certificate, key, and CA
+certificate to each RabbitMQ container.
+
+The process is identical with other services as well.  Simply replace
+``rabbitmq`` in the configuration variables shown above with ``horizon``,
+``haproxy``, or ``keystone``, to deploy user-provided certificates to those
+services.
+
+--------------
+
+.. include:: navigation.txt

doc/source/install-guide/configure.rst

@@ -16,6 +16,8 @@ Chapter 5. Deployment configuration
    configure-haproxy.rst
    configure-horizon.rst
    configure-ceilometer.rst
+   configure-keystone.rst
+   configure-sslcertificates.rst
 
 
 **Figure 5.1. Installation work flow**

doc/source/install-guide/navigation.txt

@@ -68,6 +68,9 @@
 
    -  `Configuring HAProxy (optional) <configure-haproxy.html>`__
    -  `Configuring Horizon (optional) <configure-horizon.html>`__
+   -  `Configuring Keystone (optional) <configure-keystone.html>`__
+   -  `Securing services with SSL certificates
+      <configure-sslcertificates.html>`__
 
 -  `6. Installation <install.html>`__