Validation sets: snaps that belong together
purpose for administrators for Ubuntu Core developers for app developers
Each snap refreshes on its own channel so the combination of revisions on a device may be one nobody tested. A validation set is an account's signed statement that certain snaps and revisions belong together. A device can watch a set or enforce it and a model can enforce one from first boot. Enforcing pins revisions and blocks removal so it trades freedom on the device for a combination that was tested.
On the map: assertions district
01 Tested together, refreshed apart
A validation set is an account's signed statement that some snaps, optionally at fixed revisions, belong together. The documentation says it helps interdependent snaps "maintain their testing and certification integrity" and "orchestrate their updates". acme-updater and acme-vpn are invented for this map.
On acme's test bench, agent 41, updater 17 and VPN 8 passed every test, together. In the field, each of them follows its own channel. So what's running on gateway number 600 this morning? Snapd refreshes a snap when its channel moves. The agent went to 42, the other two stayed, and that mix was never on the bench. What's missing is a statement. In snapd's words, a validation set is a statement by an account about a set of snaps, and possibly revisions, that work well together. Any account can publish and sign one. Enforce it on the gateway with refresh, and the agent goes back to 41.
02 Three decisions per snap
Each snap in a set is required (the default), optional or invalid, with an optional revision. An invalid snap cannot carry a revision.
Think about what acme really wants to say about a gateway. It isn't only revision numbers. A set is a list, and each line is a decision about one snap. Required is the default: the agent has to be installed, and here it has to be revision 41. Optional means the snap is allowed. The diagnostics snap may be there or not, but if it is, it has to be revision 5. Invalid means it must not be on the device at all, like an old VPN snap that acme has retired. The revision is optional on every line. Leave it out, and any revision satisfies the set.
03 Watch first, then constrain
--monitor reports whether the device matches a set and blocks nothing. --enforce constrains, and needs the device to satisfy the set first, or --refresh to make it so. A new sequence allows a rollback to the previous one.
You've written the set. Do you dare switch it on across the fleet? Start by watching. snap validate --monitor tracks the gateway-set and tells you, when you ask, whether this device matches. Here it says invalid, because the agent is at 42. Nothing is blocked. Enforce is the mode that constrains, and snapd won't start enforcing a set the device doesn't already satisfy. Add the --refresh and snapd first installs or refreshes what's needed. Sets are published in numbered sequences. The docs give the reason: if applying a new sequence fails, snapd can go back to the previous one. Raise the sequence whenever a production set changes.
04 Enforced from the factory for Ubuntu Core developers for administrators
A model lists validation sets with mode enforce or prefer-enforce. Both are enforced from first boot; only a prefer-enforce set can be forgotten. A sequence in the model allows only that sequence.
Typing snap validate works for the gateway on your desk. The other 999 need the same rule before anyone has touched them. So acme writes the set into the gateway's model. Each device then enforces it from its first boot, at the end of seeding. Mode enforce holds for as long as the model lists the set, and snap validate --forget is refused. prefer-enforce starts the same way, but the set may be forgotten later. The model can also fix a sequence, and then only that sequence is allowed. So the model answers a question the set can't: is this statement advice, or part of what the device is?
05 What enforcing costs
Under an enforced set, required snaps cannot be removed and other revisions are refused. --ignore-validation overrides it for one snap and is remembered. Local installs are not checked.
A statement that binds has to cost something. Here's what you give up on that gateway. Removing the VPN fails, because the set requires it, and the error names the set. Asking for agent 42 is refused too, since revision 41 is required. There is a way out: --ignore-validation. It isn't a one-off. Snapd remembers it for that snap on later refreshes, and the set now reports invalid. The docs are open about two limits. A snap file you install by hand isn't checked. And while several snaps update, old and new revisions can coexist for a moment, so a set is no tool for hard version dependencies.
06 When another tool fits better
Use a hold for one snap on one machine and a track for an older line of releases. A validation set is for a combination across devices. The older gating-snap mechanism, the validation assertion, still gates refreshes.
Before you publish a set, ask whether the problem is really a combination. Often it's smaller. If one snap misbehaves on one machine, hold that snap. If some devices should stay on an older line of releases, that's what tracks are for. Reach for a set when the unit is a combination and the audience is a fleet. You may also meet an older mechanism in the Ubuntu Core docs: refresh control with a gating snap. Its publisher approves each revision of another snap with a validation assertion. The code warns readers not to confuse the two. Snapd still applies that gating when it refreshes an installed snap.
07 Where to go from here
The assertion and its modes are in "Assertions: snaps and validation"; the other ways to control updates are in "Who decides when a snap updates".
So that's what a validation set is for: a signed statement that keeps a tested combination together, watched or enforced. The format and the exact refusals are one deck over, with the snap assertions. Assertions: how they work shows how any assertion is signed and checked. Who decides when a snap updates compares holds, timers and sets. Refresh is the change that a set steers. The model and first boot decks show sets written into a model and enforced at the end of seeding. And recovery systems and a store of your own cover the rest.
Read more
What the sources say a validation set is for
- snapd: "a statement by an account about a set snaps and possibly revisions for which an extrinsic/implied property is valid (e.g. they work well together)" (
asserts/validation_set.go, quoted as written) - the documentation: to help a group of interdependent snaps "maintain their testing and certification integrity, as well as help orchestrate their updates", to simplify dependency deployment, and to help manage devices
A set is signed by the account it belongs to: its authority-id must equal its account-id.
Presence
| presence | Meaning | With a revision |
|---|---|---|
required (default) | the snap must be installed | it must be at that revision |
optional | the snap may be installed | if installed it must be at that revision |
invalid | the snap must not be installed | a revision is an error here |
Modes on a device
| Mode | Set by | Effect |
|---|---|---|
| monitor | snap validate --monitor <account>/<name>[=<seq>] | prints valid or invalid; blocks nothing |
| enforce | snap validate --enforce [--refresh] <account>/<name>[=<seq>] | constrains install, refresh and remove; refused unless the device already satisfies the set, or --refresh makes it so |
| enforce (model) | model validation-sets with mode: enforce | enforced from first boot, at the end of seeding; cannot be forgotten |
| prefer-enforce (model) | model validation-sets with mode: prefer-enforce | enforced from first boot; can be forgotten |
snap validate --forget <account>/<name> stops tracking a set. =<seq> pins a sequence; without it the set may move to newer sequences. A model entry without account-id uses the model's brand. A model entry with sequence allows only that sequence: only sequence <n> allowed by model.
--refresh installs and refreshes snaps to satisfy the set. It does not remove snaps the set marks invalid.
What an enforced set changes
| Operation | Result |
|---|---|
| install a snap marked invalid | cannot install snap "<snap>" due to enforcing rules of validation set <key> |
| refresh to another revision | cannot update snap "<snap>" to revision <n> without --ignore-validation, revision <m> is required by validation sets: <keys> |
| remove a required snap | snap "<snap>" is required by validation sets: <keys>, or snap "<snap>" at revision <n> is required by validation sets: <keys> when the set gives a revision |
| refresh all | each snap is steered to the revision the sets require; for a pinned revision the channel and cohort are not used |
| install a local file | not checked |
--ignore-validation | allowed; remembered for that snap on later refreshes; the set then lists as invalid |
| forget a set the model enforces | validation-set is enforced by the model |
A set's key is printed as 16/<account-id>/<name>/<sequence>. Parallel instances are not constrained.
Validation sets and gating snaps
| Validation set | Gating snap (refresh control) | |
|---|---|---|
| Assertion | validation-set | validation plus refresh-control in the gating snap's snap-declaration |
| Signed by | any account for itself | the gating snap's publisher |
| Says | which snaps and revisions belong together | this revision of that snap is approved |
| Applies when | the device tracks the set or the model lists it | the gating snap is installed and an installed gated snap refreshes |
| Set up by | the account alone with snapcraft edit-validation-sets | the store team sets refresh-control first |
--ignore-validation skips both.
Further reading
- Validation sets: the published explanation and its "Why use a validation set"
- Manage validation sets: creating a set with snapcraft and using monitor and enforce
- Model assertion: the
validation-setsheader and its modes - validation-set assertion: the fields of the assertion
- Refresh control: the older gating-snap mechanism
Roads from here
GETTING SNAPS
- A store of your own — the store a brand publishes its snaps and sets in
RUNNING SNAPS
- Who decides when a snap updates — every other way to decide when a snap updates
- Refresh — the refresh that a set steers
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — how any assertion is signed and checked
- Assertions: snaps and validation — the validation-set assertion and what enforcing refuses
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the model that lists sets for a device
- ubuntu-seed and first boot — sets enforced at the end of seeding
- Recovery systems — sets when a recovery system is created