Introduce new TLS-e guide

This commit lays down the steps you need to take to deploy TLS-e with
TripleO. This is needed because we recently replaced novajoin with
tripleo-ipa which changes how people deploy TLS-everywhere.

Subsequent patches will:

  - introduce a guide for public TLS
  - remove legacy ssl documentation

Change-Id: I81f6a3ed542aa59c99ab57a5f2454e85ae7fde57
This commit is contained in:
Lance Bragstad 2020-05-05 13:58:06 +00:00
parent dcec202b78
commit e99368f6c9
4 changed files with 381 additions and 0 deletions

View File

@ -88,6 +88,7 @@
.rtos {background: #ade;}
.validations {background: #fdd;}
.optional {background: #ffe;}
.tls {background: #ded;}
/* admonition selector */
#admonition_selector {

View File

@ -96,6 +96,28 @@ Installing the Undercloud
sudo yum install -y ceph-ansible
.. admonition:: TLS
:class: tls
If you intend to deploy *TLS-everywhere* in the overcloud and are
deploying Train with python3 or Ussuri+, install the following packages::
sudo yum install -y python3-ipalib python3-ipaclient krb5-devel
If you're deploying Train with python2, install the corresponding python2
version of the above packages::
sudo yum install -y python-ipalib python-ipaclient krb5-devel
if you intend to use Novajoin to implement *TLS-everywhere* install the
following package::
sudo yum install -y python-novajoin
You can find more information about deploying with TLS in the
:doc:`../features/tls-introduction` documentation.
#. Prepare the configuration file::
cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf

View File

@ -42,5 +42,6 @@ Documentation on additional features for |project|.
split_stack
ssl
tls-introduction
tls-everywhere
tuned
undercloud_minion

View File

@ -0,0 +1,357 @@
Deploying TLS-everywhere
========================
Setting up *TLS-everywhere* primarily consists of a few additional steps you
need to take on the undercloud and FreeIPA server. These steps consist of
installing additional packages and enrolling the undercloud host as a FreeIPA
client.
The OpenStack release you are deploying affects which tools you can use to
deploy *TLS-everywhere*. For deployments using Queens through Stein you must
use Novajoin. For deployments using Train or Ussuri, you can use either
Novajoin or tripleo-ipa. For deployments using Victoria or newer releases you
must use tripleo-ipa. Deployments :ref:`deployed_server` must also use
tripleo-ipa. We recommend using tripleo-ipa whenever possible. Let's walk
through each step using both tripleo-ipa and Novajoin.
You can find a primer on the various TLS deployment strategies and components
in the :doc:`tls-introduction` documentation.
TLS-everywhere with tripleo-ipa
-------------------------------
.. note::
This deployment strategy is only supported on Train and newer releases. If
you're deploying a version older than Train, you'll need to use Novajoin to
accomplish *TLS-everywhere*, which is documented below.
Do the following steps before deploying your undercloud.
Configure DNS
~~~~~~~~~~~~~
*TLS-everywhere* deployments use FreeIPA as the DNS server. You need to set the
proper search domain and nameserver on the undercloud. To do this, you need to
know the deployment domain, the domain of the FreeIPA server, and the FreeIPA
server's IP address. For example, if the deployment domain is `example.com` and
the FreeIPA server domain is `bigcorp.com`, you should set the following in
`/etc/resolv.conf`::
search example.com bigcorp.com
nameserver $FREEIPA_IP_ADDRESS
This step ensures the undercloud can resolve newly added hosts and services
after TripleO enrolls them as FreeIPA clients. You only need to add both search
domains if they're different. If the FreeIPA server is using the same domain as
the deployment you only need to specify the deployment domain.
Configure FreeIPA
~~~~~~~~~~~~~~~~~
.. note::
This section assumes you have permissions to make writeable changes to your
FreeIPA server. If you don't have those permissions or direct access to the
FreeIPA server, you'll need to contact your FreeIPA administrator and have
them perform the following steps either using ansible scripts or manually.
Before you configure the undercloud, you need to ensure FreeIPA is configured
with the correct principal and privileges. This allows the undercloud to add
new hosts, services, and DNS records in FreeIPA during the overcloud
installation.
The undercloud will enroll itself as a FreeIPA client and download a keytab to
use for authentication during the installation process. To do this, it needs a
one-time password (OTP) from FreeIPA that you configure in ``undercloud.conf``.
You can generate the OTP manually if you have the correct permissions to add
hosts, modify permissions, update roles, and create principals in FreeIPA. You
need to perform these actions from an existing FreeIPA client. Note, the
FreeIPA server itself is enrolled as a client.
You can find a set of `playbooks
<https://opendev.org/x/tripleo-ipa/src/branch/master/tripleo_ipa/playbooks#user-content-tls-e-ipa-server-configuration-roles>`_
in tripleo-ipa that automate creating permissions, hosts, and principals for
the undercloud. These playbooks expect the ``IPA_PRINCIPAL``, which is a user
in FreeIPA, to have the necessary permissions to perform the tasks in each
playbook (e.g., ``ipa privilege-add-permission``, ``ipa host-add``, etc). They
also expect you to generate a kerberos token before executing each playbook.
Create a FreeIPA role
^^^^^^^^^^^^^^^^^^^^^
First, you need to create a new FreeIPA role with the appropriate permissions
for managing hosts, principals, services, and DNS entries::
$ kinit
$ export IPA_PASSWORD=$IPA_PASSWORD
$ export IPA_PRINCIPAL=$IPA_USER
$ export UNDERCLOUD_FQDN=undercloud.example.com
$ ansible-playbook /usr/share/ansible/tripleo-playbooks/ipa-server-create-role.yaml
Register the undercloud
^^^^^^^^^^^^^^^^^^^^^^^
Next, you need to register the undercloud as a FreeIPA client and generate a
OTP that the undercloud will use for enrollment, which is necessary before it
can manage entities in FreeIPA::
$ export IPA_PASSWORD=$IPA_PASSWORD
$ export IPA_PRINCIPAL=$IPA_USER
$ export UNDERCLOUD_FQDN=undercloud.example.com
$ ansible-playbook /usr/share/ansible/tripleo-playbooks/ipa-server-register-undercloud.yaml
If successful, the ansible output will contain an OTP. Save this OTP because
you will need it when you configure the undercloud.
Create a principal
^^^^^^^^^^^^^^^^^^
Finally, create a FreeIPA principal and grant it the necessary permissions to
manage hosts, services, and DNS entries in FreeIPA::
$ export IPA_PASSWORD=$IPA_PASSWORD
$ export IPA_PRINCIPAL=$IPA_USER
$ export UNDERCLOUD_FQDN=undercloud.example.com
$ ansible-playbook /usr/share/ansible/tripleo-playbooks/ipa-server-create-principal.yaml
Configure the Undercloud
~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
This section only provides guidance for configuring *TLS-everywhere*. You
need to make sure your undercloud configuration is complete before starting
the undercloud installation process.
Set the following variables in `undercloud.conf`::
ipa_otp = $OTP
overcloud_domain_name = example.com
undercloud_nameservers = $FREEIPA_IP_ADDRESS
Your undercloud configuration is ready to be deployed and has the necessary
changes to allow you to deploy *TLS-everywhere* for the overcloud.
Undercloud Install
~~~~~~~~~~~~~~~~~~
After you've had an opportunity to verify all undercloud configuration options,
including the options listed above, start the undercloud installation process::
$ openstack undercloud install
Undercloud Verification
~~~~~~~~~~~~~~~~~~~~~~~
You should verify that the undercloud was enrolled properly by listing the
hosts in FreeIPA::
$ sudo kinit
$ sudo ipa host-find
You should also confirm that ``/etc/novajoin/krb5.keytab`` exists on the
undercloud. The ``novajoin`` directory name is purely for legacy naming
reasons. The keytab is placed in this directory regardless of using novajoin
to enroll the undercloud as a FreeIPA client.
You can proceed with the :ref:`Overcloud TLS-everywhere` if the undercloud
installation was successful.
TLS-everywhere with Novajoin
----------------------------
.. warning:: This deployment strategy is only supported up to the Train release. We
recommend using tripleo-ipa to accomplish *TLS-everywhere* in newer
releases. Steps for using tripleo-ipa are documented above.
Do the following steps before deploying your undercloud.
Configure DNS
~~~~~~~~~~~~~
*TLS-everywhere* deployments use FreeIPA as the DNS server. You need to set the
proper search domain and nameserver on the undercloud. To do this, you need to
know the deployment domain, the domain of the FreeIPA server, and the FreeIPA
server's IP address. For example, if the deployment domain is `example.com` and
the FreeIPA server domain is `bigcorp.com`, you should set the following in
`/etc/resolv.conf`::
search example.com bigcorp.com
nameserver $FREEIPA_IP_ADDRESS
This step ensures the undercloud can resolve newly added hosts and services
after TripleO enrolls them as FreeIPA clients. You only need to add both search
domains if they're different. If the FreeIPA server is using the same domain as
the deployment you only need to specify the deployment domain.
Add Undercloud as a FreeIPA host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Next, you need to add the undercloud as a host in FreeIPA. This will generate a
one-time password that TripleO uses to enroll the undercloud as a FreeIPA
client, giving the undercloud the permissions it needs to add new hosts,
services, and DNS records. You can use the following command-line utility to
add the undercloud as a FreeIPA host::
novajoin-ipa-setup \
--principal $IPA_USER \
--password $IPA_PASSWORD \
--server ipa.bigcorp.com \
--realm BIGCORP.COM \
--domain example.com \
--hostname undercloud.example.com \
--precreate
If successful, the command will return a one-time password. Save this password
because you will need it later to configure the undercloud.
Configure the Undercloud
~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
This section only provides guidance for configuring *TLS-everywhere*. You
need to make sure your undercloud configuration is complete before starting
the undercloud installation process.
Set the following variables in `undercloud.conf`::
enable_novajoin = True
ipa_otp = $IPA_OTP
overcloud_domain_name = example.com
Your undercloud configuration is ready to be deployed and has the necessary
changes to allow you to deploy *TLS-everywhere* for the overcloud.
Undercloud Install
~~~~~~~~~~~~~~~~~~
After you've had an opportunity to verify all undercloud configuration options,
including the options listed above, start the undercloud installation process::
$ openstack undercloud install
Undercloud Verification
~~~~~~~~~~~~~~~~~~~~~~~
You should verify that the undercloud was enrolled properly by listing the
hosts in FreeIPA::
$ sudo kinit
$ sudo ipa host-find
You should also confirm that ``/etc/novajoin/krb5.keytab`` exists on the
undercloud and that the ``novajoin`` and ``novajoin-notifier`` services are
running.
You can proceed with the :ref:`Overcloud TLS-everywhere` if the undercloud
installation was successful.
.. _Overcloud TLS-everywhere:
Configuring the Overcloud
-------------------------
*TLS-everywhere* requires you to set extra parameters and templates before you
deploy, or update, your overcloud. These changes consist of settings domain
information and including additional heat templates in your deploy command.
Let's walk through each step individually.
Set Parameters
~~~~~~~~~~~~~~
Next, you need to set parameters so that TripleO knows where to find your
FreeIPA server and configures DNS. You need to set these variables so that
TripleO adds DNS records that map to the correct hosts. Let's continue assuming
we have a file called ``tls-parameters.yaml`` and it contains the following
parameter_defaults section::
parameter_defaults:
DnsSearchDomains: ["example.com"]
DnsServers: ["192.168.1.13"]
CloudDomain: example.com
CloudName: overcloud.example.com
CloudNameInternal: overcloud.internalapi.example.com
CloudNameStorage: overcloud.storage.example.com
CloudNameStorageManagement: overcloud.storagemgmt.example.com
CloudNameCtlplane: overcloud.ctlplane.example.com
.. note::
If you are using deployed servers, you must also specify the following
parameters::
IdMInstallClientPackages: True
This option is required to install packages needed to enroll overcloud
hosts as FreeIPA clients. Deployments using Novajoin do not require this
option since the necessary packages are built into the overcloud images. If
you do not specify this argument, you need to ensure dependencies for
ansible-freeipa are present on the overcloud servers before deploying the
overcloud.
The ``DnsServers`` value above assumes we have FreeIPA available at
192.168.1.13.
It's important to note that you will need to update the `DnsSearchDomains` to
include the domain of the IPA server if it's different than the `CloudDomain`.
For example, if your `CloudDomain` is `example.com` and your IPA server is
located at `ipa.bigcorp.com`, then you need to include `bigcorp.com` as an
additional search domain::
DnsSearchDomains: ["example.com", "bigcorp.com"]
Composable Services
~~~~~~~~~~~~~~~~~~~
In addition to the parameters above, you might need to update the
``resource_registry`` in ``tls-parameters.yaml`` to include a composable
service. There are two composable services, one for Novajoin and the other is
for tripleo-ipa. TripleO uses the Novajoin composable service for deploying
*TLS-everywhere* by default. If you need or want to use tripleo-ipa, you'll
need to update the registry to use a different composable service. Both options
are described below.
Novajoin Composable Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the default option but we will update TripleO in the future to use
tripleo-ipa by default. At that point, you may need to add the following
composable service to the ``resource_registry`` in ``tls-parameters.yaml``::
resource_registry:
OS::TripleO::Services::IpaClient: /usr/share/openstack-tripleo-heat-templates/deployment/ipa/ipaclient-baremetal-ansible.yaml
tripleo-ipa Composable Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you're deploying *TLS-everwhere* with tripleo-ipa, you need to override the
default Novajoin composable service. Add the following composable service to
the ``resource_registry`` in ``tls-parameters.yaml``::
resource_registry:
OS::TripleO::Services::IpaClient: /usr/share/openstack-tripleo-heat-templates/deployment/ipa/ipaservices-baremetal-ansible.yaml
Remember, this is going to be the default method of deploying *TLS-everywhere*
as of the Victoria release.
Specify Templates
~~~~~~~~~~~~~~~~~
At this point, you should have all the settings configured for a successful
*TLS-everywhere* deployment. The only remaining step is to include the
following templates in your overcloud deploy command::
$ openstack overcloud deploy \
-e /usr/share/openstack-tripleo-heat-templates/environments/ssl/tls-everywhere-endpoints-dns.yaml \
-e /usr/share/openstack-tripleo-heat-templates/environments/services/haproxy-public-tls-certmonger.yaml \
-e /usr/share/openstack-tripleo-heat-templates/environments/ssl/enable-internal-tls.yaml \
-e tls-parameters.yaml
Remember, ``tls-parameters.yaml`` is the file containing the parameters above.
Overcloud Verification
----------------------
After the overcloud is deployed, you can confirm each endpoint is using HTTPS
by querying keystone's endpoints::
$ openstack --os-cloud overcloud endpoint list