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
parent
dcec202b78
commit
e99368f6c9
@ -88,6 +88,7 @@
|
|||||||
.rtos {background: #ade;}
|
.rtos {background: #ade;}
|
||||||
.validations {background: #fdd;}
|
.validations {background: #fdd;}
|
||||||
.optional {background: #ffe;}
|
.optional {background: #ffe;}
|
||||||
|
.tls {background: #ded;}
|
||||||
|
|
||||||
/* admonition selector */
|
/* admonition selector */
|
||||||
#admonition_selector {
|
#admonition_selector {
|
||||||
|
|||||||
@ -96,6 +96,28 @@ Installing the Undercloud
|
|||||||
|
|
||||||
sudo yum install -y ceph-ansible
|
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::
|
#. Prepare the configuration file::
|
||||||
|
|
||||||
cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf
|
cp /usr/share/python-tripleoclient/undercloud.conf.sample ~/undercloud.conf
|
||||||
|
|||||||
@ -42,5 +42,6 @@ Documentation on additional features for |project|.
|
|||||||
split_stack
|
split_stack
|
||||||
ssl
|
ssl
|
||||||
tls-introduction
|
tls-introduction
|
||||||
|
tls-everywhere
|
||||||
tuned
|
tuned
|
||||||
undercloud_minion
|
undercloud_minion
|
||||||
|
|||||||
357
deploy-guide/source/features/tls-everywhere.rst
Normal file
357
deploy-guide/source/features/tls-everywhere.rst
Normal 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
|
||||||
Loading…
x
Reference in New Issue
Block a user