Update release train documentation

Updated the documentation for release train, in particular adding
information on how to use the host images in Ark, and updating the
details surrounding Ubuntu packages.

Author: Alex-Welsh

doc/source/configuration/host-images.rst

@@ -4,6 +4,44 @@
 Host Images
 ===========
 
+Pulling host images
+===================
+
+StackHPC provides pre-built overcloud host images through Ark, which can be
+consumed using the configuration provided by this repository.
+
+When configured, an image will be downloaded to the seed during the
+``kayobe seed service deploy`` step, and subsequently deployed using bifrost
+with ``kayobe overcloud provision``.
+
+To use these images, set ``stackhpc_download_overcloud_host_images`` to true
+in ``etc/kayobe/stackhpc-overcloud-host-images.yml``.
+
+Currently, images exist for the following operating systems:
+
+* CentOS 8 Stream
+* Rocky Linux 8
+* Rocky Linux 9
+* Ubuntu Focal 20.04
+* Ubuntu Jammy 22.04
+
+The image to download is selected automatically using the ``os_distribution``
+and ``os_release`` variables.
+
+This content requires the same set of credentials as is used for other
+release train content.
+
+The Ark pulp credentials issued by StackHPC should be configured in
+``etc/kayobe/pulp.yml``, using Ansible Vault to encrypt the password:
+
+.. code-block:: yaml
+
+   stackhpc_release_pulp_username: <username>
+   stackhpc_release_pulp_password: <password>
+
+Building 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.

doc/source/configuration/release-train.rst

@@ -2,9 +2,9 @@
 StackHPC Release Train
 ======================
 
-StackHPC provides packages and container images for OpenStack via `Ark
-<https://ark.stackhpc.com>`__. These artifacts are built and released using a
-process known as the `Release Train
+StackHPC provides packages, container images, and host images for OpenStack via
+`Ark <https://ark.stackhpc.com>`__. These artifacts are built and released using
+a process known as the `Release Train
 <https://stackhpc.github.io/stackhpc-release-train/>`__.
 
 Deployments should use a local `Pulp <https://pulpproject.org/>`__ repository
@@ -37,10 +37,12 @@ Configuration
 This configuration provides the following:
 
 * Configuration to deploy a local Pulp service as a container on the seed
-* Pulp repository definitions for CentOS Stream 8 and Rocky Linux 8
+* Pulp repository definitions for CentOS Stream 8, Rocky Linux 8/9 and Ubuntu
+  Jammy
 * Playbooks to synchronise a local Pulp service with Ark
 * Configuration to use the local Pulp repository mirrors on control plane hosts
 * Configuration to use the local Pulp container registry on control plane hosts
+* Configuration to deploy pre-built OS images to overcloud hosts using Bifrost
 
 Local Pulp server
 -----------------
@@ -60,6 +62,10 @@ Pulp startup.
 If a proxy is required to access the Internet from the seed, ``pulp_proxy_url``
 may be used.
 
+Host images are not synchronised to the local Pulp server, since they should
+only be pulled to the seed node once. More information on host images can be
+found :ref:`here <host-images>`.
+
 StackHPC Ark
 ------------
 
@@ -74,12 +80,12 @@ The Ark pulp credentials issued by StackHPC should be configured in
 Package repositories
 --------------------
 
-Currently, Ark does not provide package repositories for Ubuntu - only
-container images. For this reason, ``stackhpc_pulp_sync_ubuntu_focal`` in
-``etc/kayobe/pulp.yml`` is set to ``false`` by default.
+Currently, Ark does not provide package repositories for Ubuntu Jammy 22.04 -
+only container images.
 
-CentOS Stream 8 and Rocky Linux 8/9 package repositories are synced based on the
-value of ``os_distribution``. If you need to sync multiple distributions,
+CentOS Stream 8, Rocky Linux 8/9, and Ubuntu Focal package repositories are
+synced based on the value of ``os_distribution`` and ``os_release`` . If you
+need to sync multiple RHEL-like distributions,
 ``stackhpc_pulp_sync_centos_stream8``, ``stackhpc_pulp_sync_rocky_8`` and
 ``stackhpc_pulp_sync_rocky_9`` in ``etc/kayobe/pulp.yml`` may be set to
 ``true``.
@@ -93,8 +99,15 @@ repository.
 Package managers
 ----------------
 
-No configuration is provided for APT, since Ark does not currently provide
-package repositories for Ubuntu - only container images.
+For Ubuntu Focal systems, the package manager configuration is provided by
+``stackhpc_apt_repositories`` in ``etc/kayobe/apt.yml``.
+
+The configuration is applied by default to all Ubuntu Focal hosts. The
+configuration can be overridden by changing the repository definitions in
+``apt_repositories`` or toggling ``apt_disable_sources_list`` to use the default
+apt repositories. This can be done on a host-by host basis by defining the
+variables as host or group vars under ``etc/kayobe/inventory/host_vars`` or
+``etc/kayobe/inventory/group_vars``.
 
 For CentOS and Rocky Linux based systems, package manager configuration is
 provided by ``stackhpc_dnf_repos`` in ``etc/kayobe/dnf.yml``, which points to
@@ -105,6 +118,9 @@ package repositories on the local Pulp server. To use this configuration, the
 configuration may be added for other groups, however there may be ordering
 issues during initial deployment when Pulp has not yet been deployed.
 
+In both instances, the configuration points to package repositories on the
+local Pulp server.
+
 The distribution name for the environment should be configured as either
 ``development`` or ``production`` via ``stackhpc_repo_distribution`` in
 ``etc/kayobe/stackhpc.yml``.
@@ -156,7 +172,7 @@ See the Kayobe :kayobe-doc:`custom playbook documentation
   these are new container image repositories, then the new image tags will not
   be available to cloud nodes until they have been published.
 * ``pulp-container-publish.yml``: Publish synchronised container images in the
-  local Pulp. This will make synchonised container images available to cloud
+  local Pulp. This will make synchronised container images available to cloud
   nodes.
 
 Syncing content
@@ -274,4 +290,4 @@ you will see a 404 error during ``pulp-repo-sync.yml``:
       msg: Task failed to complete. (failed; 404, message='Not Found', url=URL('https://ark.stackhpc.com/pulp/content/centos/8-stream/BaseOS/x86_64/os/20211122T102435')) '''
 
 The issue can be rectified by updating the ``stackhpc_release_pulp_username``
-and ``stackhpc_release_pulp_password`` variables
+and ``stackhpc_release_pulp_password`` variables.