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.