Merge "Merge SSL documentation"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
d7450b1a10
@ -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
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
@ -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
|
||||
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
|
||||
|
||||
--------------
|
||||
|
||||
|
||||
22
doc/source/install-guide/configure-keystone.rst
Normal file
22
doc/source/install-guide/configure-keystone.rst
Normal file
@ -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
|
||||
129
doc/source/install-guide/configure-sslcertificates.rst
Normal file
129
doc/source/install-guide/configure-sslcertificates.rst
Normal file
@ -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
|
||||
@ -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**
|
||||
|
||||
@ -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>`__
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user