Devices, Workers and System Disks

Kurrent splits the compute side into three independent entities. Each has its own identifier and authority, and a bootable system is formed by binding them together. Machines, identities and disks can therefore be replaced separately.

Entity	Identifier	Authority	Determines
Device	MAC	Device ledger state/devices.yml	Which physical machine
Worker	worker_id (hostname)	Worker ledger state/workers.yml	Under which identity
System disk	NQN	Disk file on the storage node + Worker ledger	Which system to boot

Device

A device represents a physical machine. On its first network boot, firmware reports an 11-field fingerprint (MAC, UUID, SMBIOS, CPU, memory, NIC and others) and the device public key; the control plane records it under the MAC.

A device record contains:

Field	Meaning
mac	Unique device identifier; the authoritative anchor of the binding
uuid / fingerprint	Reported hardware information for identification and audit
state	pooled / bound / revoked
bound_worker_id	Bound Worker; empty when unbound
Public-key hash	Digest of the device identity key, used for admission when signature enforcement is on
source	ipxe (automatic report) or manual (manual registration/import)

Lifecycle:

pooled ──bind──► bound ──revoke──► revoked
  ▲                │
  └────unbind──────┘

• Registration is not authorization. Entering the pool only means "this machine has been seen"; it grants no boot rights. Only after binding to a Worker does the device become that Worker's booting node.
• Automatic admission happens only while the registration window is open and the report carries a valid public key; once closed, reports only update fingerprints and add no entries. Manual registration and purging revoked entries are not limited by the window.
• revoked devices no longer accept reports; the dnsmasq binding file receives MAC,ignore, so a revoked device gets no lease.

Worker

A Worker is a compute identity. worker_id doubles as the hostname and is the index for ledgers and credentials. It is not a machine identity and survives hardware replacement.

A Worker record contains:

Field	Meaning
worker_id	Compute identity; ledger primary key
Bound device	Projected from the device ledger; not stored separately
disks[]	Mounted system disks
default_disk	Default boot disk (os_tag)
boot	Optional menu entry and timeout overrides
state	registered (identity only) or ready (has a system disk)

readiness is a derived read-only projection:

Value	Condition
ready	Has a bound device and a system disk
partial	Has only a bound device, or only a system disk
idle	Has neither

System Disk

A system disk is a disk file on a storage node, identified authoritatively by its NQN on the data plane:

NQN    = <nqnBase>:<worker_id>.<os>.<os_tag>
IQN    = derived from the NQN (consumed by the iSCSI backend and installers)
os_tag = 12 random hex digits (disk-level identifier)
file   = <worker_id>.<os>.<os_tag>.img

• os and os_version are display and grouping metadata; os has no allowlist. A Worker may hold at most one disk per (os, os_version), while different versions may coexist.
• A disk can be cloned from a master image or created as an empty disk. Master images are never booted; they are only clone sources.
• os_tag is generated by the control plane at creation. Once the NQN is projected into boot variables, it is the disk's unique identifier.

Default Disk

The default disk determines which system boots after the menu timeout:

• The first system disk becomes the default automatically; later disks do not rewrite the default.
• When the default disk is deleted, a remaining disk is promoted automatically; with no disks left, default_disk is cleared.
• Without a default, /boot-vars returns menu-default=reboot, so the machine never silently boots the wrong system.

Master Images

A master image is a disk file under the storage node's spec.agent.diskDir whose filename contains _tpl_ (case-insensitive). A background scanner caches the master list and GPT layout:

• Both master images and system disks must use 4K-native GPT. A 512-byte-sector layout is rejected by both the Agent and nvmet-host, because firmware cannot parse the exported partition table.
• The filesystem must support reflink (btrfs / xfs) for near-instant cloning; ext4 degrades to a full copy.
• Master tags (os / os_version / remark) are stored in the Agent ledger and used only for display and disk selection.

Binding

The binding is one-to-one: a device belongs to exactly one Worker, and a Worker has at most one bound device.

• Authority is on the device side. bound_worker_id in devices.yml is the single fact; the bound device in a Worker response is only a projection. The dnsmasq hostname mapping is also a derived projection and does not participate in boot identity resolution.
• Binding is authentication. /boot-vars verifies that the requesting MAC belongs to the matched Worker's bound device, preventing another device from claiming the identity.
• Rebinding is atomic. With force=true, the new binding is written before the old one is cleared; a ledger snapshot is restored on failure.
• Unbinding only affects the device. The device returns to the pool while the Worker keeps its disks, default disk and credentials.

Rebinding as Cold Migration

Rebinding device A to device B is a cold migration:

1. Confirm B is registered with a device identity key, and the target Worker's credentials are effective on the storage node.
2. Power off or isolate A; live migration and data-plane fencing are not provided.
3. Rebind B on the Devices page; the system disk and Worker identity stay unchanged.
4. B boots, passes challenge-response and receives the connection information for the same disk.

The same path works in reverse; there is no automated orchestration yet.

Placement

When a system disk is created, the control plane decides the location unless disk_agent or a pin is explicit:

1. The candidate must have the disk role, be enabled (not drained), have a reachable base_url, and report a ready data-plane port.
2. When cloning, the master image must exist locally on that node.
3. Among candidates, the node with the fewest existing system disks is chosen (load spreading).
4. An explicit pin overrides automatic placement, but the pinned node must still pass availability checks.

Batch creation uses the same placement implementation for dry_run and execution; the preview is the plan that will run.

Deletion Semantics

Operation	Result
Delete a system disk (delete_file=false)	Removes the export target, keeps the disk file, removes the ledger entry
Delete a system disk (delete_file=true)	Also deletes the backing file; irreversible
Delete the default disk	Promotes a remaining disk; clears the default when none remain
Delete a Worker	Unbinds the device, removes the Worker's credential entry and push record; disk files handled by option
Unbind a device	Device returns to the pool; Worker and disks unchanged
Revoke a device	Enters revoked and no longer accepts reports; the purge entry removes only revoked records

Recreating a Worker with the same name does not inherit old credentials: the credential entry is removed with the Worker. A retained disk file can be mounted again, but its NQN and ledger record must be re-established.

Related Pages

• How these entities form one boot: Boot Chain
• Disks, credentials and the data plane: Storage and Data Plane
• Device and human identity: Identity and Access
• Delivery steps: First Delivery