diff --git a/_custom/custom.css b/_custom/custom.css index 7deebf93..b65c916d 100644 --- a/_custom/custom.css +++ b/_custom/custom.css @@ -88,6 +88,7 @@ .rtos {background: #ade;} .validations {background: #fdd;} .optional {background: #ffe;} +.tls {background: #ded;} /* admonition selector */ #admonition_selector { diff --git a/deploy-guide/source/deployment/install_undercloud.rst b/deploy-guide/source/deployment/install_undercloud.rst index 0aa147e9..a2bafb7f 100644 --- a/deploy-guide/source/deployment/install_undercloud.rst +++ b/deploy-guide/source/deployment/install_undercloud.rst @@ -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 diff --git a/deploy-guide/source/features/index.rst b/deploy-guide/source/features/index.rst index ac87fbb4..63fc4b08 100644 --- a/deploy-guide/source/features/index.rst +++ b/deploy-guide/source/features/index.rst @@ -42,5 +42,6 @@ Documentation on additional features for |project|. split_stack ssl tls-introduction + tls-everywhere tuned undercloud_minion diff --git a/deploy-guide/source/features/tls-everywhere.rst b/deploy-guide/source/features/tls-everywhere.rst new file mode 100644 index 00000000..e3e4abde --- /dev/null +++ b/deploy-guide/source/features/tls-everywhere.rst @@ -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 +`_ +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