Skip to content

Permanent ids for what berth keeps - #74

Merged
helightdev merged 8 commits into
mainfrom
stable-ids
Nov 15, 2026
Merged

helightdev merged 8 commits into
mainfrom
stable-ids

Conversation

@helightdev

@helightdev helightdev commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

Gives every host, provisioner, resource, registry, secret and key a permanent id. Names become labels: a rename changes the label alone, and everything that refers to a thing or belongs to it uses its id. The page for API consumers is docs/content/docs/(guide)/reference/ids.mdx.

Ids

  • A UUID v7 as 32 lowercase hex characters, no hyphens (berth_api::ids). Replies, the store and logs use this form.
  • host_, prov_, res_, reg_, sec_ and key_ prefixes are accepted and stripped. A prefix of another kind is refused with a 400. The hyphenated UUID form is accepted on input.
  • A value is read as follows. A prefixed id is that id alone (404 if missing, never tried as a name). A bare id is that id if a thing has it, otherwise a name. Anything else is a name.
  • Names in the shape of an id (32 hex, either case, with or without a prefix) are refused at creation and at rename.
  • Plugins keep their package id. Jobs keep their ids. Existing r-… resource ids are converted to new ids; provisioners only read the label's presence.

Store layout

I kept the layout from the design note rather than an entities table. state gets a label column with UNIQUE (kind, scope, label) WHERE label IS NOT NULL; the key stays (kind, scope, name) and name holds the id.

  • One row stays one thing. Export, berth store copy, reseal and the sealing context keep handling one table. Rows are sealed under the id, so a rename needs no reseal.
  • The database enforces unique names on both backends, and a rename is one UPDATE (Backend::relabel).
  • A write without a label keeps the row's label (COALESCE), so code that rewrites a value cannot drop it.

What belongs to a thing is a row without a label whose name is the owner's id or ID/…:

Kind Rows
Host credentials, access, tailnet named by its id, and secrets ID/ssh and ID/sudo
Registry secret ID/login
Provisioner secrets ID/SECRET
Resource spec named by its id
Key ID/pending

Batch::forget_owned(scope, id) deletes them in the same transaction as the owner. Backend::change_states takes one Change, applied in this order: removals, owners, writes, then the host and job moves. It replaces rename_host and #71's rename_subject.

References

  • Resource records: provisioner and host are ids. A host in a file keeps its path.
  • Provisioner entries: node is the node's id.
  • Jobs: subject and host are ids.
  • Messages and cursors are keyed by the host's id, and lock files are locks/ID.lock.
  • The tailnet record from feat(serve): remove a destroyed host's tailnet device and rename it with the host #72 is keyed by the host's id.
  • Profiles in the store hold ids for registries, secrets[].name and access.auth = key:….
  • Place::load gives names and Place::save takes names or ids (profiles::refs). Export, edit, profile files and the profile a host keeps of itself show names.
  • A reference to a secret or registry that does not exist yet stays a name, and becomes the id when the thing is made. A removed one turns back into its name.

Secrets

Owned secrets keep their addresses on the wire: registry/NAME, ssh/HOST, sudo/HOST and provisioner/NAME/SECRET. NAME may be a name or an id, and the server resolves the owner. Setting one for an owner that does not exist is a 404. secrets.list keeps names and adds secrets: [{id, name}] for the global ones.

The fallback from a provisioner's secret to a global one of the same name is gone, in provision::secrets and in node::said_same. A node's provisioner gets its own copy of the client certificate its feature trusts at each registration. A type such as incus/vm still names the single provisioner registered of that type.

API and CLI

  • Paths, query parameters and bodies take a name or an id. A layer in front of the router turns an id in a path into the thing's name, so every handler finds it as before. jobs.list and inbox.list filters resolve to ids.
  • Replies gain ids:
Reply Change
Hosts id
Provisioners id is now the id, beside name and node_id
Resources provisioner_id, host_id
Registries id in each entry
Keys id
Jobs subject by id; subject_name and host_id added
Inbox and resource events host_id / provisioner_id

Migration

A new schema step on both backends adds the column and index. Then the ninth import, import:ids, runs in one transaction after the copy berth makes before converting:

  1. It gives each thing an id and moves owned rows under their owners. A login or password whose owner is gone is dropped.
  2. It rewrites references in records, profiles, jobs, messages and cursors.
  3. For each provisioner, each secret its type declares that it lacked and that a global secret provided, it copies the global into its owned secrets. It removes that global if no profile hands it to a host and no feature trusts it as a client certificate.

The step is idempotent: labelled rows and rows named ID or ID/… are left alone. Tests cover the 0.5.2 fixture and a new 0.6.0-rc.4 fixture (made with that tag's berth plus rows of its layout), and the store suite runs the conversion and renames on both backends.

The host's kept profile is format 4 and carries its id. berth host adopt reuses that id when no host here has it.

For consumers

  • Existing calls with names work as before.
  • A provisioner's id used to be its name; read name instead.
  • A job's subject holds ids; subject_name says it by name.
  • A provisioner is given no global secret of the same name. Stores are converted, and new provisioners need their own secrets.

…ries, secrets and keys

Names are labels, and what refers to a thing or belongs to it uses its id. The ninth import converts a store once, and a provisioner is given no secret it does not own.
Comment thread crates/berth-core/tests/upgrade.rs Fixed
@helightdev
helightdev marked this pull request as ready for review November 15, 2026 22:09
@helightdev
helightdev merged commit 51ceb78 into main Nov 15, 2026
21 checks passed
@helightdev
helightdev deleted the stable-ids branch November 15, 2026 23:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants