reference: snap lifecycle documentation

Signed-off-by: Andy Whitcroft <[email protected]>

Author: Andy Whitcroft

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

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-<verflav>`` image
+into a ``kernel.efi-<verflav>`` 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-<verflav>`` image
+into a ``stubble.efi-<verflav>`` 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.