Hooks: confdb hooks

hook group for Ubuntu Core developers for app developers for snapd developers

Five hook name patterns that end with the name of a confdb plug. A write through a view runs change-view and save-view in every connected custodian then commits and runs observe-view in the other affected snaps; a read runs load-view and query-view in the custodians and commits nothing. Confdb is experimental and needs experimental.confdb.

On the map: hooks district

▶ Watch this deck — 7 scenes, ~5 min

01 A write and a read through a view

TWO PIPELINES AROUND A VIEW writesnap set acme/gateway/proxy-admin host=… or snapctl set --viewchange-view-<plug>save-view-<plug>commitcustodiancustodiansnapd observe-view-<plug>other snaps, after the commit readsnap get acme/gateway/proxy-admin password or snapctl get --viewload-view-<plug>query-view-<plug>answercustodiancustodiannothing committed <plug> = the snap's own confdb plug namechange-view-proxy-admin, for plug proxy-admin experimental.confdb=true
Two lanes: a write runs change-view and save-view in custodians, then the commit, then observe-view in other snaps; a read runs load-view and query-view in custodians and answers without committing; every hook name ends with a confdb plug name; confdb needs experimental.confdb=true

Five patterns: change-view-, save-view-, observe-view- on writes; load-view-, query-view- on reads. The suffix is a confdb plug name. The schema acme/gateway and its views are examples.

The gateway's proxy address lives in confdb, under acme's gateway schema, and no single snap owns it. So when you change it, which snaps get a say, and when? A write first runs change-view in the custodians, where a custodian can check or adjust the value, then save-view, where it can store it somewhere else. Then snapd commits, and observe-view tells the other snaps. A read runs load-view and query-view in the custodians, and commits nothing. Every one of these hook names ends with the snap's own confdb plug name. And confdb is experimental: it's off until you set experimental.confdb.

02 Custodian or observer: the plug decides for Ubuntu Core developers for app developers for snapd developers

CUSTODIAN OR OBSERVER # acme-settingsplugs:proxy-admin:interface: confdbaccount: acmeview: gateway/proxy-adminrole: custodian change-view-proxy-adminsave-view-proxy-adminload-view-proxy-adminquery-view-proxy-adminwhile the plugis connected # acme-agentplugs:proxy:interface: confdbaccount: acmeview: gateway/proxyno role: an observer, withobserve-view-proxy only every view needs a connected custodian, or:cannot read confdb view acme/gateway/proxy: no custodian snap connected acme-settings has a second plug, proxy,for gateway/proxy, also role: custodian a write through proxy-admin gives acme-settings two observe-view tasks, one per affected plug
acme-settings' snap.yaml has a confdb plug proxy-admin for the view gateway/proxy-admin with role custodian, and its hooks are named after the plug; acme-agent's plug proxy has no role, so it only gets observe-view-proxy; a view with no connected custodian refuses reads and writes, so acme-settings also has a custodian plug proxy, and a write can give it one observe-view task per plug

role: custodian on a connected confdb plug selects the custodian hooks for that one view. A write or read with no custodian connected fails with no custodian snap connected. System schemas have no custodians. Naming a plug after its view is a habit, not a rule.

Who counts as a custodian? It's written on the snap's confdb plug. Acme-settings has a plug called proxy-admin, for the proxy-admin view, with role: custodian. So for writes and reads through that view, it runs change-view-proxy-admin, save-view-proxy-admin and the rest, as long as the plug is connected. Acme-agent's plug, called proxy, has no role, so acme-agent is an observer: it only gets observe-view-proxy after a write. Every view needs a connected custodian, or reads and writes through it are refused. So acme-settings has a custodian plug for the proxy view too, which means one write can bring it two observe-view tasks, one per plug.

03 A write is a pipeline for Ubuntu Core developers for app developers for snapd developers

A WRITE $ snap set acme/gateway/proxy-admin host=PROXY2.ACME.EXAMPLEchange: Set confdb through "acme/gateway/proxy-admin"clear-confdb-tx-on-error Run hook change-view-proxy-admin of snap "acme-settings"PROXY2.ACME.EXAMPLE→ proxy2.acme.example Run hook save-view-proxy-admin of snap "acme-settings"sees proxy2.acme.examplecommit-confdb-tx: Commit changes to confdb (acme/gateway/proxy-admin)saved Run hook observe-view-proxy of snap "acme-agent"… acme-settings (both plugs), acme-updater, acme-vpnsee proxy2.acme.exampleone task per affected plugclear-confdb-tx the snap that made a writegets no observe-view$ snap get acme/gateway/proxy-admin hostproxy2.acme.example change-view can refuse the write with snapctl fail: see snapctl: configuration and health
The set-confdb change after snap set acme/gateway/proxy-admin host=PROXY2.ACME.EXAMPLE: clear-confdb-tx-on-error, change-view-proxy-admin in acme-settings lowercases the host, save-view-proxy-admin sees the final value, commit-confdb-tx, observe-view tasks for acme-agent, acme-settings (two plugs), acme-updater and acme-vpn, clear-confdb-tx; snap get then returns the lowercase host

Order: all change-view-, all save-view-, commit, observe-view- of the affected snaps except the writer. Values set in change-view are what everyone after it sees. A snapctl set --view from an app waits for the change, up to 2 minutes.

You run snap set on the proxy-admin view, and type the host in capitals. Snapd starts a set-confdb change. First, change-view runs in every custodian, in snap name order, and acme-settings' hook lowercases the host. Next, save-view runs in each custodian and sees the final value. Then snapd commits. Then observe-view runs for every snap whose view the write touched: acme-agent, acme-settings, acme-updater and acme-vpn. Had acme-settings' own app made the write, it wouldn't be told. Snap get now returns the lowercase host. And change-view could have refused the write instead, with snapctl fail.

04 A failed save is rolled back, and save-view runs again for Ubuntu Core developers for snapd developers

ROLLBACK $ snap set acme/gateway/proxy-admin host=proxy3.acme.examplechange-view-proxy-adminacme-backupfirst, by snap nameacme-settings save-view-proxy-adminacme-backupsaves proxy3.acme.exampleacme-settings✗ exit 1 rollback: save-view again with the committed data, errors ignoredacme-settingsthe failed one firstacme-backupsaves proxy2.acme.example $ snap changes… Error … Set confdb through "acme/gateway/proxy-admin"$ snap get acme/gateway/proxy-admin hostproxy2.acme.example# what acme-backup's server receivedproxy3.acme.exampleproxy2.acme.example commit-confdb-txobserve-view-…nothing committed, no observer told save-view may run twice: it must give the right result the second time
With two custodians, acme-backup and acme-settings, a write of host=proxy3.acme.example runs both change-view hooks; acme-backup's save-view stores proxy3, acme-settings' save-view exits 1; the rollback runs save-view again, the failed one first, then acme-backup with the committed proxy2; commit and observe-view do not run; the change errors and the host stays proxy2

A save-view failure rolls every custodian back by running its save-view- hook again with the committed data. Write save-view hooks so that they can run twice. acme-backup is an invented example; snapd's test confdb-cross-config checks this order.

Now another custodian is connected: acme-backup, which copies proxy settings to a backup server. You write a new host. Both change-view hooks run, acme-backup's first, by name. Then acme-backup's save-view stores the new host on its server, and acme-settings' save-view fails. What now? Snapd resets the transaction to the committed values and runs the save-view hooks again: the failed one first, then the earlier ones, with errors ignored. So acme-backup saves twice, the second time with the old host. The change fails, nothing is committed, and no observer is told. Write save-view so it gives the right result when it runs again.

05 A read can run hooks too for Ubuntu Core developers for app developers for snapd developers

A READ snapd's copy, a cache of ephemeral datapassword: cached-secret $ snap get acme/gateway/proxy-admin passwordchange: Get confdb through "acme/gateway/proxy-admin"clear-confdb-tx-on-error Run hook load-view-proxy-admin of snap "acme-settings"sees cached-secretloads current-secret Run hook query-view-proxy-admin of snap "acme-settings"sees current-secretmay adjust the answerclear-confdb-txload-confdb-changethe answer, for the readercurrent-secret unchanged: nothing committed no custodian with load-view or query-view: no hook runs, the answer comes from snapd's copya read that may cover ephemeral data, with no load-view hook:read might cover ephemeral data but no custodian has a load-view hook
snap get of the proxy password through acme/gateway/proxy-admin starts a get-confdb change: load-view-proxy-admin in acme-settings sees the cached value and loads the current one, query-view-proxy-admin sees it and may adjust it, and the reader gets the result; snapd's cached copy is unchanged; without these hooks no hook runs, and ephemeral data needs a load-view hook

load-view- fills a read transaction; query-view- adjusts it. Neither is saved. A failure fails the read.

Reads can involve custodians too. The proxy password is ephemeral: acme-settings keeps the real copy outside snapd, and snapd holds only a cached one. When snap get asks for it, snapd starts a get-confdb change. Load-view runs in acme-settings, sees the cached value, and loads the current one. Query-view runs next, sees what load-view set, and may adjust it. The reader gets the result. None of it is committed: snapd's copy still holds the old value. If no custodian has these hooks, none runs, and the answer comes from snapd's copy. But a view with ephemeral data can't be read without a load-view hook.

06 A slow custodian hook delays every access to its confdb for Ubuntu Core developers for snapd developers

WAITING FOR ACCESS $ snap set acme/gateway/proxy-admin host=proxy4.acme.examplechange: Set confdb through "acme/gateway/proxy-admin" Run hook save-view-proxy-admin of snap "acme-settings"Doing · waiting for acme's server queued behind it, in arrival order1 snap get … host2 snap set … host=proxy5…3 snap get … hostwaitingwaitingwaiting $ snap get acme/gateway/proxy-admin --wait-for 0s hosterror: cannot read acme/gateway/proxy-admin: timed out waiting for access the server answers, the hook ends, the write commits1 → proxy4.acme.example2 → written3 → proxy5.acme.example while a custodian snap is being refreshed, its confdb hooks are held, not skipped
A set-confdb change is held in save-view-proxy-admin of acme-settings, which waits for acme's management server; a get, a set and a get of the gateway schema queue behind it; a get with --wait-for 0s fails with timed out waiting for access; when the hook ends the queue runs in order, the first read seeing proxy4 and the last read proxy5

Accesses to one confdb schema are serialised behind the running write; reads may run together. Keep custodian hooks short: every reader and writer waits for them. A waiting access gives up after 10 minutes by default, or after --wait-for.

Acme-settings' save-view hook pushes each new proxy address to acme's management server, and today that server is slow. Meanwhile, more reads and writes of the gateway schema arrive. They queue behind the open write. A reader that will only wait zero seconds gets timed out waiting for access. When the server answers and the hook ends, the queued requests run in the order they arrived. The first read sees the address the slow write saved, and a read queued behind a later write sees the later one. Confdb hooks are also held, not skipped, while their snap is being refreshed. So keep custodian hooks short: everyone waits for them.

07 Where to go from here

ROADS Hooks: confdb hooksConfdbwhat it is for Hooksthe mechanismConfigurationschemas, views, databags snapctl: configurationget, set --view, fail Confdb assertionsthe views' definition Interfacesthe confdb interfaceInterface hooksnamed after a plug The overlordset-confdb, get-confdb
Roads from confdb hooks: what confdb is for, hooks, configuration, snapctl configuration, confdb assertions, interfaces, interface hooks and the overlord

Roads: what confdb is for, the mechanism, configuration, the snapctl commands, assertions, interfaces, interface hooks and the overlord.

Those are the hooks around a view. The confdb deck explains why confdb exists at all: data that no single snap owns. The hooks deck covers the mechanism that runs every hook. The configuration deck explains schemas, views and databags. The snapctl configuration deck shows snapctl get and set with a view, and snapctl fail. The confdb assertions deck shows the schema that defines the views. The interfaces deck covers the confdb interface and its plugs, interface hooks the other hooks named after a plug, and the overlord the set-confdb and get-confdb changes.

Read more

The tasks of a write and a read

ChangeKind and summaryTasks, in order
A writeset-confdb, Set confdb through "<account>/<schema>/<view>"clear-confdb-tx-on-error; change-view of each custodian that ships it, by snap name; save-view of each, in the same order; commit-confdb-tx; observe-view for each affected plug of each affected snap except the writer; clear-confdb-tx
A readget-confdb, Get confdb through "<account>/<schema>/<view>"clear-confdb-tx-on-error; load-view of each custodian that ships it; query-view of each; clear-confdb-tx; for snap get, load-confdb-change
  • Custodians are snaps with a connected confdb plug for exactly this view with role: custodian. A view of a non-system schema with none refuses reads and writes.
  • An affected snap has a connected confdb plug for any view of the schema that the written paths reach, custodian or not. It gets an observe-view task per such plug, also when it ships no observe-view hook; that task then does nothing.
  • snap set has no writing snap, so every affected snap is told. A write from a snap's app with snapctl set --view skips that snap.
  • A read through snap get always creates a change; without load-view or query-view hooks it is complete at once. snapctl get --view without those hooks reads snapd's copy directly.

What a failure does

Hook failsResult
change-view, or it calls snapctl failthe write is refused: cannot change confdb <account>/<schema>: <snap> rejected changes: <reason>
save-viewevery custodian's save-view runs again with the committed data, the failed one first, errors ignored; the write fails
observe-viewignored; the write has already been committed
load-view, query-viewthe read fails

Waiting

WaitLimitMessage
a read or write waits for an earlier write of the same schema--wait-for, or 10 minutescannot read <view>: timed out waiting for access (or write)
snapctl set --view or get --view from an app waits for its change2 minutescannot write confdb view <view>: timed out (2m0s) waiting for change <id>
a confdb hook while its snap is being refreshedheld until the snap is active againnone

Reads may run together; a write waits for every earlier access and holds the schema until its change is done.

Messages

MessageCause
cannot write confdb view <view>: no custodian snap connectedno connected custodian for the view; cannot read for a read
cannot write confdb view <view>: write might change ephemeral data but no custodians has a save-view hookan ephemeral path would be written with no save-view to store it
cannot schedule tasks to read view <view>: read might cover ephemeral data but no custodian has a load-view hookan ephemeral path would be read with no load-view to fetch it
snaps cannot be custodians of "system" confdb schemasrole: custodian on a plug for a system schema

The schema acme/gateway, its views and the snaps in this deck are examples.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

SNAPCTL · the snap's API into snapd

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap