commit 51b69e9b16d248d3d1c73390e3d3d1cb98eba9e0 Author: Mark Goddard Date: Fri Oct 9 16:30:09 2020 +0100 docs: Add information on migrating to CentOS 8 More detailed information on the migration process to follow. Related-Bug: #1864368 Change-Id: I5d45088669ff2f35031e5f17bd38d7230a6730e1 diff --git a/doc/source/user/centos8.rst b/doc/source/user/centos8.rst new file mode 100644 index 0000000..870e5a3 --- /dev/null +++ b/doc/source/user/centos8.rst @@ -0,0 +1,136 @@ +======== +CentOS 8 +======== + +This section covers use of Kolla Ansible on CentOS 8 in the Train release. From +the 9.1.0 release, Kolla Ansible supports both CentOS 7 and 8. + +Scope +----- + +We must consider the OS distribution and version running on the host, and in +the containers. Kolla Ansible does not support mixing different OS +distributions between the host and containers, nor does it support mixing +different major OS versions between the host and containers. The following +combinations are therefore supported: + +* Host: CentOS 7, containers: CentOS 7 +* Host: CentOS 8, containers: CentOS 8 + +Upgrade path +------------ + +The Train release is the last release to support CentOS 7, and the first to +support CentOS 8. CentOS 7 users wishing to upgrade beyond Train must therefore +migrate to CentOS 8. The upgrade path looks like this: + +* Stein & earlier (CentOS 7) +* Train (CentOS 7) +* Train (CentOS 8) +* Ussuri & later (CentOS 8) + +Feature removal +--------------- + +Note that the following features available on CentOS 7 are not available on +CentOS 8: + +* integrated Ceph deployment. External Ceph integration is still supported. +* SCSI target daemon has been dropped in favour of LIO. + ``cinder_target_helper`` is now ``lio`` by default on CentOS 8. + +Container images +---------------- + +For details on how to build images for CentOS 8, see the :kolla-doc:`Kolla +image building guide `. Note +that for the Train release only, Kolla Ansible applies a ``-centos8`` suffix +(configured via ``openstack_tag_suffix``) to image tags by default on CentOS 8 +hosts. The default tag on CentOS 8 hosts is therefore ``train-centos8``. This +is to differentiate CentOS 7 and CentOS 8 container images. + +Migrating from CentOS 7 to CentOS 8 +----------------------------------- + +This section describes how to migrate an existing deployment from CentOS 7 to +CentOS 8. + +There is no supported upgrade path from CentOS 7 to CentOS 8. Since we want to +use the same major versions of CentOS in the host and containers, the hosts +must be reinstalled with CentOS 8 before CentOS 8 containers are deployed. +Where possible, this should be done in batches to avoid downtime. The high +level workflow is: + +* deploy or upgrade to the Train release onto CentOS 7 hosts +* upgrade services to ensure compatibility with those available in CentOS 8 +* migrate hosts to CentOS 8 in batches + +Note that in a multi-node system it is possible to have a mix of CentOS 7 and +CentOS 8 hosts while the migration takes place. + +Service compatibility +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to ensure the services running on CentOS 7 hosts are +compatible with those that will be deployed on CentOS 8 hosts. + +RabbitMQ +######## + +CentOS 7 by default uses RabbitMQ 3.7.10. CentOS 8 supports only RabbitMQ +3.7.24+. It is therefore necessary to upgrade RabbitMQ containers on CentOS 7 +hosts to be compatible with those on CentOS 8 hosts. This can be done by adding +the following in ``globals.yml``: + +.. code-block:: yaml + + rabbitmq_use_3_7_24_on_centos7: true + +Now upgrade RabbitMQ: + +.. code-block:: console + + kolla-ansible -i upgrade -t rabbitmq + +Elasticsearch & Kibana +###################### + +CentOS 7 by default uses Elasticsearch and Kibana 5.x. CentOS 8 supports only +6.x. It is therefore necessary to upgrade Elasticsearch and Kibana containers +on CentOS 7 hosts to be compatible with those on CentOS 8 hosts. This can be +done by adding the following in ``globals.yml``: + +.. code-block:: yaml + + elasticsearch_use_v6: true + kibana_use_v6: true + +Now upgrade Elasticsearch & Kibana: + +.. code-block:: console + + kolla-ansible -i upgrade -t elasticsearch,kibana + +Batched migration +~~~~~~~~~~~~~~~~~ + +This section describes how to perform a batched migration of hosts from CentOS +7 to CentOS 8. + +It is recommended to migrate hosts in the following order: + +* controllers +* compute nodes + +Within each of the above groups, hosts should be migrated in batches of a +suitable size. The batch size should be chosen taking into consideration +availability and capacity constraints. Testing should be performed after each +batch to verify the system is functioning correctly. + +For each batch, the high level workflow is: + +* remove the batch of hosts from the cluster +* reinstall the batch of hosts using CentOS 8 (out of scope for Kolla Ansible) +* bootstrap the batch of hosts +* deploy services to the batch of hosts +* verify the operation was successful diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 498e798..314df8f 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -11,5 +11,6 @@ User Guides multinode multi-regions operating-kolla + centos8 security troubleshooting diff --git a/doc/source/user/support-matrix.rst b/doc/source/user/support-matrix.rst index f3304d3..5276bc3 100644 --- a/doc/source/user/support-matrix.rst +++ b/doc/source/user/support-matrix.rst @@ -31,10 +31,4 @@ For details of which images are supported on which distributions, see the CentOS 8 -------- -For details on how to build images for CentOS 8, see the :kolla-doc:`Kolla -image building guide `. Note -that for the Train release only, Kolla Ansible applies a ``-centos8`` suffix -(configured via ``openstack_tag_suffix``) to image tags by default on CentOS 8 -hosts. The default tag is therefore ``train-centos8``. This is to -differentiate CentOS 7 and CentOS 8 container images. Information about -migrating from CentOS 7 to CentOS 8 will be provided soon. +Information on CentOS 8 is provided in :doc:`centos8`.