From f44644f20f3e4619f72ddead2ef3cc52e24ab810 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Tue, 10 Jan 2017 15:50:21 +1100 Subject: [PATCH] Update platform support to describe stable testing The reality is that "stable" is what is tested. This tries to give enough info that users can ascertain what tests are running at any given time and hence what elements are known to be working. Additional, clarify the Fedora position in the README as now described by above. Closes: #1653561 Change-Id: Ifb91b9089790897861bd7e671c3dba59adac239d --- .../elements/fedora-minimal/README.rst | 7 + diskimage_builder/elements/fedora/README.rst | 10 ++ doc/source/user_guide/supported_distros.rst | 136 +++++++++++++++--- 3 files changed, 135 insertions(+), 18 deletions(-) diff --git a/diskimage_builder/elements/fedora-minimal/README.rst b/diskimage_builder/elements/fedora-minimal/README.rst index 530328f2..72624b9f 100644 --- a/diskimage_builder/elements/fedora-minimal/README.rst +++ b/diskimage_builder/elements/fedora-minimal/README.rst @@ -1,6 +1,13 @@ ============== fedora-minimal ============== + +*Note* as at February 2022, this element is no longer tested or used +by OpenDev. Changes to the RPM format used by recent Fedora releases +have meant that this element can not build on Ubuntu hosts, which lack +a packaged RPM sufficient to extract the base chroot environment. The +``fedora-containerfile`` element can be used instead of this element. + Create a minimal image based on Fedora. Use of this element will require 'yum' and 'yum-utils' to be installed on diff --git a/diskimage_builder/elements/fedora/README.rst b/diskimage_builder/elements/fedora/README.rst index 6bb7c290..689c35ba 100644 --- a/diskimage_builder/elements/fedora/README.rst +++ b/diskimage_builder/elements/fedora/README.rst @@ -5,6 +5,16 @@ fedora Use Fedora cloud images as the baseline for built disk images. For further details see the redhat-common README. +Releases +-------- + +This element targets the current and previous version of Fedora; these +values clearly changes over time. To fix the version set the +`DIB_RELEASE` variable to the Fedora version (e.g. ``35``). The +default value is the current best supported version (i.e. it may +change upward at any given release to support the next Fedora). + + Environment Variables --------------------- diff --git a/doc/source/user_guide/supported_distros.rst b/doc/source/user_guide/supported_distros.rst index 5345e68d..c50878c9 100644 --- a/doc/source/user_guide/supported_distros.rst +++ b/doc/source/user_guide/supported_distros.rst @@ -1,23 +1,123 @@ -Supported Distributions -======================= +Tested Distributions +-------------------- -Distributions which are supported as a build host: +``diskimage-builder`` can create many different types of targets +composed of many different elements. For any release, the project +considers the elements tested by the OpenDev gate +continuous-integration jobs as stable. -- Centos 6, 7 -- Debian 8 ("jessie") -- Fedora 30, 31 -- RHEL 6, 7 -- Gentoo -- openSUSE Leap 42.3, 15.0, 15.1 and Tumbleweed +Practically, this means a change can not commit unless it has +successfully built the elements described below under test. +Build Host +========== -Distributions which are supported as a target for an image: +The build-host is the platform used to create images. Unfortunately +there is no concise answer as to the support status of all possible +build-hosts. ``diskimage-builder`` has a complex relationship with +the build-host depending on which target elements are being built. -- Centos 6, 7 -- Debian 8 ("jessie") -- Fedora 31, 32 -- RHEL 6, 7 -- 16.04 ("xenial"), 18.04 ("bionic") -- Gentoo -- openEuler 20.03-LTS-SP1+ -- openSUSE Leap 15.3 and Tumbleweed (opensuse-minimal only) +Image-based elements take an upstream ``.qcow2`` image, extract and +customise it. Since ``diskimage-builder`` chroots into an +already-complete environment, these elements generally work on any +build-host, but there are complexities; for example some images ship +an XFS-filesystem with options that some stable-distribution +build-hosts can not read (and hence the build-host can not mount and +extract the image). + +As another example, the ``-minimal`` elements run tools such as +``yum``, ``dnf``, ``apt`` on the build-host to create an initial +``chroot`` environment. Thus some combinations will not work; for +example ``fedora-minimal`` for the latest versions may require a RPM +that is not packaged on current stable versions of Ubuntu. Some +versions of Ubuntu ship a ``debootstrap`` that has bugs preventing +building other distributions, etc. + +Finally the ``containerfile`` elements use ``podman`` to extract a +container-image and then customise that. Distributions vary in their +podman version and various bugs related to this. + +The images used by the OpenDev's `Zuul `__ system +are built by `Nodepool `__. Thus +the simplest way to have the most supported build-host environment is +to use ``diskimage-buidler`` installed in the `nodepool-builder +container image `__. +You can run ``disk-image-create`` directly from this container, e.g. + +:: + + docker run --rm --privileged --network host \ + --env DIB_SHOW_IMAGE_USAGE=1 \ + --env TMPDIR=/opt/dib_tmp \ + -v nested_var_lib_containers:/var/lib/containers \ + -v /var/run/dib_output:/var/run/dib_output \ + -v /opt/dib_tmp:/opt/dib_tmp \ + zuul/nodepool-builder disk-image-create -x -t qcow2 \ + --no-tmpfs \ + -o /var/run/dib_output/image -n + +The platform this container image is built upon is by extension the +most-supported build host. Inspecting the `Dockerfile +`__ is +a good way to start building customised build-host environments. This +is currently based on Debian Bullsye. + +Other distributions are not tested as build-hosts in the +``diskimage-builder`` gate. + +Testing and Targets +=================== + +The stable targets are those that are tested; as noted no change can +commit which would break this testing. + +There are two main testing paths: + +* end-to-end tests build an image, import it to an OpenStack + environment, boot it and confirm basic operation. These tests use + the ``nodepool-builder`` container environment to build the image to + be tested. +* functional tests build a complete output image. They do not perform + boot tests. These tests run on Debian Bullseye. + +The canonical list of tests and the elements they build for any releae +is kept in `.zuul.yaml/jobs.yaml +`__. +If this document differs to the defined tests, the Zuul configuration +is correct. + +As of Feburary 2022, the default end-to-end testing covers the +following elements on x86-64 + +* ``centos-minimal``: CentOS 7, 8-stream and 9-stream +* ``fedora-containerfile``: the latest Fedora. +* ``ubuntu-minimal``: Ubuntu Xenial, Bionic and Focal +* ``opensuse-minimal``: Leap 15.3 and Tumbleweed (non-voting) +* ``gentoo``: (non-voting) +* ``debian-minimal``: Bullseye +* ``rocky-container``: Rocky Linux 8 + +We run functional (build-only) tests on the following elements and +versions: + +* ``containerfile``: Ubuntu Focal +* ``openeuler-minimal``: 20.03-LTS-SP2 +* ``centos`` : (image-based build) 8-stream and 9-stream +* ``fedora`` : (image-based build) latest +* ``opensuse`` : 15.3 +* ``ubuntu`` : Bionic and Focal + +For ARM64, we also run functional tests on + +* ``ubuntu-minimal`` : Bionic and Focal +* ``debian-minimal`` : Bullseye +* ``centos-minimal`` : 8-stream and 9-stream +* ``openeuler-minimal``: 20.03-LTS-SP2 + +For additional details, see the ``README`` file of the relevant +elements. + +``diskimage-builder`` is used in a range of other projects that do +their own testing, separate to the ``diskimage-buidler`` CI gate +testing. These have different combinations of host/target elements +they keep stable. Updates to this document are welcome.