reference: snap lifecycle documentation

Signed-off-by: Andy Whitcroft <apw@canonical.com>

Author: Andy Whitcroft

docs/.custom_wordlist.txt

@@ -4,8 +4,10 @@ ACKs
 AppArmor
 backport
 backported
+bootable
 enablement
 gitea
+initramfs
 kconfig
 LEDs
 master
@@ -20,7 +22,9 @@ rebases
 respin
 respins
 selftests
+signoff
 subtree
 unported
+UKIs
 UKN
 ZFS

docs/reference/index.md

@@ -19,11 +19,12 @@ more.
 
 ```{toctree}
 :maxdepth: 1
-:caption: Kernel variants
+:caption: Kernel variants and snaps
 
 ubuntu-kernels
 hwe-kernels
 oem-kernels
+snap-lifecycle
 ```
 
 ```{toctree}

docs/reference/snap-lifecycle.rst

@@ -0,0 +1,139 @@
+**************
+Snap lifecycle
+**************
+
+This document aims to document the lifecycle of the various kernel snap forms.
+
+Snap builds
+===========
+
+The majority of kernels with snaps are consumed both as Debian packages and 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 is 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 lifecycle proceeding from the ``build`` location, to ``proposed``, and onward 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
+---------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Risk (channel)
+     - Purpose
+     - Build source
+
+   * - ``edge``
+     - Snaps are unsigned and intended for simple boot testing.
+     - Kernel snaps are built from Debian binaries in the ``build`` location.
+
+   * - ``beta``
+     - Snaps are signed and intended for certification testing.
+     - Kernel snaps are built from Debian binaries in the ``proposed`` location.
+
+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 (e.g. ``24``). 
+For interim Ubuntu releases these are the full release name (e.g. ``24.10``).
+
+Where a series has a :doc:`hardware enablement kernel <hwe-kernels>`, those are placed on the HWE specific tracks (e.g. ``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-core-initramfs`` is installed and invoked as part of the kernel :spellexception:`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 (UKIs).
+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 invoked as part of the kernel :spellexception:`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 :spellexception:`parameterizes` 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 candidate 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 may then promote further to ``security`` but there is no equivalent channel for snaps.