From 3e32fa1837614e0e76208ed320edbdd2bee9e99c Mon Sep 17 00:00:00 2001 From: Nicolas Harnois Date: Mon, 25 Aug 2025 09:46:57 +0200 Subject: [PATCH 1/4] Improve documentation related to the remodelling process. Signed-off-by: Nicolas Harnois --- .../core-elements/snaps-in-ubuntu-core.md | 2 +- docs/explanation/remodelling.md | 30 +++++++++++++++++-- .../create-a-recovery-system-from-the-api.md | 2 +- docs/reference/gadget-snap-format.md | 2 +- docs/reference/release-notes.md | 28 +++++++++++++++-- 5 files changed, 55 insertions(+), 9 deletions(-) diff --git a/docs/explanation/core-elements/snaps-in-ubuntu-core.md b/docs/explanation/core-elements/snaps-in-ubuntu-core.md index 2e14db78..74fd4702 100644 --- a/docs/explanation/core-elements/snaps-in-ubuntu-core.md +++ b/docs/explanation/core-elements/snaps-in-ubuntu-core.md @@ -28,7 +28,7 @@ The snap packaging ecosystem consists of the following parts: Developers can publish snaps to the Snap Store or to their own private Brand Store. They take sole responsibility for update cadence and quality. While snaps are commonly known as an application packaging format, Ubuntu Core is built from several different types of snap: 1. **kernel**: Contains the Linux kernel for a device
-The [kernel snap](https://snapcraft.io/docs/kernel-snap) is selected with the [model assertion](/reference/assertions/model) describing the device which is produced and signed before the image is built. Once the image is built, the kernel snap may be updated but cannot be replaced by a completely different kernel snap. +The [kernel snap](https://snapcraft.io/docs/kernel-snap) is selected with the [model assertion](/reference/assertions/model) describing the device which is produced and signed before the image is built. Once the image is built, the kernel snap may be updated but cannot be replaced by a completely different kernel snap, unless a [Ubuntu Core upgrade](/how-to-guides/manage-ubuntu-core/upgrade-ubuntu-core) is performed. 1. **gadget**: Defines device properties
The [gadget snap](/reference/gadget-snap-format) is responsible for defining and manipulating the system properties and configuration which are specific to one or more devices that will usually look similar to one another from an implementation perspective. It is also responsible for shipping the device bootloader and bootloader assets. It is selected with the [model assertion](/reference/assertions/model). 1. **base**: The runtime environment
diff --git a/docs/explanation/remodelling.md b/docs/explanation/remodelling.md index 34434231..1236371e 100644 --- a/docs/explanation/remodelling.md +++ b/docs/explanation/remodelling.md @@ -8,14 +8,16 @@ The model assertion contains: * Identification information, such as brand account id and model name. * Which essential snaps make up the device system, including the gadget snap, kernel snap and the boot base snap with the root filesystem. * Other required or optional snaps that implement the device functionality. -* Additional options for the defined device, such as grade. +* Additional options for the defined device, such as grade, and the store it is connected to. -When one or more of the above elements change, the updated model assertion and its associated image are deployed to the device, authenticated and linked through its serial assertion, to the store. This process is called remodelling. +The essential snaps can be refreshed during the device lifecycle to provide minor updates. However, when these snaps must be upgraded, or when one or more of the above elements change, a new model assertion can be deployed to the device. The updated model assertion is authenticated and linked through its serial assertion to the store. The image is upgraded based on the delta compared to the previous model. This process is called remodelling. + +The updated model must be signed with the same key as the original model, and its `revision` field must be incremented. See [model assertion](/reference/assertions/model) for further details. One example of remodelling is [Upgrading Ubuntu Core](/how-to-guides/manage-ubuntu-core/upgrade-ubuntu-core.md). ## Remodelling viability -The remodelling process is triggered by either updating the model assertion, running the `snap remodel` command, or from the [snapd the REST API](https://snapcraft.io/docs/snapd-api) (the last two require _snapd 2.61_ or later). Remodelling triggers the generation of a new recovery system, which means care needs to be taken to ensure the [ubuntu-seed](/explanation/core-elements/storage-layout.md#the-ubuntu-seed-partition) partition is sized accordingly. +The remodelling process is triggered by either updating the model assertion, running the `snap remodel` command, or from the [snapd the REST API](https://snapcraft.io/docs/snapd-api) (the last two require _snapd 2.61_ or later). Remodelling triggers the generation of a new recovery system, which means care needs to be taken to ensure the [ubuntu-seed](/explanation/core-elements/storage-layout.md#the-ubuntu-seed-partition) partition is sized accordingly. The process also ensures the newly created recovery system is valid. Therefore, the previous recovery system can be safely removed after remodelling has completed. An [API call](/how-to-guides/manage-ubuntu-core/create-a-recovery-system-from-the-api) is available to perform this removal. Remodelling is the responsibility of the snap daemon (_snapd_) running on the device. It both mediates the update process and the re-registration of the device after the update (if required). But the complexity and viability of the remodelling process is dependent on several factors outside of snapd’s control. @@ -42,6 +44,28 @@ The below permutations of the remodelling contexts are all valid: If a [validation set](https://snapcraft.io/docs/validation-sets) has been defined for the old model and the new model, or just the new model, the snaps installed during the remodelling process must follow the validation set rules. +To ensure the remodelling process completes successfully when a device's model name changes, a specific configuration is required in the [Serial Vault](https://canonical-serial-vault.readthedocs-hosted.com/serial-vault/register-a-new-device-model-name/), under the `Sub-Store Models` tab, to specify the allowed migration path from the old to new model name. + +### Gadget snap + +In the new model definition, the gadget snap can be kept identical to the previous model, or modified with any combination of the following items: + +* modification of the gadget snap name and associated ID +* modification of the channel + +If the gadget snap is modified, the new gadget snap base must be aligned with the base defined in the updated [model assertion](/reference/assertions/model). +If the default settings defined in the gadget are updated, they won't be applied when the remodelling process is performed. See [gadget snap](/reference/gadget-snap-format) for further information. + +### Kernel snap + +The kernel snap can also be kept as-is, or modified with any combination of the following items: + +* modification of the kernel snap name and associated ID +* modification of the channel + +The build-base of the new kernel snap should be aligned with the base defined in the updated [model assertion](/reference/assertions/model). +Ubuntu Core only supports kernel snaps built from LTS releases. Refer to [Release Notes](/reference/release-notes) for details on Ubuntu Core versioning. + ## Snap removal The remodelling process does not automatically remove snaps which are no longer marked as `required` or `optional` in the new model assertion. Those snaps stay in the system and keep receiving updates, but since they are no longer required by the model, it is possible to remove them. diff --git a/docs/how-to-guides/manage-ubuntu-core/create-a-recovery-system-from-the-api.md b/docs/how-to-guides/manage-ubuntu-core/create-a-recovery-system-from-the-api.md index a43c5d02..fbdc6f2e 100644 --- a/docs/how-to-guides/manage-ubuntu-core/create-a-recovery-system-from-the-api.md +++ b/docs/how-to-guides/manage-ubuntu-core/create-a-recovery-system-from-the-api.md @@ -79,7 +79,7 @@ In this example, “validation-set.assert”, “pc.assert”, “pc-kernel.asse Recovery systems can be removed by using the remove API. Note that the “current” system, the default recovery system, and the last recovery system cannot be removed. -Example POST to /v2/system/