yoga: xena merge

README.rst

@@ -5,14 +5,9 @@ StackHPC Kayobe Configuration
 This repository provides a base Kayobe configuration for the Yoga release
 of StackHPC OpenStack.
 
-Documentation for this project is provided in the ``doc`` directory. To build
-it, run:
-
-.. code-block:: console
-
-   tox -e docs
-
-The HTML will be written to ``doc/build``.
+Documentation is hosted on `readthedocs.io
+<https://stackhpc-kayobe-config.readthedocs.io/en/stackhpc-yoga/index.html>`__,
+and includes release notes.
 
 Resources
 =========

doc/requirements.txt

@@ -2,6 +2,6 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 
-reno>=3.1.0 # Apache-2.0
+reno>=3.4.0 # Apache-2.0
 sphinx>=4.2.0 # BSD
 sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD

doc/source/conf.py

@@ -26,12 +26,29 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# -- StackHPC Kayobe configuration --------------------------------------
+# Variables to override
+
+current_series = "yoga"
+branch = f"stackhpc/{current_series}"
+
+# Substitutions loader
+rst_epilog = """
+.. |current_release| replace:: {current_release}
+.. |current_release_git_branch_name| replace:: {current_release_git_branch_name}
+""".format(  # noqa: E501
+    current_release_git_branch_name=branch,
+    current_release=current_series,
+)
+
 # -- General configuration ----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'reno.sphinxext',
     #'sphinx.ext.autodoc',
+    'sphinx.ext.extlinks',
     #'sphinx.ext.intersphinx',
     'sphinxcontrib.rsvgconverter',
 ]
@@ -91,3 +108,13 @@
 # Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
 latex_use_xindy = False
 
+extlinks_projects = {
+    "kayobe",
+    "kolla",
+    "kolla-ansible",
+}
+
+extlinks = {
+    f"{project}-doc": (f"https://docs.openstack.org/{project}/{current_series}/", "%s documentation")
+    for project in extlinks_projects
+}

doc/source/configuration/cephadm.rst

@@ -3,7 +3,7 @@ Cephadm & Kayobe
 ================
 
 This section describes how to use the Cephadm integration included in StackHPC
-Kayobe configuration since Yoga to deploy Ceph.
+Kayobe configuration since Xena to deploy Ceph.
 
 The Cephadm integration takes the form of custom playbooks that wrap
 around the Ansible `stackhpc.cephadm collection

doc/source/configuration/host-images.rst

@@ -0,0 +1,66 @@
+.. _host-images:
+
+===========
+Host Images
+===========
+
+StackHPC Kayobe configuration provides configuration for some standard
+overcloud host images, built using the :kayobe-doc:`overcloud DIB
+<configuration/reference/overcloud-dib.html>` functionality of Kayobe.
+
+The overcloud DIB configuration is provided in
+``etc/kayobe/stackhpc-overcloud-dib.yml``. It is not used by default, and must
+be actively opted into. This can be done as follows:
+
+.. code-block:: yaml
+   :caption: ``etc/kayobe/overcloud-dib.yml``
+
+   overcloud_dib_build_host_images: true
+
+   overcloud_dib_host_images:
+     - "{{ stackhpc_overcloud_dib_host_image }}"
+
+The image name is configured via ``stackhpc_overcloud_dib_name``, and is
+``deployment_image`` by default.
+
+The list of DIB elements is configured via ``stackhpc_overcloud_dib_elements``.
+The default value depends on the ``os_distribution`` variable. See the YAML
+file for details.
+
+The DIB environment variables are configured via
+``stackhpc_overcloud_dib_env_vars``. See the YAML file for details.
+
+A list of packages to install is configured via
+``stackhpc_overcloud_dib_packages``.
+
+By default, a UEFI-compatible image is built that uses separate LVM volumes for
+different mount points. This is done to pass Centre for Internet Security (CIS)
+partition benchmarks. The block device YAML configuration is configured via
+``stackhpc_overcloud_dib_block_device_config_uefi_lvm``.
+
+The 3 partitions are:
+
+* p0: EFI ESP bootloader
+* p1: EFI BSP
+* p2: LVM PV (``rootpv``)
+
+The LVM Logical Volumes are:
+
+============== ================== =========
+LV             Mount point        Size (GB)
+============== ================== =========
+``lv_root``    ``/``              5G
+``lv_tmp``     ``/tmp``           1G
+``lv_var``     ``/var``           1G
+``lv_var_tmp`` ``/var/tmp``       1G
+``lv_log``     ``/var/log``       1G
+``lv_audit``   ``/var/log/audit`` 128M
+``lv_home``    ``/home``          128M
+============== ================== =========
+
+A compatible LVM configuration is provided, and covered in :ref:`lvm`.
+The Logical Volumes in the image are defined with small sizes, with the
+intention that they will be grown after provisioning.
+
+For RedHat family distributions, Dracut modules are configured via
+``stackhpc_overcloud_dib_dracut_enabled_modules_default_config``.

doc/source/configuration/index.rst

@@ -10,5 +10,8 @@ the various features provided.
 
    walled-garden
    release-train
+   host-images
+   lvm
+   swap
    cephadm
    monitoring

doc/source/configuration/lvm.rst

@@ -0,0 +1,98 @@
+.. _lvm:
+
+===
+LVM
+===
+
+StackHPC Kayobe configuration provides Logical Volume Manager (LVM)
+configuration that is compatible with the included :ref:`host-images`
+configuration. The configuration uses the :kayobe-doc:`LVM
+<configuration/reference/hosts.html#lvm>` host configuration functionality of
+Kayobe.
+
+The LVM configuration is provided in
+``etc/kayobe/inventory/group_vars/all/stackhpc/lvm``. This allows configuration
+variables to be overridden on a per-group or per-host basis (which would not be
+possible for an "extra variable" in ``etc/kayobe/*.yml``). This configuration
+is not used by default, and must be actively opted into. This can be done as
+follows:
+
+.. code-block:: yaml
+
+   controller_lvm_groups:
+     - "{{ stackhpc_lvm_group_rootvg }}"
+
+This will configure the standard set of logical volumes for the ``rootvg``
+volume group on controller hosts.
+
+The disks in this volume group are configured via
+``stackhpc_lvm_group_rootvg_disks``, and by default this contains a single
+disk, matched by a partition label of ``root`` (as used in the standard
+:ref:`host-images`).
+
+The size of each LV is configurable via the following variables:
+
+.. code-block:: yaml
+
+   # StackHPC LVM lv_swap LV size.
+   stackhpc_lvm_lv_swap_size: 16g
+
+   # StackHPC LVM lv_root LV size.
+   stackhpc_lvm_lv_root_size: 50g
+
+   # StackHPC LVM lv_tmp LV size.
+   stackhpc_lvm_lv_tmp_size: 10g
+
+   # StackHPC LVM lv_var LV size.
+   stackhpc_lvm_lv_var_size: 20g
+
+   # StackHPC LVM lv_var_tmp LV size.
+   stackhpc_lvm_lv_var_tmp_size: 2g
+
+   # StackHPC LVM lv_log LV size.
+   stackhpc_lvm_lv_log_size: 20g
+
+   # StackHPC LVM lv_audit LV size.
+   stackhpc_lvm_lv_audit_size: 10g
+
+   # StackHPC LVM lv_home LV size.
+   stackhpc_lvm_lv_home_size: 10g
+
+Additional LVs may be configured via ``stackhpc_lvm_group_rootvg_lvs_extra``. A
+common requirement is to have ``/var/lib/docker/`` mounted on a separate LV,
+so this has been made convenient to achieve:
+
+.. code-block:: yaml
+
+   stackhpc_lvm_group_rootvg_lvs_extra:
+     - "{{ stackhpc_lvm_lv_docker }}"
+
+   # StackHPC LVM lv_docker LV size.
+   stackhpc_lvm_lv_docker_size: 100%FREE
+
+It may be desirable to use a lower percentage of the free space, in case
+another LV needs to be grown at a later date.
+
+Growroot playbook
+=================
+
+A ``growroot.yml`` custom playbook is provied that can be used to grow the
+partition and LVM Physical Volume (PV) of the root Volume Group (VG). This
+allows for expansion of Logical Volumes (LVs) in that VG.
+
+The following variables may be used to configure the playbook:
+
+``growroot_group``
+  Host pattern against which to target the playbook. Default is ``overcloud``.
+``growroot_vg``
+  Name of the VG containing the PV to grow. Default is ``rootvg`` to match the
+  standard :ref:`host image configuration <host-images>`.
+
+This playbook may be used as a host configure pre hook, e.g. for overcloud
+hosts:
+
+.. code-block:: console
+
+   mkdir -p ${KAYOBE_CONFIG_PATH}/hooks/overcloud-host-configure/pre.d
+   cd ${KAYOBE_CONFIG_PATH}/hooks/overcloud-host-configure/pre.d
+   ln -s ../../../ansible/growroot.yml 30-growroot.yml

doc/source/configuration/monitoring.rst

@@ -1,22 +1,49 @@
-===========
+==========
 Monitoring
-===========
+==========
 
 Monitoring Configuration
 ========================
 
-StackHPC kayobe config includes a reference monitoring stack based on
-Prometheus. Whilst this often works out of the box, there are some tunables
-which can be customised to adapt the configuration to a particular deployment.
+StackHPC kayobe config includes a reference monitoring and alerting stack based
+on Prometheus, Alertmanager, Grafana, Fluentd, Elasticsearch & Kibana. These
+services by default come enabled and configured. Central Elasticsearch cluster
+collects OpenStack logs, with an option to receive operating system logs too.
+In order to enable this, execute custom playbook after deployment:
+
+.. code-block:: console
+
+    cd $KAYOBE_CONFIG_PATH
+    kayobe playbook run ansible/rsyslog.yml
+
+`Prometheus <https://prometheus.io/>`__ comes with a comprehensive set of
+metrics gathered from enabled exporters; every exporter's data is visualised
+by at least one `Grafana <https://grafana.com>`__ dashboard. Standard set of
+alerting rules is present as well.
+
+While the default configuration often works out of the box, there
+are some tunables which can be customised to adapt the configuration to a
+particular deployment's needs.
 
 The configuration options can be found in
 ``etc/kayobe/stackhpc-monitoring.yml``:
 
 .. literalinclude:: ../../../etc/kayobe/stackhpc-monitoring.yml
    :language: yaml
 
+In order to enable stock monitoring configuration within a particular
+environment, create the following symbolic links:
+
+.. code-block:: console
+
+    cd $KAYOBE_CONFIG_PATH
+    ln -s kolla/config/grafana/ environments/$KAYOBE_ENVIRONMENT/kolla/config/
+    ln -s kolla/config/prometheus/ environments/$KAYOBE_ENVIRONMENT/kolla/config/
+
+and commit them to the config repository.
+
 SMART Drive Monitoring
-=======================
+======================
 
 StackHPC kayobe config also includes drive monitoring for spinning disks and
 NVME's.
@@ -27,7 +54,7 @@ a cronjob, to output the metrics and we use node exporter's Textfile collector
 to report the metrics output by the scripts to Prometheus. These metrics can
 then be visualised in Grafana with the bundled dashboard.
 
-After pulling in the latest changes into your local kayobe config, reconfigure 
+After pulling in the latest changes into your local kayobe config, reconfigure
 Prometheus and Grafana
 
 .. code-block:: console
@@ -38,7 +65,7 @@ Prometheus and Grafana
 `this <https://bugs.launchpad.net/kolla-ansible/+bug/1997984>`__ bug and at
 present, the workaround is to go into each node running Grafana and manually
 restart the process with ``docker restart grafana`` and then try the reconfigure
-command again.) 
+command again.)
 
 Once the reconfigure has completed you can now run the custom playbook which
 copies over the scripts and sets up the cron jobs to start SMART monitoring
@@ -50,6 +77,4 @@ on the overcloud hosts:
     (kayobe) [stack@node kayobe]$ kayobe playbook run ansible/smartmontools.yml
 
 SMART reporting should now be enabled along with a Prometheus alert for
-unhealthy disks and a Grafana dashboard called ``Hardware Overview``. 
-
-
+unhealthy disks and a Grafana dashboard called ``Hardware Overview``.