diff --git a/deploy-guide/source/app-certificate-management.rst b/deploy-guide/source/app-certificate-management.rst index 4e9614d..9aa11c8 100644 --- a/deploy-guide/source/app-certificate-management.rst +++ b/deploy-guide/source/app-certificate-management.rst @@ -1,6 +1,6 @@ -============================================ -Appendix E: Certificate Lifecycle Management -============================================ +==================================== +Managing TLS certificates with Vault +==================================== Overview -------- @@ -11,12 +11,6 @@ certificate authority to your model. The charms consume the certificates through the `tls-certificates relation`_ and we do our validation using the `Vault charm`_. -Vault ------ - -See `Appendix C Vault <./app-vault.html>`__ - - Enabling Vault Certificate Management ------------------------------------- diff --git a/deploy-guide/source/app-encryption-at-rest.rst b/deploy-guide/source/app-encryption-at-rest.rst index 6a93322..66fee91 100644 --- a/deploy-guide/source/app-encryption-at-rest.rst +++ b/deploy-guide/source/app-encryption-at-rest.rst @@ -22,7 +22,7 @@ event that disks or full servers are removed from data center deployments. Vault +++++ -See `Appendix C Vault <./app-vault.html>`__ +See the `vault charm`_. Enabling Encryption +++++++++++++++++++ @@ -69,3 +69,5 @@ LUKS encryption keys are never store on local disk; vaultlocker is used to encry and store the key in vault, and to retrieve the key and open encrypted block devices during boot. Keys are only ever held in memory. +.. LINKS +.. _vault charm: https://jaas.ai/vault/ diff --git a/deploy-guide/source/app-ha.rst b/deploy-guide/source/app-ha.rst index ae3e163..39043f6 100644 --- a/deploy-guide/source/app-ha.rst +++ b/deploy-guide/source/app-ha.rst @@ -730,8 +730,8 @@ are working nova-compute and vault applications. Finally, you will need to provide an SSL certificate. This can be done by having Vault use a self-signed certificate or by using a certificate chain. -We'll do the former here for simplicity but see `Certificate lifecycle -management`_ for how to use a chain. +We'll do the former here for simplicity but see `Managing TLS certificates with +Vault`_ for how to use a chain. .. code-block:: none @@ -818,7 +818,7 @@ Charms`_ project group. .. _Clustered Database Service Model: http://docs.openvswitch.org/en/latest/ref/ovsdb.7/#clustered-database-service-model .. _Raft algorithm: https://raft.github.io/ .. _Ceph bucket type: https://docs.ceph.com/docs/master/rados/operations/crush-map/#types-and-buckets -.. _Certificate lifecycle management: app-certificate-management +.. _Managing TLS certificates with Vault: app-certificate-management.html .. BUGS .. _LP #1234561: https://bugs.launchpad.net/charm-ceph-osd/+bug/1234561 diff --git a/deploy-guide/source/app-managing-power-events.rst b/deploy-guide/source/app-managing-power-events.rst index 7947333..1062968 100644 --- a/deploy-guide/source/app-managing-power-events.rst +++ b/deploy-guide/source/app-managing-power-events.rst @@ -1125,7 +1125,6 @@ Charms`_ project group. .. _percona-cluster charm: https://opendev.org/openstack/charm-percona-cluster/src/branch/master/README.md#cold-boot .. _How to recover a PXC cluster: https://www.percona.com/blog/2014/09/01/galera-replication-how-to-recover-a-pxc-cluster .. _Percona XtraDB sequence numbers: https://www.percona.com/blog/2017/12/14/sequence-numbers-seqno-percona-xtradb-cluster/ -.. _Vault appendix: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide/latest/app-vault.html .. _High availability: https://docs.openstack.org/arch-design/arch-requirements/arch-requirements-ha.html .. _Control plane architecture: https://docs.openstack.org/arch-design/design-control-plane.html .. _Evacuate instances: https://docs.openstack.org/nova/latest/admin/evacuate.html diff --git a/deploy-guide/source/app-octavia.rst b/deploy-guide/source/app-octavia.rst index 9898db7..dd747b6 100644 --- a/deploy-guide/source/app-octavia.rst +++ b/deploy-guide/source/app-octavia.rst @@ -38,11 +38,16 @@ Deployment Throughout this guide make sure ``openstack-origin`` matches the value you used when `deploying OpenStack`_. -Octavia makes use of OpenStack Barbican for storage of certificates for -TLS termination on load balancers; Barbican makes use of Vault for secure -storage of this data. Follow the instructions for deployment and -configuration of Vault in the `Vault`_ and `Certificate Lifecycle Management`_ -appendices and then deploy Barbican: +Octavia uses OpenStack Barbican to store certificates for TLS termination on +load balancers. Barbican, in turn, uses Vault to securely store that data. + +.. note:: + + For Vault deployment instructions see the `vault charm`_. For certificate + management information read the `Managing TLS certificates with Vault`_ + section of this guide. + +To deploy Barbican: .. code-block:: none @@ -285,9 +290,9 @@ For more information on creating and configuring load balancing services in Octavia please refer to the `Octavia cookbook`_. .. LINKS -.. _Vault: app-vault -.. _Certificate Lifecycle Management: app-certificate-management -.. _deploying OpenStack: install-openstack +.. _deploying OpenStack: install-openstack.html +.. _Managing TLS certificates with Vault: app-certificate-management.html .. _Octavia Policies: https://docs.openstack.org/octavia/latest/configuration/policy.html .. _Octavia cookbook: https://docs.openstack.org/octavia/latest/user/guides/basic-cookbook.html .. _operators maintenance: https://docs.openstack.org/octavia/latest/admin/guides/operator-maintenance.html#rotating-the-amphora-images +.. _vault charm: https://jaas.ai/vault/ diff --git a/deploy-guide/source/app-ovn.rst b/deploy-guide/source/app-ovn.rst index b23858d..aaf7071 100644 --- a/deploy-guide/source/app-ovn.rst +++ b/deploy-guide/source/app-ovn.rst @@ -31,11 +31,15 @@ Deployment OVN makes use of Public Key Infrastructure (PKI) to authenticate and authorize control plane communication. The charm requires a Certificate Authority to be present in the model as represented by the ``certificates`` relation. +Certificates must be managed by Vault. -Follow the instructions for deployment and configuration of Vault in -the `Vault`_ and `Certificate Lifecycle Management`_ appendices. +.. note:: -OVN can then be deployed: + For Vault deployment instructions see the `vault charm`_. For certificate + management information read the `Managing TLS certificates with Vault`_ + section of this guide. + +To deploy OVN: .. code-block:: none @@ -809,9 +813,10 @@ of the actual migration. applications. You must tailor the commands to fit with your deployments topology. -5. Unseal `Vault`_, enable `Certificate Lifecycle Management`_ and - validate that the services on ovn-central units are running as expected. - Please refer to the the `Usage`_ section for more information. +5. Unseal Vault (see the `vault charm`_), set up TLS certificates (see + `Managing TLS certificates with Vault`_), and validate that the services on + ovn-central units are running as expected. Please refer to the `Usage`_ + section for more information. Perform migration ~~~~~~~~~~~~~~~~~ @@ -996,8 +1001,8 @@ Perform migration openstack network agent delete ... .. LINKS -.. _Vault: app-vault -.. _Certificate Lifecycle Management: app-certificate-management +.. _vault charm: https://jaas.ai/vault/ +.. _Managing TLS certificates with Vault: app-certificate-management.html .. _Toward Convergence of ML2+OVS+DVR and OVN: http://specs.openstack.org/openstack/neutron-specs/specs/ussuri/ml2ovs-ovn-convergence.html .. _ovn-dedicated-chassis charm: https://jaas.ai/u/openstack-charmers/ovn-dedicated-chassis/ .. _networking-ovn plugin: https://docs.openstack.org/networking-ovn/latest/ diff --git a/deploy-guide/source/app-vault.rst b/deploy-guide/source/app-vault.rst deleted file mode 100644 index b603600..0000000 --- a/deploy-guide/source/app-vault.rst +++ /dev/null @@ -1,172 +0,0 @@ -================= -Appendix C: Vault -================= - -Overview -++++++++ - -Vault provides a secure storage and certificate management service. -Integrating Vault into an OpenStack deployment involves a number of -post-deployment steps. - -.. note:: - - For actual deployment steps see the `vault charm`_. - -Vault client -~~~~~~~~~~~~ - -Vault is needed as a client in order to manage the Vault deployment. Install it -on the host where the Juju client resides: - -.. code:: none - - sudo snap install vault - -Initialise Vault -~~~~~~~~~~~~~~~~ - -Identify the vault unit by setting the ``VAULT_ADDR`` environment variable -based on the IP address of the unit. This can be discovered from :command:`juju -status` output (column 'Public address'). Here well use '10.0.0.126': - -.. code:: none - - export VAULT_ADDR="http://10.0.0.126:8200" - -Initialise Vault by specifying the number of unseal keys that should get -generated as well as the number of unseal keys that are needed in order to -complete the unseal process. Below we will specify five and three, -respectively: - -.. code:: none - - vault operator init -key-shares=5 -key-threshold=3 - -Sample output: - -.. code:: console - - Unseal Key 1: XONSc5Ku8HJu+ix/zbzWhMvDTiPpwWX0W1X/e/J1Xixv - Unseal Key 2: J/fQCPvDeMFJT3WprfPy17gwvyPxcvf+GV751fTHUoN/ - Unseal Key 3: +bRfX5HMISegsODqNZxvNcupQp/kYQuhsQ2XA+GamjY4 - Unseal Key 4: FMRTPJwzykgXFQOl2XTupw2lfgLOXbbIep9wgi9jQ2ls - Unseal Key 5: 7rrxiIVQQWbDTJPMsqrZDKftD6JxJi6vFOlyC0KSabDB - - Initial Root Token: s.ezlJjFw8ZDZO6KbkAkm605Qv - - Vault initialized with 5 key shares and a key threshold of 3. Please securely - distribute the key shares printed above. When the Vault is re-sealed, - restarted, or stopped, you must supply at least 3 of these keys to unseal it - before it can start servicing requests. - - Vault does not store the generated master key. Without at least 3 key to - reconstruct the master key, Vault will remain permanently sealed! - - It is possible to generate new unseal keys, provided you have a quorum of - existing unseal keys shares. See "vault operator rekey" for more information. - -Besides displaying the five unseal keys the output also includes an "initial -root token". This token is used to access the Vault API. - -.. warning:: - - It is not possible to unseal Vault without the unseal keys, nor is it - possible to manage Vault without the intial root token. **Store this - information in a safe place immediately**. - -Unseal Vault -~~~~~~~~~~~~ - -Unseal the vault unit using the requisite number of unique keys (three in this -example): - -.. code:: none - - vault operator unseal XONSc5Ku8HJu+ix/zbzWhMvDTiPpwWX0W1X/e/J1Xixv - vault operator unseal FMRTPJwzykgXFQOl2XTupw2lfgLOXbbIep9wgi9jQ2ls - vault operator unseal 7rrxiIVQQWbDTJPMsqrZDKftD6JxJi6vFOlyC0KSabDB - -In an HA environment repeat the unseal process for each unit. Prior to -unsealing a different unit change the value of the ``VAULT_ADDR`` variable so -that it points to that unit. - -.. note:: - - Maintenance work on the cloud may require vault units to be paused and later - resumed. A resumed vault unit will be sealed and will therefore require - unsealing. See the `Managing power events`_ section for details. - -Proceed to the next step once all units have been unsealed. - -Authorise the vault charm -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The vault charm must be authorised to access the Vault deployment in order to -create storage backends (for secrets) and roles (to allow other applications to -access Vault for encryption key storage). - -Generate a root token with a limited lifetime (10 minutes here) using the -initial root token: - -.. code:: none - - export VAULT_TOKEN=s.ezlJjFw8ZDZO6KbkAkm605Qv - vault token create -ttl=10m - -Sample output: - -.. code:: console - - Key Value - --- ----- - token s.QMhaOED3UGQ4MeH3fmGOpNED - token_accessor nApB972Dp2lnTTIF5VXQqnnb - token_duration 10m - token_renewable true - token_policies ["root"] - identity_policies [] - policies ["root"] - -This temporary token ('token') is then used to authorise the charm: - -.. code:: none - - juju run-action --wait vault/leader authorize-charm token=s.QMhaOED3UGQ4MeH3fmGOpNED - -After the action completes execution, the vault unit(s) will become active and -any pending requests for secrets storage will be processed for consuming -applications. - -Here is sample status output for an unsealed three-unit Vault cluster: - -.. code:: console - - vault/0* active idle 0/lxd/1 10.0.0.126 8200/tcp Unit is ready (active: false, mlock: disabled) - vault-hacluster/0* active idle 10.0.0.126 Unit is ready and clustered - vault-mysql-router/0* active idle 10.0.0.126 Unit is ready - vault/1 active idle 1/lxd/1 10.0.0.130 8200/tcp Unit is ready (active: true, mlock: disabled) - vault-hacluster/2 active idle 10.0.0.130 Unit is ready and clustered - vault-mysql-router/2 active idle 10.0.0.130 Unit is ready - vault/2 active idle 2/lxd/1 10.0.0.132 8200/tcp Unit is ready (active: false, mlock: disabled) - vault-hacluster/1 active idle 10.0.0.132 Unit is ready and clustered - vault-mysql-router/1 active idle 10.0.0.132 Unit is ready - -Managing TLS certificates -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Vault can be used to manage a deployment's TLS certificates, either by basing -them on a self-signed CA certificate (that Vault can generate by itself) or on -a third-party CA certificate that you can upload to Vault. - -Vault is the recommended way to use TLS in Charmed OpenStack. This topic is -covered on the `Certificate lifecycle management`_ page. - -.. important:: - - The OVN charms require TLS certificates to be managed by Vault. - -.. LINKS -.. _vault charm: https://jaas.ai/vault -.. _Certificate lifecycle management: app-certificate-management.html -.. _Managing power events: app-managing-power-events.html#vault diff --git a/deploy-guide/source/index.rst b/deploy-guide/source/index.rst index eb2e6ab..5087bbe 100644 --- a/deploy-guide/source/index.rst +++ b/deploy-guide/source/index.rst @@ -58,8 +58,7 @@ contribution`_. :caption: Appendices :maxdepth: 1 - Vault - Certificate lifecycle management + Managing TLS certificates with Vault Encryption at Rest Octavia LBaaS Ceph erasure coding diff --git a/deploy-guide/source/install-openstack.rst b/deploy-guide/source/install-openstack.rst index 3f06dce..2564ab3 100644 --- a/deploy-guide/source/install-openstack.rst +++ b/deploy-guide/source/install-openstack.rst @@ -222,8 +222,8 @@ Here are the corresponding commands for Vault: juju add-relation vault-mysql-router:shared-db vault:shared-db Vault now needs to be initialised and unsealed. The vault charm will also need -to be authorised to carry out certain tasks. These steps are covered on the -`Vault`_ page. Perform them now. +to be authorised to carry out certain tasks. These steps are covered in the +`vault charm`_ documentation. Perform them now. Once the above is completed the Unit section output to command :command:`juju status` should look similar to this: @@ -760,7 +760,7 @@ networks, images, and a user environment. Go to :doc:`Configure OpenStack .. _Deploying applications: https://juju.is/docs/deploying-applications .. _Deploying to specific machines: https://juju.is/docs/deploying-advanced-applications#heading--deploying-to-specific-machines .. _Managing relations: https://juju.is/docs/relations -.. _Vault: app-vault.html +.. _vault charm: https://jaas.ai/vault/ .. CHARMS .. _ceph-mon: https://jaas.ai/ceph-mon