Development
This document serves the purpose of gathering all the useful information regarding the construction of and development of the ubuntu-core flavor.
Overview
Every ubuntu-core image is composed of a defined set of snaps. The following section gives a quick overview of what each snap is about and includes a handy list of links for the given project.
New images are composed using the ubuntu-image tool and so called model assertions. In our case, model assertions tell ubuntu-image what to compose the created image of. It is the model that defines the base snap to use, the gadget and kernel. There are different model assertions for 16 and 18, for each supported platform.
The base (core) snap
This is the base filesystem with all the bare-essential libraries and tools for any system to work. Like the core snap, this is required to be present on any 18 core-enabled system. Basically it has to offer any crucial functionality that is needed for a minimal system to function and cannot be easily installed through separate snaps.
- Owner: Foundations Team
core20 for core series 20
LP project: https://code.launchpad.net/snap-core20
Code repository: https://github.com/snapcore/core20
Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core20
core18 for core series 18
LP project: https://code.launchpad.net/snap-core18
Code repository: https://github.com/snapcore/core18
Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core18
core16 for core series 16
LP project: https://code.launchpad.net/snap-core16
Code repository: https://github.com/snapcore/core16
Snap recipe: https://code.launchpad.net/~ubuntu-core-service/+snap/core16
The gadget snap
Each supported device has its own gadget snap. Gadget snaps are what defines the device, carrying binaries for the bootloader, declaring the partition layout etc. It is important to keep in mind that the gadget code repositories are also used by classic Ubuntu preinstalled images, although currently separate branches are used.
- Owner: Foundations Team
pi - universal gadget snap for all supported Raspberry Pi devices (pi2, pi3, pi4, cm3, cm4)
LP project: https://code.launchpad.net/snap-pi
Snap UC20 recipe (armhf): https://code.launchpad.net/~canonical-foundations/+snap/pi-armhf-20
Snap UC20 recipe (arm64): https://code.launchpad.net/~canonical-foundations/+snap/pi-arm64-20
Snap UC18 recipe (armhf): https://code.launchpad.net/~canonical-foundations/+snap/pi
Snap UC18 recipe (arm64): https://code.launchpad.net/~canonical-foundations/+snap/pi-arm64
Core 20 branch (armhf): https://github.com/snapcore/pi-gadget -b 20-armhf
Core 20 branch (arm64): https://github.com/snapcore/pi-gadget -b 20-arm64
Core 18 branch (armhf): https://github.com/snapcore/pi-gadget -b 18-armhf
Core 18 branch (arm64): https://github.com/snapcore/pi-gadget -b 18-arm64
dragonboard - the Dragonboard device
LP project: https://code.launchpad.net/snap-dragonboard
Snap recipe 18: https://code.launchpad.net/~canonical-foundations/+snap/dragonboard-18
Snap recipe 16: https://code.launchpad.net/~canonical-foundations/+snap/dragonboard
Core 18 branch: https://github.com/snapcore/dragonboard-gadget -b 18
Core 16 branch: https://github.com/snapcore/dragonboard-gadget -b 16
pc - gadget snap for amd64 and i386 devices
LP project: https://code.launchpad.net/snap-pc
Snap recipe 20 (amd64): https://code.launchpad.net/~canonical-foundations/+snap/pc-amd64-20
Snap recipe 18 (amd64): https://code.launchpad.net/~canonical-foundations/+snap/pc-amd64-18
Snap recipe 18 (i386): https://code.launchpad.net/~canonical-foundations/+snap/pc-i386-18
Snap recipe 16 (amd64): https://code.launchpad.net/~canonical-foundations/+snap/pc-amd64-16
Snap recipe 16 (i386): https://code.launchpad.net/~canonical-foundations/+snap/pc-i386-16
Core 20 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 20
Core 18 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 18
Core 18 branch (i386): https://github.com/snapcore/pc-i386-gadget -b 18
Core 16 branch (amd64): https://github.com/snapcore/pc-amd64-gadget -b 16
Core 16 branch (i386): https://github.com/snapcore/pc-i386-gadget -b 16
There following gadget snaps are only used for the 16 series. Even though some of those repositories have 18 branches and/or include some snaps in the 18 track, they do not participate in any of the core18 images and should only be used for core16 (core):
LP project: https://code.launchpad.net/snap-pi2
Core 16 branch: https://github.com/snapcore/pi2-gadget -b master
LP project: https://code.launchpad.net/snap-pi3
Core 16 branch: https://github.com/snapcore/pi3-gadget -b 16
LP project: https://code.launchpad.net/snap-cm3
Core 16 branch: https://github.com/snapcore/cm3-gadget -b master
The snapd snap
The snap offering snapd itself. This was once part of the core snap but it has been ripped out as a separate snap since recently.
- Owner: Snapd Team
Code branch: https://github.com/snapcore/snapd
The kernel snap
- Owner: Kernel Team
pi-kernel - the generic Raspberry Pi kernel for all supported Pi devices (pi2, pi3, cm3)
dragonboard-kernel
pc-kernel
For core16 only (not used for core18), legacy snaps:
pi2-kernel - the generic Raspberry Pi kernel, now renamed to pi-kernel.
Model assertions
All available and officially supported model assertions are available on https://github.com/snapcore/models .
One can get the model assertions for the selected supported platform by using the following commands:
Core 20
Besides the default, signed ones below, we also provide -dangerous and -<channel> model assertions.
Generic Raspberry Pi (32-bit): snap known --remote model series=16 model="ubuntu-core-20-pi-armhf" brand-id=canonical
Generic Raspberry Pi (64-bit): snap known --remote model series=16 model="ubuntu-core-20-pi-arm64" brand-id=canonical
amd64: snap known --remote model series=16 model="ubuntu-core-20-amd64" brand-id=canonical
Core 18
Generic Raspberry Pi: snap known --remote model series=16 model="ubuntu-core-18-pi" brand-id=canonical
Generic Raspberry Pi (64-bit): snap known --remote model series=16 model="ubuntu-core-18-pi-arm64" brand-id=canonical
Dragonboard: snap known --remote model series=16 model="ubuntu-core-18-dragonboard" brand-id=canonical
amd64: snap known --remote model series=16 model="ubuntu-core-18-amd64" brand-id=canonical
i386: snap known --remote model series=16 model="ubuntu-core-18-i386" brand-id=canonical
Obsolete Raspberry Pi 2: snap known --remote model series=16 model="ubuntu-core-18-pi2" brand-id=canonical
Obsolete Raspberry Pi 3: snap known --remote model series=16 model="ubuntu-core-18-pi3" brand-id=canonical
Obsolete Raspberry Pi 3 (64-bit): snap known --remote model series=16 model="ubuntu-core-18-pi3-arm64" brand-id=canonical
Obsolete Raspberry Pi CM3: snap known --remote model series=16 model="ubuntu-core-18-cm3" brand-id=canonical
Core 16
Raspberry Pi 2: snap known --remote model series=16 model="pi2" brand-id=canonical
Raspberry Pi 3: snap known --remote model series=16 model="pi3" brand-id=canonical
Raspberry Pi CM3: snap known --remote model series=16 model="cm3" brand-id=canonical
Dragonboard: snap known --remote model series=16 model="dragonboard" brand-id=canonical
amd64: snap known --remote model series=16 model="pc-amd64" brand-id=canonical
i386: snap known --remote model series=16 model="pc-i386" brand-id=canonical
Build and promotion automation
See UbuntuCore/CoreSnapAutomation .
Promoting snaps to stable
For some cases, the 18 snaps use a special 18 track instead of the default one. This means that for those snaps, instead of channels like stable, candidate, beta, edge there's 18/stable, 18/candidate, 18/beta, 18/edge - especially for gadget snaps. Before attempting promotion from one channel to another, always make sure that you are specifying the right track and channel. Otherwise one might promote a core18-targeted snap to the stable channel used by core16 devices. Look at the list of revisions and available tracks/channels before promotion.
The edge, beta and candidate snap promotions are handled by our automation (see above section). Manual promotion is only required when moving a snap from candidate to stable, in which case the following instructions need to be followed. NOTE! For core18/core20/core20+ snaps, always coordinate first with the snapstore team before promoting to stable. Base snap releases always cause huge spikes in bandwidth consumption so we need to make sure there are no other releases/operations in progress that could cause infrastructure issues.
Another important thing to keep in mind is that all base snap releases are released using progressive releases (phased upgrades). So, in fact, only after approximately 36 hours (15% increment roughly every 6 hours) a new version is available for all users in the respective <track/>stable channel.
Releasing a new snap to stable:
- Get the list of revisions that are supposed to be promoted for this snap (can be through the snapcraft dashboard).
- Remember that there's a separate revision number for every architecture.
Run export SNAPCRAFT_EXPERIMENTAL_PROGRESSIVE_RELEASES=y to enable progressive releases (note: might be no longer needed after becoming non-experimental).
Run this command on the same terminal: snapcraft release <snap_name> <revision> <track/>stable --progressive 10
<track/> depends on whether the snap you are promoting has a specific track you want to use, like 18/.
Example #1 (core18 snap): snapcraft release core18 1234 18/stable,18/candidate --progressive 10
- The progressive release value can be anything, but we tend to start from 10%.
Releasing a new ubuntu-core image
See UbuntuCore/ReleaseProcess .
Adding new Ubuntu Core Appliances
[Ubuntu Appliances|https://ubuntu.com/appliance] are basically Ubuntu Core images with some special snaps preinstalled and preconfigured. Such images can be loaded on the given platform (Pi's mostly right now) to turn it into a home/office appliance. Currently those are built on ubuntu-cdimage and based on UC18.
See UbuntuCore/AddingAppliances .
Useful Documentation
https://ubuntu.com/core/docs/uc20/inside - Inside Ubuntu Core 20 official documentation outlining how UC20 images work and how the various components interact with each other.