Glossary
Every term the Better Compute docs use, from atoms and bookings to leases, NodeSpecs and exec tickets, with a link to the page that explains it.
Better Compute borrows words from Kubernetes, OpenStack Ironic and cloud APIs, and gives a few of them a narrower meaning. "Lease", for example, is never used alone: it is an allocation lease, a liveness lease, or a shard, pool or site lease, and each is a different thing. This page defines every term the guides mark as a glossary term, one or two sentences each, with a link to the page that explains it in depth.
A dotted underline in any guide marks such a term: hover or tap it for the definition, then follow Glossary to
land on its entry here. Each entry's anchor is its name in lower case with hyphens, for example
#allocation-lease.
A
Admission
The request-as-resource path every create of a reservation or instance takes: the request is written as a draft, Better IAM decides on that draft with its attributes, and only an allowed draft is placed. A retry with the same idempotency key replays the stored result.
Admission context
The IAM decision context recorded with each allowed mutation in audit_events: identity, session kind, agent, delegation and request id. Better IAM does not audit allows, and asynchronous work acts on this record, never on a stored token.
Allocation
A placement on one node, owned by a reservation or an instance, listing the atoms and scalar amounts it holds. A gang has one allocation per node.
Allocation lease
A renewable hold on a reservation: one made with leaseSeconds is released unless reservations.renew is called within every period.
Atom
A device with bookable: true, the only kind ever booked: a whole GPU, a MIG instance, a time-slice or MPS slot, a NIC virtual function, a disk or a whole node. A partitioned GPU's parent is not an atom.
Attestor
A plug-in of JoinService that checks one kind of join evidence and decides whether a machine may join and as which node: join-token, x509pop, provisioned, discovery, cloud-iid or tpm.
Authz projection
Compute's own rows describing every compute-* resource Better IAM may decide on (type, id, tenant, parent, owner and attributes), written in the same transaction as the change and held in memory. The resolver answers IAM from it, and list queries filter on the same rows.
B
bcd
The Better Compute daemon: one Go binary that runs on servers (node), site agents (site) and inside the PXE ramdisk (ramdisk), dials out to a gateway, runs commands and converges its NodeSpec. None of it is released. Its v0.1 node agent (bcd join, bcd node, bcd status) is tested end to end; bcd site and bcd ramdisk are written and covered by Go unit tests only; bcd sim runs many real node agents in one process on fake-hardware builds only; a host build with virsh runs VPS instances on the libvirt-kvm runtime, tested against a fake virsh only; self-update with A/B slots and the WebSocket fallback are written; and the TypeScript FakeDaemon stands in where bcd is missing.
BMC
The baseboard management controller: the part of a server that works when the server does not, used to power it, choose its boot device, mount media and read hardware. Metal reaches every BMC through a site agent, never from the control plane.
Booking
One row (device_id, allocation_id, during) in device_bookings. An EXCLUDE constraint allows one live booking per atom per instant, which is why double-booking cannot happen.
BookingRepair
The check that re-places a calendar reservation whose booked hardware went bad (cordoned, quarantined or unreachable), run 15 minutes before its start and again at the start.
C
Calendar reservation
A reservation with a start in the future. Its atoms are booked at admission for the window from start to start + duration, so nobody else can take them for that window.
Capacity
What the inventory makes bookable, per pool and resource: allocatable, allocated, reserved and available. Only schedulable nodes count as allocatable.
CDI
The Container Device Interface. For a hold reservation the node writes a CDI spec naming exactly the booked GPUs, which a workload manager on the node (containerd, Kubernetes, Slurm) consumes.
Command
A durable, idempotent one-shot message to one node, with a per-node seq, not_before, not_after, an optional min_generation and the flags of its kind. Commands are for actions; lasting state belongs in the NodeSpec.
Command kind
The registered type of a command, such as node.reboot or diag.nvml: its lane, the agent roles that accept it, a timeout, a payload message, and the flags retry-safe, self-terminating, attested and destructive.
compute_now()
The SQL function every query uses for the current time instead of now(), so the whole control plane reads one database clock. Tests point it at a simulated clock, and a repository lint refuses bare now().
Condition
A typed statement about a node or GPU, such as GpuCountMismatch, NodeUnreachable or ClockSkew, written by the health, inventory and liveness controllers. A condition with a NoSchedule effect keeps the node out of placement.
Config unit
One concern of a machine's host configuration in its NodeSpec host section, such as nvidia-driver, mig-layout or hugepages: a unit name and validated settings. Profiles' hostConfig and pool policies produce them; bcd's host converger applies them in a fixed order.
Cordon
A flag that stops new placements on a node and changes nothing else: existing allocations keep running and commands still flow. nodes.uncordon clears it.
D
Delegated confirmation
When an agent acting under a Better IAM delegation is denied an action the person held back, compute answers CONFIRMATION_REQUIRED instead of a plain denial; the person approves in Better IAM and the agent retries the same request.
Destructive-batch quorum
The v1.0 control against a compromised api or worker: destructive commands carry a batch_id and run only when enough operator approver keys, pinned in the trust bundle and held off the control plane, signed a BatchApproval over the Merkle root of the batch's (subject, kind) scope, which the machine checks with the command's inclusion proof. bcd and the FakeDaemon enforce it, the server stores, approves and holds batches (commandBatches, enqueue({ batchId })), the gateway attaches each batched command's approval and proof, and the built-in workflows, metal.bulk and metal.power create their own batches.
Device
A unit of hardware with typed attributes, in the style of Kubernetes dynamic resource allocation: class gpu, gpu.mig, gpu.slot, nic.vf, disk or node, with a stable id such as a GPU UUID, disk WWN or MAC.
Draft
The first state of a reservation or instance, written before IAM decides so that policies can read exactly what is asked for. Its id derives from the tenant, the caller's identity and the idempotency key, so a retry finds the same row.
Drain
A cordon that also waits for the node to empty: nodes.drain cordons the node, adds the draining NoSchedule reason and hands it to the Drain controller.
Drift
A difference between the fleet and the FleetConfig document last applied. The fleet.drift reconciler re-plans the applied document every 15 minutes by default and publishes fleet.drifted or fleet.converged.
Driver
An implementation of one or more hardware concerns in the Ironic sense: power, management, boot, deploy, inspect, console, virtual-media, bios, raid, firmware, config or runtime. A node binds one driver per concern, inherited from its pool's hardware profile unless overridden.
E
Epoch
A counter that fences a lease or session: every takeover increments it, and writes carrying an older epoch are refused, so a stalled worker, site agent or gateway cannot act after losing ownership.
EXCLUDE constraint
The PostgreSQL constraint EXCLUDE USING gist (device_id WITH =, during WITH &&) on device_bookings. It lets at most one live booking exist per atom per instant, whatever the placer or the API does.
Exec ticket
A single-use ES256 JWT (typ: bc-exec+jwt) that tunnels.open issues for one node, one tunnel and one caller, valid for at most 60 seconds. The API, the gateway and the daemon each verify it before any byte flows.
F
FakeDaemon
The TypeScript implementation of the daemon side of the protocol in @better-compute/testing, with the same journal rules, acceptance checks and lanes as bcd. It runs in tests, the fleet simulator and better-compute dev --sim N, and covers what bcd does not implement yet: VM hosts and their metadata service, site agents, self-update and the WebSocket fallback.
Flavor
A named instance shape such as g1.small, defined by a pool's owner and picked by name when creating an instance. In a hosted pool it becomes claims on one host; in a provider pool it names the provider's offer.
FleetConfig
The fleet's shape (sites, provider accounts, pools, quotas, offers and flavors) as one document keyed by name, exported, planned and applied in one transaction with fleet.export, fleet.plan and fleet.apply.
G
Gang
A reservation of 2 to 64 whole nodes that is placed all or nothing, optionally on one value of a topology label such as fabric.domain. It has one allocation per node and counts as one request for quota and IAM.
Gateway
The process that holds daemons' long-lived gRPC sessions over mutual TLS, delivers desired state and commands, and writes results and events to PostgreSQL. It keeps only soft state, so losing one loses open streams and nothing else.
Generation
The version number of a node's NodeSpec, incremented only when the spec's canonical JSON changes; adoption writes generation 1. The daemon reports observedGeneration, and a node is schedulable only once it has converged at least once.
H
Hardware key
The SHA-256 of a machine's normalized product UUID, serial number, permanent MACs and GPU UUIDs, used to recognize the same machine across joins. It is trusted only when at least two independent identifiers survive the placeholder blocklist.
I
IamPort
The interface compute calls for every IAM question: authenticate, require, authorize, authorizeMany, requestConfirmation, billingCheck, recordUsage and featureEnabled. The IAM bridge implements it over an embedded or a remote Better IAM.
Image
A signed, content-addressed OS or ramdisk artifact (name@version, raw, qcow2 or iso, with a SHA-256). It is verified once its signature checks out against a signer allowlist, and unsigned images stay private.
Instance
A VM, microVM or single-tenant container in a VPS pool, with a desiredState (running, stopped or deleted) and an observed state that the vps.instances reconciler drives toward it.
Inventory
The node's NodeInventory v1 document: hardware facts in sections, each hashed so the daemon sends only what changed, stored as append-only snapshots. It produces the node's devices, labels and conditions.
J
Join token
A secret of the form bcjt_<id>.<secret> that lets a machine join one pool, for a limited time (ttlSeconds) and a limited number of machines (maxUses, default 1). It is shown once and handed to the machine out of band.
JoinService
The control-plane service that admits machines: it runs the attestors on the join evidence, creates or reclaims the node row, and signs a short-lived node certificate, all in one transaction.
Journal
The daemon's local, bounded record of every command it accepted and every result and event not yet acknowledged, keyed by a journal_id. It makes sure no side effect runs twice; a lost journal starts a new id, and the server fails in-flight commands instead of replaying them.
L
Lane
One of the three delivery channels a command kind belongs to, control, provision or bulk, each with its own credits and a fixed pool of workers on the daemon, so bulk work never blocks control commands.
Liveness lease
A session's 40-second time to live, extended by heartbeats. When it lapses the node becomes unreachable, but nothing it holds is released.
M
Maintenance
A node flag, separate from cordon, set when provisioning fails, remediation gives up or an operator asks. It keeps the node out of placement until cleared.
MIG
NVIDIA Multi-Instance GPU, which splits one GPU into isolated instances. A GPU in MIG mode becomes an unbookable parent plus one gpu.mig atom per instance, and only mig pools accept requests for them.
N
Node
A machine Better Compute manages: a server running bcd, a site agent, or a provider machine. Its state is several independent axes (provision state, maintenance, cordon, power, connectivity and conditions), not one field.
Node certificate
The short-lived ECDSA P-256 client certificate JoinService signs for a daemon, valid for at most 24 hours (2 hours for a ramdisk), named by a SPIFFE ID and carrying a role: node, site, ramdisk or node-tenant.
NodeSpec
A node's generation-numbered desired state, in sections the daemon converges in a fixed order: host, devices, instances, access, telemetry and daemon. Modules contribute sections; the gateway delivers the whole spec or a patch.
O
Offering
A pool_offers row that makes a pool visible to another tenant, with a quota per resource and an optional priority. A resource missing from the quota grants zero.
Outbox
The table every event is written to, in the same transaction as the change it describes, so an event exists if and only if the change committed. Webhooks, the live stream, the history API and in-process subscribers all read it.
P
Placer
The component that decides where a request lands: which node, which atoms and which scalar amounts. The default inline placer places during admission; the pool-lease placer queues requests and places them in batches.
Pool
A scheduling and policy domain in one site, owned by one tenant, with exactly one GPU model, a class (metal-host, metal-dedicated, vps-host or provider), a sharing mode and policies such as acceptance checks and a disruption budget.
Profile
A versioned provisioning template for metal or VPS targets, with driver bindings, an image, user data, steps, host configuration and acceptance checks. It is immutable once a workflow has used it.
Project
An application-owned grouping inside a tenant (the projects table), which reservations and instances can name and policies can read as projectId.
Provider
An external capacity API, such as Hetzner Cloud, Hetzner Robot or Proxmox VE, behind a pool of class provider. Instances in such a pool are created through the provider rather than on your own hosts.
Provider account
A configured account with a provider, whose credentials are stored only as secret references, never as values. A provider pool is backed by one account.
Provision state
A node's lifecycle axis, from adopting or enrolling through ready and deployed to retired. The legal moves live in one table in @better-compute/core, and every verb, method and reconciler checks against it.
PXE
Network boot. On a bare-metal site the site agent answers proxy DHCP and serves TFTP and iPXE, so an enrolled machine boots into the ramdisk without anyone touching it.
Q
Quota
A cap on how much of each resource a tenant may hold in one pool at the same time, set by the pool's offering or quotas.set, counted in compute's database and charged all or nothing at admission.
R
Ramdisk
The PXE-booted initramfs in which bcd runs as bcd ramdisk to inspect, burn in, wipe and image a machine. It takes the gateway, pins, a single-use discovery token and the site agent's signed assertion from its kernel command line, joins with the discovery attestor, and keeps its identity in tmpfs, so every boot is a new one. Its certificate lasts at most 2 hours and allows only the commissioning command kinds (disk.wipe, deploy.image, boot.kexec, diag.*, inventory.refresh, logs.collect).
Reconciler
A level-triggered controller that reads the current state, compares it with the desired state and acts on the difference. It is woken through the work queue, sharded across workers, and never relies on having seen every event.
Region
A geographic label in Better IAM's region-name grammar, stored on a site as iamRegion so policies can decide on where capacity is.
Release
A manifest of one bcd version's files, signed offline by keys the control plane knows only by their sha256/... pins. Rollouts move nodes from one release to another.
Reservation
A tenant's claim on devices of one pool for a time window: devices with counts, selectors and topology, an optional start, a duration and a binding of hold, instance or node.
Resolver
The function Better IAM calls to learn about a resource it does not store. Compute's resolver answers every compute-* type from the authz projection in memory and hands other types to the host's own resolver.
Retry pushback
The delay a busy gateway attaches to a RESOURCE_EXHAUSTED refusal as the gRPC trailer grpc-retry-pushback-ms (and retry-after on the WebSocket path), jittered and scaled to the number of daemons it is refusing. bcd and the FakeDaemon wait exactly that long instead of their own back-off, so a power-on herd spreads over the window the gateway can admit.
Rollout
The controlled move of the fleet to one signed bcd release in waves (1%, 10%, 50%, 100% by default), within each pool's disruption budget, pausing by itself when too many nodes of a wave fail.
S
Sandbox
An isolated place to run untrusted code, served by sandboxes.create: one hosted VPS instance made from a per-tenant template (pool, flavor, image), with a time-to-live after which it is deleted, and optionally claimed from the template's warm pool of paused (or stopped) instances. Instance methods refuse a sandbox's instance. It can be snapshotted and restored, and sandboxes.exec reaches it over SSH through a tunnel, with no agent in the guest.
Sandbox SSH CA
The deployment's SSH certificate authority for sandboxes.exec, separate from the break-glass CA: it signs certificates of at most 15 minutes for the principal <account>@<instanceId>, and every sandbox instance's user data makes its sshd trust it for its own principal only.
Sandbox template
A tenant's recipe for sandboxes (sandboxTemplates.*): a hosted pool, a flavor, an image and the pool's runtime, optional user data, env as secret:// references, network (egress, private or none), TTL bounds and a warm pool size.
Session
The long-lived gRPC stream a daemon holds to one gateway, opened with Hello and answered with Welcome. Each new session increments the node's epoch, which fences the old one.
Shard lease
A lease that gives one worker or agent ownership of something, with a fencing epoch: shard:<n> for a slice of reconciler work, and likewise pool:<id>, site:<id>:boot, singleton:<job> and gateway:<id>.
Site
A boot and failure domain served by at least one site agent, of kind shared, dedicated or custom (a tenant's own hardware). Pools, nodes and join tokens each belong to exactly one site.
Site agent
bcd running as bcd site on a site's provisioning and BMC networks, stored as a node with role: 'site' and joined with a site token. It runs BMC operations (Redfish only today) and site.httpProxy, serves network boot (proxy DHCP, TFTP, iPXE scripts with signed discovery assertions) only to prepared machines while it holds the site's boot lease, and keeps a digest-verified image cache for the site's ramdisks.
SiteBoot lease
The lease site:<id>:boot that lets exactly one connected site agent serve network boot for its site; the standby is promoted only after it expires, under a new epoch.
SPIFFE ID
The URI name in every node certificate, spiffe://<trustDomain>/site/<siteId>/node/<nodeId>. Names come only from JoinService, never from the certificate request, and no tenant appears in them.
Spot
A reservation made with spot: true: placed like any other and billed as gpu.<model>.spot.hours, but preempted with a short notice (2 minutes by default) when a regular request needs its GPUs and nothing else fits.
Step
One persisted unit of a workflow, run on the control-plane, a site agent, the node or the ramdisk. An agent step is exactly one command, and await: 'rejoin' marks steps that end the agent's boot.
T
Taint
A named NoSchedule reason an operator sets on a node (taint:<key>), shown next to the reasons controllers write, to keep the node out of placement for a reason that should stay visible.
Tenant
A Better IAM tenantId: the root tenant is the platform, organizations are customers. Every tenant-scoped record carries its tenant, and a caller outside a request's tenant and the root tenant is refused before any database access.
Tunnel
A two-way byte stream between a caller and a shell, console, SSH server or TCP port on a node, carried over the session the node already holds to its gateway, so the node needs no inbound port.
U
Usage window
One row per allocation, hour and meter in usage_windows, such as gpu.h100.hours, written by the usage reconcilers every 5 minutes and sent to Better IAM billing with an idempotency key, so every retry is safe.
W
Warm pool
The instances a sandbox template keeps booted and then paused (or stopped on a runtime that cannot pause), so sandboxes.create can claim one after its own IAM decision without a new placement. Warm instances are charged to the tenant's quota and metered as vps.sandbox.warm until claimed.
Work queue
The table of (kind, key) wake-ups for reconcilers, written in the same transaction as the change that causes them. Enqueueing a key that is already queued bumps its generation instead of adding a row, so no wake-up is lost.
Workflow
A profile expanded for one target into persisted steps, run by the provision engine with retries, timeouts, failure and cleanup steps. A node runs at most one active workflow at a time.
Better Compute is created by Sean Filimon
Last updated