diff --git a/doc/source/install-guide/configure-haproxy.rst b/doc/source/install-guide/configure-haproxy.rst index 6d670fe3c2..c12bd52fe3 100644 --- a/doc/source/install-guide/configure-haproxy.rst +++ b/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 -and user-provided certificates. Auto-generated self-signed certificates are -currently the default. +The openstack-ansible project provides the ability to secure HAProxy +communications with self-signed or user-provided SSL certificates. -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 -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. +.. _Securing services with SSL certificates: configure-sslcertificates.html -------------- diff --git a/doc/source/install-guide/configure-horizon.rst b/doc/source/install-guide/configure-horizon.rst index 1a3b31fb92..c61510bdf1 100644 --- a/doc/source/install-guide/configure-horizon.rst +++ b/doc/source/install-guide/configure-horizon.rst @@ -1,43 +1,21 @@ `Home `__ 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 -and user-provided certificates. Auto-generated self-signed certificates are -currently the default. +The openstack-ansible project provides the ability to secure Horizon +communications with self-signed or user-provided SSL certificates. -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 -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. +.. _Securing services with SSL certificates: configure-sslcertificates.html -------------- diff --git a/doc/source/install-guide/configure-keystone.rst b/doc/source/install-guide/configure-keystone.rst new file mode 100644 index 0000000000..ae26d096b4 --- /dev/null +++ b/doc/source/install-guide/configure-keystone.rst @@ -0,0 +1,22 @@ +`Home `__ 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 diff --git a/doc/source/install-guide/configure-sslcertificates.rst b/doc/source/install-guide/configure-sslcertificates.rst new file mode 100644 index 0000000000..8ebd7deff5 --- /dev/null +++ b/doc/source/install-guide/configure-sslcertificates.rst @@ -0,0 +1,129 @@ +`Home `__ 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 +``_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 ``_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 diff --git a/doc/source/install-guide/configure.rst b/doc/source/install-guide/configure.rst index ccd79168df..0668642b05 100644 --- a/doc/source/install-guide/configure.rst +++ b/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** diff --git a/doc/source/install-guide/navigation.txt b/doc/source/install-guide/navigation.txt index 8fb429e1f3..a2f196d6c2 100644 --- a/doc/source/install-guide/navigation.txt +++ b/doc/source/install-guide/navigation.txt @@ -68,6 +68,9 @@ - `Configuring HAProxy (optional) `__ - `Configuring Horizon (optional) `__ + - `Configuring Keystone (optional) `__ + - `Securing services with SSL certificates + `__ - `6. Installation `__