openstack/tripleo-docs
Code Issues Proposed changes
09e3ef837b
tripleo-docs/deploy-guide/source/features/tls-introduction.rst

160 lines
7.0 KiB
ReStructuredText
Raw Normal View History

Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
.. _tls-introduction:
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
TLS Introduction
================
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
Depending on your deployment's security requirements, you might be required to
encrypt network traffic. TripleO helps you accomplish this by supporting
various TLS deployment options. Let's start by understanding the different ways
we can deploy TLS.
The first option is to only encrypt traffic between clients and public
endpoints. This approach results in fewer certificates to manage, and we refer
to it as *public TLS*. Public endpoints, in this sense, are endpoints only
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
exposed to end-users. Traffic between internal endpoints is not encrypted.
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
The second option leverages TLS for all endpoints in the entire deployment,
including the overcloud, undercloud, and any systems that natively support TLS.
We typically refer to this approach as *TLS-everywhere* because we use TLS
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
everywhere we can, encrypting as much network traffic as possible. Certificate
management automation is critical with this approach because the number of
certificates scales linearly with the number of services in your deployment.
TripleO uses several components to help ease the burden of managing
certificates. This option is desirable for deployments susceptible to industry
regulation or those who have a higher security risk. Healthcare,
telecommunications, and the public sector are but a few industries that make
extensive use of *TLS-everywhere*. You can think of *public TLS* as a subset of
what *TLS-everywhere* offers.
TripleO uses the following components to implement *public TLS* and
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
*TLS-everywhere*.
Certmonger
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
----------
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
`Certmonger`_ is a daemon that helps simplify certificate management between
endpoints and certificate authorities (CAs). You can use it to generate key
pairs and certificate signing requests (CSRs). It can self-sign CSRs or send
them to external CAs for signing. Certmonger also tracks the expiration of each
certificate it manages. When a certificate is about to expire, Certmonger
requests a new certificate, updates it accordingly, and may restart a service.
This automation keeps the node enrolled as a client of the certificate
authority so that you don’t have to update hundreds, or thousands, of
certificates manually. Certmonger runs on each node that provides an endpoint
in your deployment.
.. _Certmonger: https://pagure.io/certmonger
FreeIPA
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
-------
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
`FreeIPA`_ is a multi-purpose system that includes a certificate authority
(DogTag Certificate System), LDAP (389 Directory Server), MIT Kerberos, NTP
server, and DNS. TripleO uses all of these subsystems to implement TLS across
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
OpenStack. For example, if you use FreeIPA in your deployment, you can sign
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
CSRs with DogTag, as opposed to self-signing CSRs with certmonger locally.
FreeIPA runs on a supplemental node in your deployment, and it is kept separate
from other infrastructure.
.. _FreeIPA: https://www.freeipa.org/page/Main_Page
Installing FreeIPA
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
~~~~~~~~~~~~~~~~~~
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
Similar to setting up the undercloud node, you need to set the hostname
properly for the FreeIPA server. For this example, let's assume we're using
``example.com`` as the domain name for the deployment.::
sudo hostnamectl set-hostname ipa.example.come
sudo hostnamectl set-hostname --transient ipa.example.com
Collect and install the FreeIPA packages::
sudo yum install -y ipa-server ipa-server-dns
Configure FreeIPA::
sudo ipa-server-install --realm EXAMPLE.COM /
--ds-password $DIRECTORY_MANAGER_PASSWORD /
--admin-password $ADMIN_PASSWORD /
--hostname ipa.example.com /
--setup-dns /
--auto-forwarders /
--auto-reverse /
--unattended
Add missing FreeIPA install steps We need a couple of additional steps for the IPA setup. Change-Id: I8038a6ca4ad6ea02184195a4052a22d84a658fa2
2020-05-15 15:25:38 -04:00
By default, FreeIPA does not public it's Certificate Revocation List (CRL)
on startup. As the CRL is retrieved when the overcloud nodes retrieve
certificates from FreeIPA, we should configure it to do so and restart
FreeIPA.::
sed -i -e \
's/ca.crl.MasterCRL.publishOnStart=.*/ca.crl.MasterCRL.publishOnStart=true/' \
/etc/pki/pki-tomcat/ca/CS.cfg
systemctl restart ipa
Add notes on removing novajoin Added note about permission needed when migrating from novajoin to tripleo-ipa. Also added notes indicating that novajoin is no longer available in Victoria. Change-Id: I614ab9eb39d3b46fa1f854bae4656c35fd48da48
2020-09-18 15:21:24 -04:00
If your IPA server is not at 4.8.5 or higher, you will need to add an
Add missing FreeIPA install steps We need a couple of additional steps for the IPA setup. Change-Id: I8038a6ca4ad6ea02184195a4052a22d84a658fa2
2020-05-15 15:25:38 -04:00
ACL to allow for the proper generation of certificates with a IP SAN.::
cat << EOF | ldapmodify -x -D "cn=Directory Manager" -w $DIRECTORY_MANAGER_PASSWORD
dn: cn=dns,dc=example,dc=com
changetype: modify
add: aci
aci: (targetattr = "aaaarecord || arecord || cnamerecord || idnsname || objectclass || ptrrecord")(targetfilter = "(&(objectclass=idnsrecord)(|(aaaarecord=*)(arecord=*)(cnamerecord=*)(ptrrecord=*)(idnsZoneActive=TRUE)))")(version 3.0; acl "Allow hosts to read DNS A/AAA/CNAME/PTR records"; allow (read,search,compare) userdn = "ldap:///fqdn=*,cn=computers,cn=accounts,dc=example,dc=com";)
EOF
Add notes on removing novajoin Added note about permission needed when migrating from novajoin to tripleo-ipa. Also added notes indicating that novajoin is no longer available in Victoria. Change-Id: I614ab9eb39d3b46fa1f854bae4656c35fd48da48
2020-09-18 15:21:24 -04:00
If you are upgrading to Victoria and you have been using novajoin, an additional permission
must be added to the Nova Host Manager role to allow the creation of DNS zone entries.
As an admin user::
ipa privilege-add-permission 'Nova Host Management' --permission \
'System: Modify Realm Domains'
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
Please refer to ``ipa-server-install --help`` for specifics on each argument or
reference the `FreeIPA documentation`_. The directions above are only a guide.
You may need to adjust certain values and configuration options to use FreeIPA,
depending on your requirements.
.. _FreeIPA documentation: https://www.freeipa.org/page/Documentation
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
Novajoin
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
--------
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
`Novajoin`_ is a vendor data service that extends nova's config drive
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
functionality and you use it when you want to deploy *TLS-everywhere*. When the
undercloud creates new nodes for the overcloud, novajoin creates a host entry
in FreeIPA to enable the overcloud node to enroll as a FreeIPA client.
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
If you want to use novajoin, you must have nova deployed in your undercloud.
Novajoin isn't supported for deployments :doc:`deployed_server`.
Novajoin was introduced in the Queens release and is supported through Train.
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
The `tripleo-ipa`_ project, described below, effectively replaced novajoin in
the Train release.
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
Add notes on removing novajoin Added note about permission needed when migrating from novajoin to tripleo-ipa. Also added notes indicating that novajoin is no longer available in Victoria. Change-Id: I614ab9eb39d3b46fa1f854bae4656c35fd48da48
2020-09-18 15:21:24 -04:00
As of Victoria, novajoin is not longer supported. If you are updating
from Ussuri, tripleo will automatically migrate your deployment from novajoin
to tripleo-ipa. Tripleo will stop and remove the novajoin containers from
the undercloud. If in-flight validations are enabled, tripleo will run a
pre-upgrade validation to verify that the needed ACI and permissions have been
added to the FreeIPA server. See the previous section on "Installing FreeIPA"
for more details.
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
.. _Novajoin: https://opendev.org/x/novajoin
tripleo-ipa
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
-----------
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
`tripleo-ipa`_ is a collection of Ansible roles used to integrate FreeIPA into
Refactor TLS introduction The TLS-everywhere introduction contains some useful information for the ways you can deploy TLS (public TLS and TLS everywhere). As well as primers on the components used to implement TLS. This commit generalizes the introduction so we can re-use it for public TLS and TLS-everywhere. Subsequent patches will add separate guides that describe how to accomplish both deployment techniques. Change-Id: Ieea23577095dd910c9923a8d1285561a72038a46
2020-05-18 18:26:48 +00:00
TripleO deployments and you use it when you want to deploy *TLS-everywhere*.
These playbooks support deployments using nova and ironic in the undercloud as
well as :doc:`deployed_server`. This project was introduced in Train and
effectively replaces the novajoin metadata service.
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
We recommend using tripleo-ipa for all *TLS-everywhere* deployments as of the
Add notes on removing novajoin Added note about permission needed when migrating from novajoin to tripleo-ipa. Also added notes indicating that novajoin is no longer available in Victoria. Change-Id: I614ab9eb39d3b46fa1f854bae4656c35fd48da48
2020-09-18 15:21:24 -04:00
Train release. As of Victoria, tripleo-ipa is the only supported method to
configure and deploy *TLS-everywhere*.
Add a new introduction for TLS documentation The existing documentation is full of useful bits for setting up TLS everywhere and TLS for public-only endpoints. This commit adds an introduction that attempts to describe the usecases for using TLS. Additionally, it adds short, concise descriptions of the components needed in TLS deployments and why they're important. This is going to be the first of a series of documentation patches that attempt to refactor the existing TLS/SSL documentation to be more use-case driven. The goal is to make it easier for readers and TripleO developers to understand how TLS works in TripleO. Change-Id: I7eaf8f852eaccf4debd0b5095c2622c53b09de4d
2019-10-31 09:19:19 -05:00
.. _tripleo-ipa: https://opendev.org/x/tripleo-ipa
Copy Permalink