diff --git a/deploy-guide/source/app-certificate-management.rst b/deploy-guide/source/app-certificate-management.rst index 9aa11c8..086dca6 100644 --- a/deploy-guide/source/app-certificate-management.rst +++ b/deploy-guide/source/app-certificate-management.rst @@ -1,6 +1,6 @@ -==================================== -Managing TLS certificates with Vault -==================================== +========================= +Managing TLS certificates +========================= Overview -------- @@ -11,23 +11,23 @@ certificate authority to your model. The charms consume the certificates through the `tls-certificates relation`_ and we do our validation using the `Vault charm`_. -Enabling Vault Certificate Management +Enabling Vault certificate management ------------------------------------- OpenStack charms providing an API service have a new 'certificates' relation. Adding this relation will trigger the OpenStack charm to request certificates and keys from vault. Once vault has provided these the charm -will install them and switch to listening on https, the catalog will also be +will install them and switch to listening on https, the catalogue will also be updated. -.. code:: bash +.. code-block:: none - juju add-relation keystone:certificates vault:certificates - juju add-relation glance:certificates vault:certificates - juju add-relation cinder:certificates vault:certificates - juju add-relation nova-cloud-controller:certificates vault:certificates - juju add-relation neutron-api:certificates vault:certificates - ... + juju add-relation keystone:certificates vault:certificates + juju add-relation glance:certificates vault:certificates + juju add-relation cinder:certificates vault:certificates + juju add-relation nova-cloud-controller:certificates vault:certificates + juju add-relation neutron-api:certificates vault:certificates + ... Adding a Certificate Authority (CA) certificate to Vault ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,11 +60,11 @@ Retrieve CSR from Vault Run the *get-csr* action against the lead unit of the vault application: -.. code:: bash +.. code-block:: none - $ juju run-action vault/0 get-csr + juju run-action vault/0 get-csr Action queued with id: 0495b6ce-09d8-4e57-8d21-efa13794034a - $ juju show-action-output 0495b6ce-09d8-4e57-8d21-efa13794034a + juju show-action-output 0495b6ce-09d8-4e57-8d21-efa13794034a results: output: |- -----BEGIN CERTIFICATE REQUEST----- @@ -89,7 +89,6 @@ Run the *get-csr* action against the lead unit of the vault application: enqueued: 2018-06-07 10:21:13 +0000 UTC started: 2018-06-07 10:21:13 +0000 UTC - Retrieve the CSR from the action output and place it in a file, removing any leading whitespace. @@ -99,75 +98,72 @@ Sign CSR The exact command from signing the CSR will depend on the setup of the external CA. Below is an example: -.. code:: bash +.. code-block:: none - openssl ca -config openssl.cnf -extensions v3_intermediate_ca -days 3650 \ - -notext -md sha256 -in csr_file -out /tmp/vault-charm-int.pem -batch \ - -passin pass:secretpassword + openssl ca -config openssl.cnf -extensions v3_intermediate_ca -days 3650 \ + -notext -md sha256 -in csr_file -out /tmp/vault-charm-int.pem -batch \ + -passin pass:secretpassword *If the signing is rejected due to mismatched O or OU or C etc then rerun the -get-csr actions and specify the mismatched items* +get-csr actions and specify the mismatched items.* -Upload signed CSR and root CA cert to vault +Upload signed CSR and root CA cert to Vault ........................................... (Where /tmp/root-ca.pem is the root ca cert) -.. code:: bash +.. code-block:: none - juju run-action vault/0 upload-signed-csr \ - pem="$(cat /tmp/vault-charm-int.pem | base64)" \ - root-ca="$(cat /tmp/root-ca.pem | base64)" \ - allowed-domains='openstack.local' + juju run-action vault/0 upload-signed-csr \ + pem="$(cat /tmp/vault-charm-int.pem | base64)" \ + root-ca="$(cat /tmp/root-ca.pem | base64)" \ + allowed-domains='openstack.local' .. note:: - The certificates provided via the 'pem' parameter must be a PEM bundle - containing the signed certificate, any intermediate CA certs external - to Vault and the root CA cert. Without this information Vault cannot - verify the trust chain and will reject the provided certificate - see - `RFC5280`_ for more details about certificate paths and trust. + The certificates provided via the 'pem' parameter must be a PEM bundle + containing the signed certificate, any intermediate CA certs external to + Vault and the root CA cert. Without this information Vault cannot verify + the trust chain and will reject the provided certificate - see `RFC5280`_ + for more details about certificate paths and trust. - If external intermediate CAs are in use the root-ca PEM must also - be a PEM bundle including certs for all intermediate CAs and the root - CA. + If external intermediate CAs are in use the root-ca PEM must also be a PEM + bundle including certs for all intermediate CAs and the root CA. - For more details about the format of certificate PEM bundles see - `RFC7468`_. + For more details about the format of certificate PEM bundles see `RFC7468`_. Vault issues certificates ~~~~~~~~~~~~~~~~~~~~~~~~~ -Vault will now issue certificates to all clients that have requested them. -This process will trigger the api charms to request endpoint updates from -keystone to reflect that they are now using https. This can be a lengthy -process, so monitor keystone units and wait for them to become idle. +Vault will now issue certificates to all clients that have requested them. This +process will trigger the api charms to request endpoint updates from keystone +to reflect that they are now using https. This can be a lengthy process, so +monitor keystone units and wait for them to become idle. -.. code:: bash +.. code-block:: none - - watch -d juju status keystone + watch -d juju status keystone Test ~~~~ Where /tmp/root-ca.pem is the root CA cert: -.. code:: bash +.. code-block:: none - source novarc # make sure you have https in OS_AUTH_URL + source novarc # make sure you have https in OS_AUTH_URL - echo "Testing: keystone" - openstack --os-cacert /tmp/root-ca.pem catalog list - echo "Testing: nova-cloud-controller" - openstack --os-cacert /tmp/root-ca.pem server list - echo "Testing: cinder" - openstack --os-cacert /tmp/root-ca.pem volume list - echo "Testing: neutron" - openstack --os-cacert /tmp/root-ca.pem network list - echo "Testing: image" - openstack --os-cacert /tmp/root-ca.pem image list - deactivate + echo "Testing: keystone" + openstack --os-cacert /tmp/root-ca.pem catalog list + echo "Testing: nova-cloud-controller" + openstack --os-cacert /tmp/root-ca.pem server list + echo "Testing: cinder" + openstack --os-cacert /tmp/root-ca.pem volume list + echo "Testing: neutron" + openstack --os-cacert /tmp/root-ca.pem network list + echo "Testing: image" + openstack --os-cacert /tmp/root-ca.pem image list + deactivate Reissuing certificates ~~~~~~~~~~~~~~~~~~~~~~ @@ -176,7 +172,7 @@ The vault charm has an *reissue-certificates* action. Running the action will cause vault to issue new certificates for all charm clients. The action must be run on the lead unit. -.. code:: bash +.. code-block:: none juju run-action vault/0 reissue-certificates diff --git a/deploy-guide/source/app-ha.rst b/deploy-guide/source/app-ha.rst index c2c4ed2..c8753d3 100644 --- a/deploy-guide/source/app-ha.rst +++ b/deploy-guide/source/app-ha.rst @@ -728,8 +728,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 `Managing TLS certificates with -Vault`_ for how to use a chain. +We'll do the former here for simplicity but see `Managing TLS certificates`_ +for how to use a chain. .. code-block:: none @@ -816,7 +816,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 -.. _Managing TLS certificates with Vault: app-certificate-management.html +.. _Managing TLS certificates: app-certificate-management.html .. BUGS .. _LP #1234561: https://bugs.launchpad.net/charm-ceph-osd/+bug/1234561 diff --git a/deploy-guide/source/app-hardware-offload.rst b/deploy-guide/source/app-hardware-offload.rst index a2cf769..1cf83f1 100644 --- a/deploy-guide/source/app-hardware-offload.rst +++ b/deploy-guide/source/app-hardware-offload.rst @@ -1,6 +1,6 @@ -=========================== -Network hardware offloading -=========================== +=================== +Hardware offloading +=================== Overview -------- diff --git a/deploy-guide/source/app-octavia.rst b/deploy-guide/source/app-octavia.rst index 943b176..757f1d6 100644 --- a/deploy-guide/source/app-octavia.rst +++ b/deploy-guide/source/app-octavia.rst @@ -1,42 +1,38 @@ -============= -Octavia LBaaS -============= +============== +Load balancing +============== Overview -------- -As of the 18.11 charm release, with OpenStack Rocky and later, OpenStack -Octavia can be deployed to provide Load-balancing services as part of an -OpenStack Cloud. This service supersedes the LBaaS v2 services provided -directly through Neutron in earlier releases; when Octavia is deployed -a proxy service is configured to proxy LBaaS v2 API calls directly to -Octavia. +OpenStack Octavia can be deployed to provide Load balancing services as part of +an OpenStack cloud. This service supersedes the LBaaS v2 services provided +directly through Neutron in earlier releases; when Octavia is deployed a proxy +service is configured to proxy LBaaS v2 API calls directly to Octavia. -Octavia uses cloud resources to provision instances to provide LBaaS -services unlike the LBaaS v2 support in the OpenStack Charms which -placed haproxy instances on neutron-gateway units. +.. note:: + + Octavia is supported by Charmed OpenStack starting with OpenStack Rocky. + +Octavia uses cloud resources to provision instances to provide LBaaS services +unlike the LBaaS v2 support in the OpenStack Charms which placed haproxy +instances on neutron-gateway units. .. warning:: - Octavia is only supported by the OpenStack Charms for OpenStack - Rocky or later. - -.. warning:: - - There is no automatic migration path for Neutron LBaaS - haproxy-on-host configurations (as deployed under the existing - support) to Octavia Amphora configurations. New load balancers - must be created in Octavia before the octavia charm is related - to the existing neutron-api charm. Floating IP's can then be - moved prior to deletion of existing LBaaS based balancers. + There is no automatic migration path for Neutron LBaaS haproxy-on-host + configurations (as deployed under the existing support) to Octavia Amphora + configurations. New load balancers must be created in Octavia before the + octavia charm is related to the existing neutron-api charm. Floating IPs + can then be moved prior to deletion of existing LBaaS based balancers. Deployment ---------- -.. warning:: +.. note:: - Throughout this guide make sure ``openstack-origin`` matches the value you - used when `deploying OpenStack`_. + Throughout the deployment, ensure that the value for ``openstack-origin`` + matches the currently deployed OpenStack release. Octavia uses OpenStack Barbican to store certificates for TLS termination on load balancers. Barbican, in turn, uses Vault to securely store that data. @@ -44,8 +40,8 @@ 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. + management information read the `Managing TLS certificates`_ section of this + guide. To deploy Barbican: @@ -59,7 +55,8 @@ To deploy Barbican: juju add-relation barbican barbican-vault juju add-relation barbican-vault vault -Octavia can then be deployed: +Octavia can then be deployed. Use the appropriate section depending on your +cloud's networking framework: Neutron ML2+OVS ~~~~~~~~~~~~~~~ @@ -91,28 +88,25 @@ Neutron ML2+OVN juju deploy octavia-dashboard juju add-relation octavia-dashboard openstack-dashboard - .. note:: - Octavia uses a Neutron network for communication between - Octavia control plane services and Octavia Amphorae; units will - deploy into a 'blocked' state until the configuration steps - are executed. + Octavia uses a Neutron network for communication between Octavia control + plane services and Octavia Amphorae; units will deploy into a 'blocked' + state until the configuration steps are executed. Configuration ------------- -Generate Certificates +Generate certificates ~~~~~~~~~~~~~~~~~~~~~ Octavia uses client certificates for authentication and security of -communication between Amphorae (load balancers) and the Octavia -control plane; for the initial version of the Octavia charm, these -must be generated by the operator and provided to the Octavia charm -as configuration. +communication between Amphorae (load balancers) and the Octavia control plane; +for the initial version of the Octavia charm, these must be generated by the +operator and provided to the Octavia charm as configuration. -The script below generates example certificates and keys with a 365 -day expiry period: +The script below generates example certificates and keys with a 365 day expiry +period: .. code-block:: none @@ -143,8 +137,7 @@ day expiry period: -in controller.csr -days 365 -out controller_cert.pem cat controller_cert.pem controller_key.pem > controller_cert_bundle.pem - -The generated certs and keys must then be provided to the octavia charm: +The generated certificates and keys must then be provided to the octavia charm: .. code-block:: none @@ -160,7 +153,7 @@ The generated certs and keys must then be provided to the octavia charm: Future versions of the charm may automatically generate the internal Certification Authority required to operate Octavia. -Resource Configuration +Resource configuration ~~~~~~~~~~~~~~~~~~~~~~ The charm will automatically create and maintain the resources required for @@ -184,9 +177,9 @@ full custom configuration of the management network for Octavia. If you want to manage these resources yourself you must set the `create-mgmt-network` configuration option to false. -Network resources for use by Octavia must be tagged using Neutron resource -tags (typically by passing a '--tag' CLI parameter when creating resources - -see the OpenStack CLI for more details) using the following schema: +Network resources for use by Octavia must be tagged using Neutron resource tags +(typically by passing a '--tag' CLI parameter when creating resources - see the +OpenStack CLI for more details) using the following schema: =========================== ====================== ========================================================= Resource Type Tag Description @@ -199,8 +192,8 @@ Controller Security Group charm-octavia-health Security group for Controller =========================== ====================== ========================================================= Execution of the `configure-resources` action will detect the pre-configured -network resources in Neutron using tags and configure the Octavia service -as appropriate. +network resources in Neutron using tags and configure the Octavia service as +appropriate. The UUID of the Nova flavor to use for Amphorae can be set using the `custom-amp-flavor-id` configuration option. @@ -208,8 +201,9 @@ The UUID of the Nova flavor to use for Amphorae can be set using the Amphora image ~~~~~~~~~~~~~ -Octavia uses Amphorae (cloud instances running HAProxy) to provide LBaaS services; -an appropriate image must be uploaded to Glance with the tag `octavia-amphora`. +Octavia uses Amphorae (cloud instances running HAProxy) to provide LBaaS +services; an appropriate image must be uploaded to Glance with the tag +`octavia-amphora`. You can use the ``octavia-diskimage-retrofit`` tool to transform a stock Ubuntu cloud image into a Octavia HAProxy Amphora image. @@ -236,7 +230,7 @@ After the deployment has settled and ``glance-simplestreams-sync`` has completed its initial image sync, you may ask a ``octavia-diskimage-retrofit`` unit to initiate the Amphora image retrofitting process. -This is accomplished through running an action on one of the units. +This is accomplished by running an action on one of the units. .. code-block:: none @@ -246,9 +240,8 @@ Octavia will use this image for all Amphora instances. .. warning:: - It's important to keep the Amphora image up-to-date to ensure that - LBaaS services remain secure; this process is not covered in this - document. + It's important to keep the Amphora image up-to-date to ensure that LBaaS + services remain secure; this process is not covered in this document. See the Octavia `operators maintenance`_ guide for more details. @@ -275,23 +268,24 @@ To deploy a basic HTTP load balancer using a floating IP for access: The example above assumes: - - The user and project executing the example has a subnet configured - with the name `private_subnet` with the CIDR 192.168.21.0/24 - - An external network definition for floating IP's has been configured - by the cloud operator with the name `ext_net` - - Two instances running HTTP services attached to the `private_subnet` - on IP addresses 192.168.21.{100,101} exposing a heat check on `/healthcheck` +* The user and project executing the example has a subnet configured with the + name 'private_subnet' with the CIDR 192.168.21.0/24 -The example is also most applicable in cloud deployments which use overlay -networking for project networks and floating IP's for network ingress to project +* An external network definition for floating IPs has been configured by the + cloud operator with the name 'ext_net' + +* Two instances running HTTP services attached to 'private_subnet' on IP + addresses 192.168.21.{100,101} exposing a heat check on '/healthcheck' + +The example is also most applicable in cloud deployments that use overlay +networking for project networks and floating IPs for network ingress to project networks. For more information on creating and configuring load balancing services in Octavia please refer to the `Octavia cookbook`_. .. LINKS -.. _deploying OpenStack: install-openstack.html -.. _Managing TLS certificates with Vault: app-certificate-management.html +.. _Managing TLS certificates: 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 diff --git a/deploy-guide/source/app-ovn.rst b/deploy-guide/source/app-ovn.rst index 93e000c..c59b55f 100644 --- a/deploy-guide/source/app-ovn.rst +++ b/deploy-guide/source/app-ovn.rst @@ -5,10 +5,8 @@ Open Virtual Network (OVN) Overview -------- -As of the 19.10 OpenStack Charms release, with OpenStack Train or later, -support for integration with Open Virtual Network (OVN) is available. As of -the 20.05 OpenStack Charms release OVN is the preferred default for our -`OpenStack Base bundle`_ reference implementation. +Open Virtual Network (OVN) can be deployed to provide networking services as +part of an OpenStack cloud. .. note:: @@ -25,6 +23,12 @@ OVN charms: * ovn-dedicated-chassis +.. note:: + + OVN is supported by Charmed OpenStack starting with OpenStack Train. OVN is + the default configuration in the `OpenStack Base bundle`_ reference + implementation. + Deployment ---------- @@ -36,8 +40,8 @@ Certificates must be managed by Vault. .. note:: For Vault deployment instructions see the `vault charm`_. For certificate - management information read the `Managing TLS certificates with Vault`_ - section of this guide. + management information read the `Managing TLS certificates`_ section of this + guide. To deploy OVN: @@ -104,8 +108,7 @@ for use with hardware offloading and make them available to OpenStack. To use the feature you need to use supported network interface card (NIC) hardware. We have done feature validation using the Mellanox ConnectX-5 NICs. -Please refer to `Network hardware offloading`_ for more background on the -feature. +Please refer to `Hardware offloading`_ for more background on the feature. Hardware offload support makes use of SR-IOV as an underlying mechanism to accelerate the data path between a virtual machine instance and the NIC @@ -121,9 +124,8 @@ with appropriate driver and firmware support. Prerequisites ^^^^^^^^^^^^^ -Please refer to the `SR-IOV for networking support`_ section and the `Network -hardware offloading`_ page for information on hardware and kernel -configuration. +Please refer to the `SR-IOV for networking support`_ section and the `Hardware +offloading`_ page for information on hardware and kernel configuration. Charm configuration ^^^^^^^^^^^^^^^^^^^ @@ -814,9 +816,9 @@ of the actual migration. topology. 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. + `Managing TLS certificates`_), and validate that the services on ovn-central + units are running as expected. Please refer to the `Usage`_ section for more + information. Perform migration ~~~~~~~~~~~~~~~~~ @@ -1002,7 +1004,7 @@ Perform migration .. LINKS .. _vault charm: https://jaas.ai/vault/ -.. _Managing TLS certificates with Vault: app-certificate-management.html +.. _Managing TLS certificates: 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/ @@ -1017,7 +1019,7 @@ Perform migration .. _DPDK supported hardware page: http://core.dpdk.org/supported/ .. _MAAS: https://maas.io/ .. _Customizing instance huge pages allocations: https://docs.openstack.org/nova/latest/admin/huge-pages.html#customizing-instance-huge-pages-allocations -.. _Network hardware offloading: app-hardware-offload.html +.. _Hardware offloading: app-hardware-offload.html .. _SR-IOV for networking support: app-ovn.html#sr-iov-for-networking-support .. _traffic control monitor: http://manpages.ubuntu.com/manpages/focal/man8/tc.8.html#monitor .. _data path control tools: http://manpages.ubuntu.com/manpages/focal/man8/ovs-dpctl.8.html diff --git a/deploy-guide/source/upgrade-issues.rst b/deploy-guide/source/upgrade-issues.rst index 0c523de..8c9fe44 100644 --- a/deploy-guide/source/upgrade-issues.rst +++ b/deploy-guide/source/upgrade-issues.rst @@ -2,7 +2,8 @@ Known upgrade issues ==================== -This section documents known software upgrade issues. +This section documents known issues that may apply to either of the three +upgrade types (charms, OpenStack, series). DNS HA with the focal series ---------------------------- @@ -37,16 +38,16 @@ See bug `LP #1809190`_. cinder/ceph topology change: upgrading from Newton to Ocata ----------------------------------------------------------- -If ``cinder`` is directly related to ``ceph-mon`` rather than via -``cinder-ceph`` then upgrading from Newton to Ocata will result in the loss of -some block storage functionality, specifically live migration and snapshotting. -To remedy this situation the deployment should migrate to using the cinder-ceph -charm. This can be done after the upgrade to Ocata. +If cinder is directly related to ceph-mon rather than via cinder-ceph then +upgrading from Newton to Ocata will result in the loss of some block storage +functionality, specifically live migration and snapshotting. To remedy this +situation the deployment should migrate to using the cinder-ceph charm. This +can be done after the upgrade to Ocata. .. warning:: Do not attempt to migrate a deployment with existing volumes to use the - ``cinder-ceph`` charm prior to Ocata. + cinder-ceph charm prior to Ocata. The intervention is detailed in the below three steps. diff --git a/deploy-guide/source/upgrade-special.rst b/deploy-guide/source/upgrade-special.rst index aad9f06..1ce22d9 100644 --- a/deploy-guide/source/upgrade-special.rst +++ b/deploy-guide/source/upgrade-special.rst @@ -1,6 +1,6 @@ -========================== -Special upgrade procedures -========================== +================================ +Special charm upgrade procedures +================================ The OpenStack charms are designed to accommodate every supported series and OpenStack release wherever possible. However, upgrades may occasionally