9b04f1e550
Documents the steps needed to deploy an overcloud with the public API endpoints using SSL. Change-Id: I5b6b313d277b3fb57a12ec4f74d5c1ffc2946c84
154 lines
6.5 KiB
ReStructuredText
154 lines
6.5 KiB
ReStructuredText
Deploying with SSL
|
|
==================
|
|
|
|
TripleO supports deploying with SSL on the public OpenStack endpoints.
|
|
The following explains how to enable that.
|
|
|
|
Overcloud SSL
|
|
-------------
|
|
|
|
Public VIP Details
|
|
~~~~~~~~~~~~~~~~~~
|
|
To start, it is necessary to have a predictable public VIP. As of this
|
|
writing, that means using network isolation. With network isolation, the
|
|
first address in the external network allocation range will be assigned
|
|
as the public VIP. For details on deploying with network isolation, see
|
|
:doc:`../advanced_deployment/network_isolation`.
|
|
|
|
It is important that the public VIP be predictable because the SSL
|
|
certificate's Common Name must match the address of the configured
|
|
overcloud public endpoints. There are two ways to accomplish this:
|
|
|
|
#. The certificate's Common Name can be set to the IP of the public
|
|
VIP. In this case, the Common Name must match *exactly*. If the public
|
|
VIP is ``10.0.0.1``, the certificate's Common Name must also be ``10.0.0.1``.
|
|
Wild cards will not work.
|
|
|
|
#. The overcloud endpoints can be configured to point at
|
|
a DNS name. In this case, the certificate's Common Name must be valid
|
|
for the FQDN of the overcloud endpoints. Wild cards should work fine.
|
|
Note that this option also requires pre-configuration of the specified
|
|
DNS server with the appropriate FQDN and public VIP.
|
|
|
|
Certificate Details
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. admonition:: Self-Signed SSL
|
|
:class: selfsigned
|
|
|
|
For the self-signed case, just the predictable public VIP method will
|
|
be documented, as DNS configuration is outside the scope of this document.
|
|
|
|
Generate a private key::
|
|
|
|
openssl genrsa -out overcloud-privkey.pem 2048
|
|
|
|
Generate a self-signed CA certificate. This command will prompt for some
|
|
identifying information. Most of the fields don't matter, but this
|
|
is where the Common Name must be set to the first IP in the external
|
|
network allocation pool::
|
|
|
|
openssl req -new -x509 -key overcloud-privkey.pem -out overcloud-cacert.pem -days 365
|
|
|
|
Add the self-signed CA certificate to the undercloud's trusted certificate
|
|
store. Adding this file to the overcloud nodes will be discussed later::
|
|
|
|
sudo cp overcloud-cacert.pem /etc/pki/ca-trust/source/anchors/
|
|
sudo update-ca-trust extract
|
|
|
|
The contents of the private key and CA certificate files must be provided
|
|
to Heat as part of the deployment command. To do this, there is a sample
|
|
environment file in tripleo-heat-templates with fields for the file contents.
|
|
|
|
It is generally recommended that the original copy of tripleo-heat-templates
|
|
in ``/usr/share/openstack-tripleo-heat-templates`` not be altered, since it
|
|
could be overwritten by a package update at any time. Instead, make a copy
|
|
of the templates::
|
|
|
|
cp -r /usr/share/openstack-tripleo-heat-templates ~/ssl-heat-templates
|
|
|
|
Then edit the enable-tls.yaml environment file. If using the location from the
|
|
previous command, the correct file would be in
|
|
``~/ssl-heat-templates/environments/enable-tls.yaml``. Insert the contents of
|
|
the private key and CA certificate files in their respective locations.
|
|
|
|
.. note:: The certificate and key will be multi-line values, and all of the lines
|
|
must be indented to the same level.
|
|
|
|
An abbreviated version of how the file should look::
|
|
|
|
parameter_defaults:
|
|
SSLCertificate: |
|
|
-----BEGIN CERTIFICATE-----
|
|
MIIDgzCCAmugAwIBAgIJAKk46qw6ncJaMA0GCSqGSIb3DQEBCwUAMFgxCzAJBgNV
|
|
[snip]
|
|
sFW3S2roS4X0Af/kSSD8mlBBTFTCMBAj6rtLBKLaQbIxEpIzrgvp
|
|
-----END CERTIFICATE-----
|
|
[rest of file snipped]
|
|
|
|
``SSLKey`` should look similar, except with the value of the private key.
|
|
|
|
``SSLIntermediateCertificate`` can be set in the same way if the certificate
|
|
signer uses an intermediate certificate. Note that the ``|`` character must
|
|
be added as in the other values to indicate that this is a multi-line value.
|
|
|
|
When the certificate's common name is set to the public VIP, all instances
|
|
of ``CLOUDNAME`` in enable-tls.yaml must be replaced with ``IP_ADDRESS``.
|
|
This is not necessary when using a DNS name for the overcloud endpoints
|
|
|
|
.. note:: This command should be run exactly as shown below. Do not replace
|
|
``IP_ADDRESS`` with an actual address. Heat will insert the
|
|
appropriate value at deploy time.
|
|
|
|
::
|
|
|
|
sed -i 's/CLOUDNAME/IP_ADDRESS/' ~/ssl-heat-templates/environments/enable-tls.yaml
|
|
|
|
When using a self-signed certificate or a signer whose certificate is
|
|
not in the default trust store on the overcloud image it will be necessary
|
|
to inject the certificate as part of the deploy process. This can be done
|
|
with the environment file ``~/ssl-heat-templates/environments/inject-trust-anchor.yaml``.
|
|
Insert the contents of the signer's root CA certificate in the appropriate
|
|
location, in a similar fashion to what was done for the certificate and key
|
|
above.
|
|
|
|
.. admonition:: Self-Signed SSL
|
|
:class: selfsigned
|
|
|
|
Injecting the root CA certificate is required for self-signed SSL. The
|
|
correct value to use is the contents of the ``overcloud-cacert.pem`` file.
|
|
|
|
DNS Endpoint Configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When deploying with DNS endpoint addresses, two additional parameters must be
|
|
passed in a Heat environment file. These are ``CloudName`` and ``DnsServers``.
|
|
To do so, create a new file named something like ``cloudname.yaml``::
|
|
|
|
parameter_defaults:
|
|
CloudName: my-overcloud.my-domain.com
|
|
DnsServers: 10.0.0.1
|
|
|
|
Replace the values with ones appropriate for the target environment. Note that
|
|
the configured DNS server(s) must have an entry for the configured ``CloudName``
|
|
that matches the public VIP.
|
|
|
|
Deploying an SSL Environment
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The ``enable-tls.yaml`` file must be passed to the overcloud deploy command to
|
|
enable SSL on the public endpoints. Include the following additional parameter
|
|
in the overcloud deploy command::
|
|
|
|
-e ~/ssl-heat-templates/environments/enable-tls.yaml
|
|
|
|
The ``inject-trust-anchor.yaml`` file must also be passed if a root certificate
|
|
needs to be injected. The additional parameters in that case would instead
|
|
look like::
|
|
|
|
-e ~/ssl-heat-templates/environments/enable-tls.yaml -e ~/ssl-heat-templates/environments/inject-trust-anchor.yaml
|
|
|
|
When DNS endpoints are being used, the ``cloudname.yaml`` file must also be passed.
|
|
The additional parameters would be (``inject-trust-anchor.yaml`` may also be used
|
|
if it is needed for the configured certificate)::
|
|
|
|
-e ~/ssl-heat-templates/environments/enable-tls.yaml -e ~/cloudname.yaml [-e ~/ssl-heat-templates/environments/inject-trust-anchor.yaml] |