Skip to content

Commit 4c0ce31

Browse files
author
Andy Whitcroft
committed
reference: snap lifecycle documentation
Signed-off-by: Andy Whitcroft <[email protected]>
1 parent 16a8b54 commit 4c0ce31

File tree

2 files changed

+153
-0
lines changed

2 files changed

+153
-0
lines changed

‎docs/reference/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,13 @@ kernel-upload-rights
3535
dkms-upload-rights
3636
```
3737

38+
```{toctree}
39+
:maxdepth: 2
40+
:caption: Snap Lifecycle
41+
42+
snap-lifecycle
43+
```
44+
3845
```{toctree}
3946
:maxdepth: 1
4047
:caption: General

‎docs/reference/snap-lifecycle.rst‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
**************
2+
Snap Lifecycle
3+
**************
4+
5+
Snap Build Lifecycle
6+
====================
7+
This document aims to document the lifecycle of the various kernel snap
8+
forms.
9+
10+
Background
11+
----------
12+
The majority of kernels with snaps are consumed both as Debian packages and
13+
those snaps. To reduce testing requirements and streamline production the same
14+
binaries are used for both forms. Due to the Ubuntu requirement for source to
15+
be included with the binaries it is simplest to generate the binaries as part
16+
of generating the Debian binary packages and repackage those into snaps where
17+
needed. Where a kernel is to be signed this is performed during the packaging
18+
process in those Debian package builds.
19+
20+
Workflow Support
21+
----------------
22+
Kernel snaps are represented as a separate phase in the kernel workflow. There
23+
will be a Workflow Tracker for each Debian kernel build, and a separate
24+
subordinate tracker for the snap kernel build. The snap tracker will have the
25+
Debian trackers as its parent and will proceed once that Debian tracker is
26+
complete.
27+
28+
Debian Pocket Usage
29+
-------------------
30+
The Debian package builds flow through their own life-cycle proceeding from the
31+
``build`` location, to ``proposed``, and onwards to ``updates`` and ``security`` as
32+
testing allows.
33+
34+
Kernels in the ``build`` location are unsigned and intended for simple boot
35+
testing or for testing for signing compliance. Kernels in ``proposed`` are
36+
signed (if applicable) and formal candidates for regression and certification
37+
testing.
38+
39+
Snap Risk Usage
40+
---------------
41+
Snaps on the ``edge`` channel are unsigned and intended for simple boot testing.
42+
Snaps on the ``beta`` channel are signed and intended for certification testing.
43+
The ``edge`` kernels are built using the Debian binaries in the ``build``
44+
location. The ``beta`` kernels are built using the Debian binaries in the
45+
``proposed`` locations.
46+
47+
Track Usage
48+
-----------
49+
We make heavy use of store tracks to separate series specific snaps from each
50+
other. For Ubuntu LTS releases which align with Ubuntu Core releases those
51+
tracks are typically the Ubuntu Core release years (for example ``24``). For
52+
interim Ubuntu releases these are the full release name (for example
53+
``24.10``).
54+
55+
Where a series has a hardware enablement kernel (:ref hwe-kernels) those are
56+
placed on the HWE specific tracks (for example ``24-hwe``).
57+
58+
Unsigned Kernels
59+
----------------
60+
Unsigned kernels such as the ``pi-kernel`` will be directly generated in the
61+
Debian ``main`` package. The ``linux-image`` packages are consumed and
62+
``ubuntu-core-initramfs`` used to generate an initramfs to accompany it. These
63+
are packaged up along with any required firmware.
64+
65+
Signed Kernels
66+
--------------
67+
Signed kernel such as the ``pc-kernel`` will be generated in the Debian
68+
``main`` package, and passed through the signing pipeline as part of the Debian
69+
``signed`` package. The ``linux-image`` packages (now generated by the
70+
``signed`` package) are consumed and ``ubuntu-core-initramfs`` used to generate
71+
an initramfs to accompany it. These are packaged up along with any required
72+
firmware.
73+
74+
Kernel UKIs
75+
-----------
76+
For kernels use cases which require measurement we also produce Unified Kernel
77+
Images. That is a bootable PE executable which contains the kernel binary, an
78+
initramfs, and the kernel command line. This UKI is generated in the
79+
``linux-signed`` package through use of an additional mode of the
80+
``ubuntu-core-initramfs`` tooling. This process produces a single binary and
81+
is signed after it is combined via the signing pipeline.
82+
83+
Stubble Kernels
84+
---------------
85+
On arm64 we have an additional problem. For a number of platforms the ``dtb``
86+
is not correctly supplied by the firmware. To handle these cases a ``stubble``
87+
wrapper is used to detect those platforms and to inject the appropriate ``dtb``
88+
as appropriate, then handing off control to the wrapped kernel image. The
89+
kernel image is taken from the Debian ``linux-image`` package in the normal
90+
way.
91+
92+
Snap Workflow Lifecycle
93+
=======================
94+
The snap workflow lifecycle runs in parallel to and interlocked with the Debian
95+
Workflow lifecycle. This ensures that the snap workflow waits for the
96+
prerequisite binaries. It also ensures that testing of both Debian packages
97+
and snap must be complete before they can progress further. Finally ensuring
98+
that the Debian packages and Snaps release together.
99+
100+
Unsigned Build
101+
--------------
102+
When a Debian kernel build completes in the ``build`` location the ``edge``
103+
build of the Snap is triggered. This causes an auto-crank of the snap which
104+
parameterises the snapcraft.yaml configuration, and kicks off builds against
105+
the appropriate snap build recipe. This causes the kernel to be processed into
106+
a snap and uploaded to the snap-store. The store will automatically publish this
107+
onto the ``edge`` channel for testing.
108+
109+
Early Testing
110+
-------------
111+
Once published we trigger any available early testing. This includes ``boot-testing``,
112+
``abi-testing`` and ``signing-signoff``. Once each of these is successfully completed
113+
the Debian package may progress into the signing pipeline and on into its ``proposed`` location.
114+
115+
Proposed Build
116+
--------------
117+
Once the Debian kernel is in its ``proposed`` location a second auto-crank is
118+
triggered to process the kernel into a snap via a second snap recipe. This
119+
causes the kernel to be uploaded to the ``beta`` channel ready for wider formal
120+
testing.
121+
122+
For signed kernels this ensures the snap on the ``beta`` channel has a signed
123+
payload. We also regenerate the snap for unsigned kernel, while this may seem
124+
redundant it allows us to perform experimental builds only to ``edge`` without
125+
disrupting the workflow once the build has progressed to ``beta``.
126+
127+
Testing
128+
-------
129+
Once we have a snap on the ``beta`` channel formal testing is triggered. This
130+
includes ``certification-testing`` for the snap. Once this testing is complete
131+
the snap will be promoted to the ``candidate`` channel.
132+
133+
QA Testing
134+
----------
135+
Once we have a formal canidate snap this may be sent for further acceptance
136+
testing in QA. Testing for the Debian package and snap are combined and gate
137+
the further promotion of both. Promotion is further gated by any applicable
138+
signoff tasks.
139+
140+
Release
141+
-------
142+
Once all gating factors, testing, signoff, and cycle boundaries are satisfied
143+
the snap will be promoted to the ``stable`` channel, this occurs in lock-step
144+
with the promotion of the Debian package to ``updates``. The Debian package my
145+
then promote further to ``security`` but there is no equivalent channel for
146+
snaps.

0 commit comments

Comments
 (0)