diff --git a/docs/reference/index.md b/docs/reference/index.md index 5edeb97..e3ad380 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -35,6 +35,13 @@ kernel-upload-rights dkms-upload-rights ``` +```{toctree} +:maxdepth: 2 +:caption: Snap Lifecycle + +snap-lifecycle +``` + ```{toctree} :maxdepth: 1 :caption: General diff --git a/docs/reference/snap-lifecycle.rst b/docs/reference/snap-lifecycle.rst new file mode 100644 index 0000000..27aa1e8 --- /dev/null +++ b/docs/reference/snap-lifecycle.rst @@ -0,0 +1,150 @@ +************** +Snap Lifecycle +************** + +Snap Build Lifecycle +==================== +This document aims to document the lifecycle of the various kernel snap +forms. + +Background +---------- +The majority of kernels with snaps are consumed both as Debian packages and +those snaps. To reduce testing requirements and streamline production the same +binaries are used for both forms. Due to the Ubuntu requirement for source to +be included with the binaries it is simplest to generate the binaries as part +of generating the Debian binary packages and repackage those into snaps where +needed. Where a kernel is to be signed this is performed during the packaging +process in those Debian package builds. + +Workflow Support +---------------- +Kernel snaps are represented as a separate phase in the kernel workflow. There +will be a Workflow Tracker for each Debian kernel build, and a separate +subordinate tracker for the snap kernel build. The snap tracker will have the +Debian trackers as its parent and will proceed once that Debian tracker is +complete. + +Debian Pocket Usage +------------------- +The Debian package builds flow through their own life-cycle proceeding from the +``build`` location, to ``proposed``, and onwards to ``updates`` and ``security`` as +testing allows. + +Kernels in the ``build`` location are unsigned and intended for simple boot +testing or for testing for signing compliance. Kernels in ``proposed`` are +signed (if applicable) and formal candidates for regression and certification +testing. + +Snap Risk Usage +--------------- +Snaps on the ``edge`` channel are unsigned and intended for simple boot testing. +Snaps on the ``beta`` channel are signed and intended for certification testing. +The ``edge`` kernels are built using the Debian binaries in the ``build`` +location. The ``beta`` kernels are built using the Debian binaries in the +``proposed`` locations. + +Track Usage +----------- +We make heavy use of store tracks to separate series specific snaps from each +other. For Ubuntu LTS releases which align with Ubuntu Core releases those +tracks are typically the Ubuntu Core release years (for example ``24``). For +interim Ubuntu releases these are the full release name (for example +``24.10``). + +Where a series has a hardware enablement kernel (:ref hwe-kernels) those are +placed on the HWE specific tracks (for example ``24-hwe``). + +Unsigned Kernels +---------------- +Unsigned kernels such as the ``pi-kernel`` will be directly generated in the +Debian ``main`` package. The ``linux-image`` packages are consumed and +``ubuntu-core-initramfs`` used to generate an initramfs to accompany it. These +are packaged up along with any required firmware. + +Signed Kernels +-------------- +Signed kernel such as the ``pc-kernel`` will be generated in the Debian +``main`` package, and passed through the signing pipeline as part of the Debian +``signed`` package. The ``linux-image`` packages (now generated by the +``signed`` package) are consumed and ``ubuntu-core-initramfs`` used to generate +an initramfs to accompany it. These are packaged up along with any required +firmware. ``ubuntu-cre-initramfs`` is installed and envoked as part of the +kernel postinst.d handling to convert the existing ``vmlinux-`` image +into a ``kernel.efi-`` image. + +Kernel UKIs +----------- +For kernels use cases which require measurement we also produce Unified Kernel +Images. That is a bootable PE executable which contains the kernel binary, an +initramfs, and the kernel command line. This UKI is generated in the +``linux-signed`` package through use of an additional mode of the +``ubuntu-core-initramfs`` tooling. This process produces a single binary and +is signed after it is combined via the signing pipeline. + +Stubble Kernels +--------------- +On arm64 we have an additional problem. For a number of platforms the ``dtb`` +is not correctly supplied by the firmware. To handle these cases a ``stubble`` +wrapper is used to detect those platforms and to inject the appropriate ``dtb`` +as appropriate, then handing off control to the wrapped kernel image. The +kernel image is taken from the Debian ``linux-image`` package in the normal +way. The ``stubble-kernel`` package is installed and envoked as part of the +kernel postinst.d handling to convert the existing ``vmlinuz-`` image +into a ``stubble.efi-`` image. + +Snap Workflow Lifecycle +======================= +The snap workflow lifecycle runs in parallel to and interlocked with the Debian +Workflow lifecycle. This ensures that the snap workflow waits for the +prerequisite binaries. It also ensures that testing of both Debian packages +and snap must be complete before they can progress further. Finally ensuring +that the Debian packages and Snaps release together. + +Unsigned Build +-------------- +When a Debian kernel build completes in the ``build`` location the ``edge`` +build of the Snap is triggered. This causes an auto-crank of the snap which +parameterises the snapcraft.yaml configuration, and kicks off builds against +the appropriate snap build recipe. This causes the kernel to be processed into +a snap and uploaded to the snap-store. The store will automatically publish this +onto the ``edge`` channel for testing. + +Early Testing +------------- +Once published we trigger any available early testing. This includes ``boot-testing``, +``abi-testing`` and ``signing-signoff``. Once each of these is successfully completed +the Debian package may progress into the signing pipeline and on into its ``proposed`` location. + +Proposed Build +-------------- +Once the Debian kernel is in its ``proposed`` location a second auto-crank is +triggered to process the kernel into a snap via a second snap recipe. This +causes the kernel to be uploaded to the ``beta`` channel ready for wider formal +testing. + +For signed kernels this ensures the snap on the ``beta`` channel has a signed +payload. We also regenerate the snap for unsigned kernel, while this may seem +redundant it allows us to perform experimental builds only to ``edge`` without +disrupting the workflow once the build has progressed to ``beta``. + +Testing +------- +Once we have a snap on the ``beta`` channel formal testing is triggered. This +includes ``certification-testing`` for the snap. Once this testing is complete +the snap will be promoted to the ``candidate`` channel. + +QA Testing +---------- +Once we have a formal canidate snap this may be sent for further acceptance +testing in QA. Testing for the Debian package and snap are combined and gate +the further promotion of both. Promotion is further gated by any applicable +signoff tasks. + +Release +------- +Once all gating factors, testing, signoff, and cycle boundaries are satisfied +the snap will be promoted to the ``stable`` channel, this occurs in lock-step +with the promotion of the Debian package to ``updates``. The Debian package my +then promote further to ``security`` but there is no equivalent channel for +snaps.