From 8cf8ab4e549db532141d2c3d5bcff7f572b1470a Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Tue, 21 Apr 2020 15:41:59 +0100
Subject: [PATCH] Add docs and release note for CentOS 8

Adds a support matrix page to documentation.

Change-Id: Ia783f7c42219617cde2accd3f1db013c9bda7679
---
 .../reference/bare-metal/ironic-guide.rst     |  4 +--
 doc/source/user/index.rst                     |  1 +
 doc/source/user/quickstart.rst                |  5 ++-
 doc/source/user/support-matrix.rst            | 32 +++++++++++++++++++
 .../notes/centos-8-ee2e13a2ecd64b1d.yaml      | 16 ++++++++++
 5 files changed, 55 insertions(+), 3 deletions(-)
 create mode 100644 doc/source/user/support-matrix.rst
 create mode 100644 releasenotes/notes/centos-8-ee2e13a2ecd64b1d.yaml

diff --git a/doc/source/reference/bare-metal/ironic-guide.rst b/doc/source/reference/bare-metal/ironic-guide.rst
index 46f9b1278a..b261f9cc75 100644
--- a/doc/source/reference/bare-metal/ironic-guide.rst
+++ b/doc/source/reference/bare-metal/ironic-guide.rst
@@ -51,10 +51,10 @@ be used:
 
 .. code-block:: console
 
-   $ curl https://tarballs.openstack.org/ironic-python-agent/dib/files/ipa-centos7-master.kernel \
+   $ curl https://tarballs.openstack.org/ironic-python-agent/dib/files/ipa-centos8-master.kernel \
      -o /etc/kolla/config/ironic/ironic-agent.kernel
 
-   $ curl https://tarballs.openstack.org/ironic-python-agent/dib/files/ipa-centos7-master.initramfs \
+   $ curl https://tarballs.openstack.org/ironic-python-agent/dib/files/ipa-centos8-master.initramfs \
      -o /etc/kolla/config/ironic/ironic-agent.initramfs
 
 You may optionally pass extra kernel parameters to the inspection kernel using:
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index ac1ed83e14..498e7987e5 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -6,6 +6,7 @@ User Guides
    :maxdepth: 2
 
    quickstart
+   support-matrix
    virtual-environments
    multinode
    multi-regions
diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst
index e99f828c7c..a87522237c 100644
--- a/doc/source/user/quickstart.rst
+++ b/doc/source/user/quickstart.rst
@@ -22,6 +22,9 @@ The host machine must satisfy the following minimum requirements:
 - 8GB main memory
 - 40GB disk space
 
+See the :kolla-ansible-doc:`support matrix <user/support-matrix>` for details
+of supported host Operating Systems.
+
 Install dependencies
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -371,7 +374,7 @@ There are a few options that are required to deploy Kolla-Ansible:
   - Debian
   - RHEL
 
-  For newcomers, we recommend to use CentOS 7 or Ubuntu 18.04.
+  For newcomers, we recommend to use CentOS 8 or Ubuntu 18.04.
 
   .. code-block:: console
 
diff --git a/doc/source/user/support-matrix.rst b/doc/source/user/support-matrix.rst
new file mode 100644
index 0000000000..945d56405d
--- /dev/null
+++ b/doc/source/user/support-matrix.rst
@@ -0,0 +1,32 @@
+==============
+Support Matrix
+==============
+
+Supported Operating Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Kolla Ansible supports the following host Operating Systems (OS):
+
+.. note::
+
+   CentOS 7 is no longer supported as a host OS. The Train release supports
+   both CentOS 7 and 8, and provides a route for migration.
+
+* CentOS 8
+* Debian Buster (10)
+* RHEL 8
+* Ubuntu Bionic (18.04)
+
+Supported container images
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For best results, the base container image distribution should match the host
+OS distribution. The following values are supported for ``kolla_base_distro``:
+
+* ``centos``
+* ``debian``
+* ``rhel``
+* ``ubuntu``
+
+For details of which images are supported on which distributions, see the
+:kolla-doc:`Kolla support matrix <support_matrix>`.
diff --git a/releasenotes/notes/centos-8-ee2e13a2ecd64b1d.yaml b/releasenotes/notes/centos-8-ee2e13a2ecd64b1d.yaml
new file mode 100644
index 0000000000..91246e76e9
--- /dev/null
+++ b/releasenotes/notes/centos-8-ee2e13a2ecd64b1d.yaml
@@ -0,0 +1,16 @@
+---
+features:
+  - |
+    Adds support for CentOS 8 as a host Operating System and base container
+    image. This is the only major version of CentOS supported from the Ussuri
+    release. The Train release supports both CentOS 7 and 8 hosts, and provides
+    a route for migration.
+upgrade:
+  - |
+    CentOS 7 is no longer supported as a host Operating System or base
+    container image. CentOS users should migrate to CentOS 8. The Train release
+    supports both CentOS 7 and 8 images, and provides a route for migration.
+  - |
+    Some images were supported by CentOS 7 but lack suitable packages in CentOS
+    8, and are no longer supported for CentOS. See `Kolla release notes
+    <https://docs.openstack.org/releasenotes/kolla/ussuri.html>`__ for details.