Reference
Glossary
Before you read: nothing — this is a reference. Keep it open next to any other page.
The words a newcomer meets in this repository, with the meaning they have in Delonix — which is
sometimes narrower than the general cloud-native meaning. Each entry points to where the term is
explained or implemented. Paths are relative to the repository root; file.rs::symbol names a
symbol inside that file.
Terms are in alphabetical order. For the general background, the kernel primitives (processes, namespaces, cgroups, file descriptors, signals) are taught in Linux foundations, and OCI, CRI, CNI and KVM as the engine uses them in Cloud native primer.
Adapter — A crate in crates/adapters/ that implements a port against a local mechanism: the
kernel (delonix-linux), the network dataplane (delonix-sdn), the OCI store (delonix-oci), the
local VM hypervisors (delonix-vm). An adapter may depend on foundation and context crates, never
on an interface crate. See: Layers,
scripts/arch_fitness.py::LAYERS.
ADR (Architecture Decision Record) — One Markdown file per structural decision, in docs/adr/,
named NNNN-title.md, written in English, before the code. An accepted ADR is never rewritten; a
new ADR supersedes it. See: docs/adr/README.md,
When to write an ADR.
Apply / plan / prune — The three verbs of declarative convergence. delonix plan shows what an
apply would change and changes nothing (--detailed-exitcode exits 2 when there are changes);
delonix apply converges the manifest; --prune also removes what the stack owns and the manifest
no longer declares, and never runs by default. See: crates/contexts/delonix-stack/src/reconcile.rs::plan,
Declarative reconciliation.
CAS (content-addressed storage) — The image blob store: each blob lives under
blobs/sha256/<hex> in the state root, addressed by its digest, so identical content is stored once.
Integrity is checked when content enters the store, not when it is read: a pull compares the
manifest, the config and each layer against the expected digest (verify_manifest_digest and the
digest comparisons in crates/adapters/delonix-oci/src/registry.rs). Cas::read is a plain file
read and does not re-hash; Cas::verify re-hashes on demand. See:
crates/adapters/delonix-oci/src/cas.rs::Cas,
State on disk.
CDI (Container Device Interface) — A CNCF spec describing how to expose a device (typically a
GPU) to a container. Delonix only consumes specs already generated by a vendor tool and turns
them into the same mounts and device nodes that -v/--device produce; it never discovers drivers
itself. See: crates/adapters/delonix-linux/src/cdi.rs.
cgroup delegation — The cgroup v2 mechanism that lets an unprivileged user manage a subtree of
cgroups. Without it, rootless resource limits (-m, --cpus) cannot be enforced; the engine
detects this and refuses a limit it could not apply rather than accepting it silently. A shell
opened over SSH is often not delegated; systemd-run --user --scope -p Delegate=yes gives one that
is. delonix system info shows the answer as cgroup2 delegated. See:
crates/adapters/delonix-linux/src/lib.rs::cgroup_limits_apply,
cgroups v2 and delegation,
cgroup delegation.
CNI (Container Network Interface) — The plugin standard Kubernetes uses to give a pod its
network. Delonix can run a node's CNI plugin chain against a named network namespace, which is how
a CRI pod sandbox gets its network. See: crates/adapters/delonix-sdn/src/cni.rs::attach_named_netns,
Container networking.
Contract (node) — The API of one node, defined in Protocol Buffers under proto/delonix/node/v1/
(package delonix.node.v1), with an OpenAPI document docs/api/openapi.yaml generated from it.
scripts/contract_gate.py guards formatting, lint, compatibility with the last tag and the
generated OpenAPI. It is a published contract; no server implements it yet. See:
Where the restructuring stands,
ADR-0040.
Control process — The restartable half of the rootless network infra: the engine binary started with the internal
arguments netns control (not a user-facing command) runs inside the namespaces held by the pin, listens on a 0600 unix control socket (accepting only
the engine's own uid) and performs attaches, publishes, firewall changes, DNS and DHCP one request
at a time. Killing it does not disturb running workloads; the next command restarts it. See:
crates/adapters/delonix-sdn/src/infra.rs::start_control, control_loop; Holder / pin.
CRI (Container Runtime Interface) — The gRPC API the kubelet uses to run pods. The
delonix-cri crate (binary delonix-cri) implements it on top of the engine, so a Kubernetes node
can use Delonix instead of another runtime. See: crates/interfaces/delonix-cri/,
Kubernetes.
Daemonless — No resident process is needed for the engine to work: each CLI command does its
work and exits. What must persist is owned by systemd (units, timers) or by a per-workload process
with a clear owner (a container's supervisor, the network pin). A new resident process needs an ADR.
See: «Identidade e fronteira do motor» in AGENTS.md,
Daemonless.
Delegated cgroup — See cgroup delegation.
DX_* exit class — Every engine error has a stable code string (DX_NOT_FOUND,
DX_INVALID_ARGUMENT, …) and maps to a process exit code decided from the error's type, never
from its (translated) message: for example 4 = no such resource, 5 = conflict. Scripts and
reconcilers branch on the number, not on the text. See:
crates/foundation/delonix-model/src/error.rs::Error::code,
crates/foundation/delonix-model/src/exitcode.rs::for_error,
Errors.
Fitness function — An automated check that the architecture still has the shape that was
decided. Here it is scripts/arch_fitness.py (CI job arch): layer direction, directory = layer,
dependency versions only in the root, no consumer names in code, and the debt ratchets. See:
Engine identity and boundaries,
Architecture rules.
Holder / pin — The long-lived half of the rootless network infra. The engine binary started with the internal
arguments netns pin creates a user, network and mount namespace and then just sleeps, holding them; its pidfile keeps the
historical name holder.pid, and every nsenter -t <pid> into the infra targets it. Before the
split into pin and control process, one "holder" did both jobs, which is why both words appear in
the code. See: crates/adapters/delonix-sdn/src/infra.rs::start_pin, pin_main,
crates/adapters/delonix-sdn/src/pin_userns.rs; Control process.
IPAM (IP address management) — Allocation of workload addresses inside a network's prefix.
Delonix keeps one lease file per prefix under ipam/ in the state root, and a reaper that reclaims
a lease only after it has been seen orphaned twice across a grace period. delonix network ipam ls
lists the leases. See: crates/adapters/delonix-sdn/src/ipam.rs::allocate, reap_orphan_leases;
the pure address arithmetic is in crates/foundation/delonix-net-rules/src/lib.rs.
Kind — The type of a declarative resource in a manifest (kind: Network, kind: Pod,
kind: VirtualMachine, …), grouped by apiVersion (core, compute, networking, gateway,
storage, artifact, infrastructure). The facts of every Kind — its group, whether it is
namespaced, whether it converges, its form — live in one table. delonix api-resources prints it;
delonix explain <Kind> documents its fields. See:
crates/contexts/delonix-stack/src/kinds.rs::FACTS, KindFacts.
LANG-01 — The language rule for code: identifiers, comments and user-facing messages are written
in English; Portuguese reaches the operator only through the translation catalogue
(bins/delonix-runtime-bin/data/pt.po, selected with --l18n pt). scripts/lang_ratchet.py counts
the Portuguese still in the code as a ratchet. See:
Language.
Layer (ADR-0040) — One of the architectural rings every crate belongs to: foundation, contexts,
adapters, providers, interfaces, binaries. Dependencies point inward, and the crate's directory
(crates/<layer>/) must match its declared layer. Not to be confused with an image layer (see
Overlay / lowerdir). See: Layers,
ADR-0040.
Lowering (sugar Kinds) — Rewriting a convenience Kind into the Kind that actually does the work
while the manifest is loaded, so the rest of the engine never sees it. Workload lowers to
Container/Pod/VirtualMachine, Dependency to NetworkPolicy; a VirtualMachine's spec.expose
lowers to an HTTPRoute named <vm>-expose (cmd/vm_expose.rs). The FORM column of
delonix api-resources says what each Kind becomes: primary, sugar → X (lowered), compat → X
(a foreign schema kept but compiled onto X), sunset → X (still applied as itself, successor
announced), aggregate (expands into the documents it contains, like Stack). See:
crates/contexts/delonix-stack/src/kinds.rs::Form, bins/delonix-runtime-bin/src/cmd/manifest.rs::load.
MCP (Model Context Protocol) — A protocol through which an AI client calls tools. delonix mcp
serve (crate delonix-mcp) is a local, tenancy-free control surface over stdio: a foreground
process started by the client for one session, trusted as the local uid running it — not a remote
management API. See: crates/interfaces/delonix-mcp/src/lib.rs,
ADR-0025.
microVM — A lightweight virtual machine with a minimal device model, booted fast, used where a
workload needs its own kernel. In Delonix the microVM hypervisor is Cloud Hypervisor; libvirt
(QEMU/KVM) is the other local backend. A Workload of type: microvm forces the Cloud Hypervisor
backend. See: Building microVMs,
ADR-0006.
NoCloud seed — A small ISO carrying cloud-init user-data, meta-data
and network-config, attached to a VM so its first boot applies hostname, SSH keys and network.
Delonix generates one per VM unless the image is an appliance that does not run cloud-init. See:
crates/adapters/delonix-vm/src/cloudinit.rs::generate_seed_iso,
Virtualization.
OCI (Open Container Initiative) — The standards for container images (image spec), for
distributing them from registries (distribution spec) and for running them (runtime spec). Delonix
pulls, builds, stores and pushes OCI images itself. See: crates/adapters/delonix-oci/,
OCI images.
Overlay / lowerdir — overlayfs stacks read-only image layers (the lowerdirs) under a per-container
writable upper directory. Delonix unpacks each image layer once under layers/ and every
container of that image shares them; the container directory holds upper/, work/, merged/ and
an overlay-lowers file listing the layers. The mount is done inside the container's own user
namespace with the new mount API, one lowerdir+ call per layer, so images with many layers do not
hit the classic mount(2) option-length limit. See:
crates/adapters/delonix-oci/src/overlay.rs::prepare_overlay,
crates/adapters/delonix-linux/src/lib.rs::mount_overlay_if_marked,
ADR-0037.
Port (hexagonal) — A trait that a use case needs and that an adapter or provider implements, so
the domain never names a concrete mechanism. Examples: VmBackend, and the compute ports
ImageStore, StorageProvider, NetworkProvider, WorkloadRuntime. See:
crates/contexts/delonix-compute/src/ports.rs, launch.rs,
Traits as ports.
Provider — A crate in crates/providers/ that implements a port against one remote management
API (today Proxmox VE and TrueNAS), bringing its own HTTP client. A new provider enters as an
implementation of a port, registered at the composition root — never as if provider == … in the
code — and needs an ADR. See: Providers,
ADR-0008, ADR-0009.
Ratchet — A gate on a debt counter that fails when the number rises and also when it
falls without the committed baseline being lowered in the same commit, so progress is recorded
and never lost. scripts/lang_ratchet.py (Portuguese in code) and the debt ratchets of
scripts/arch_fitness.py work this way; both have --list and --update. See:
Architecture rules.
Reconcile (3-way) — How plan/apply decide what to change without a state file. The three
sides are the manifest (desired), what is observed on the node (actual), and the last spec applied,
stored on the resource itself in the delonix.io/last-applied annotation. The third side separates
"you removed this field from the file" (revert it) from "someone set this by hand" (leave it).
See: crates/contexts/delonix-stack/src/reconcile.rs,
The declarative reconciler.
Rootless — Running as an unprivileged user, with privileges only inside user namespaces the engine creates. It is the default path in Delonix ("rootless-first"); root is an explicit opt-in. See: Linux namespaces and rootless operation.
slirp4netns — A user-space network stack that connects a rootless network namespace to the
host's network without privileges, and forwards host ports into it. Delonix runs a single
slirp4netns for the whole rootless network infra, with NAT and port publishing done by nftables
inside the infra namespace. See: crates/adapters/delonix-sdn/src/infra.rs,
Networking.
Stack — The set of resources one manifest owns. Ownership is a label on each resource,
delonix.io/stack, not a separate record: apply --prune and stack destroy only touch resources
carrying it, and a resource created by hand is never removed by them. Stack is also an aggregate
Kind that groups resources in one document. See:
crates/contexts/delonix-stack/src/reconcile.rs::STACK_LABEL.
State root — The directory holding all engine state as files (there is no database): DELONIX_ROOT
when set, otherwise ~/.local/share/delonix (or $XDG_DATA_HOME/delonix) for a user and
/var/lib/delonix for root. Network sockets live in a separate runtime directory
(DELONIX_NET_RUNTIME_DIR). Always set both when testing. Records under it are read, written and
locked by the delonix-state adapter. See:
bins/delonix-runtime-bin/src/cmd/util.rs::state_root,
crates/adapters/delonix-state/src/store.rs::Store::default_root,
State on disk,
Isolating the engine's state.
subuid / subgid — A range of user and group ids delegated to your user in /etc/subuid and
/etc/subgid. With it, a rootless user namespace maps many ids (written through newuidmap and
newgidmap); without it, only your own uid is mapped and images that use other users break. Files a
container writes as a mapped id are not owned by your uid on the host, which is why some operations
re-enter a mapped namespace. See: crates/adapters/delonix-sdn/src/pin_userns.rs,
Kernel requirements.
Supervisor — The process container run -d forks to be the real parent of the container: it
waits for the container, records its true exit status (and an OOMKilled reason), and applies the
--restart policy. Because it forks, it must be started from a single-threaded process; servers
re-exec a fresh delonix first. See: crates/adapters/delonix-linux/src/supervise.rs::run_supervised,
crates/adapters/delonix-linux/src/lib.rs::wait_and_record.
userns (user namespace) — The Linux namespace that maps user ids, giving a process root
privileges only over objects its namespace owns. It is the foundation of rootless operation, and on
recent Ubuntu it can be blocked by AppArmor for binaries outside the expected paths. See:
Linux namespaces,
AppArmor,
namespaces(7) and user_namespaces(7).
Verdict map — An nftables map from a key to a verdict (jump, accept, …), used so a packet
finds its rule in one lookup instead of walking one rule per workload. Delonix uses fwmap (a
workload address → its firewall chain) and netpair (a pair of bridges → an exemption that opens a
route between two networks). See: crates/adapters/delonix-sdn/src/infra.rs::FWMAP, NETPAIR_MAP.
VmBackend — The port every VM backend implements (boot, stop, destroy, is_running,
ip, pause and snapshots, …). Cloud Hypervisor and libvirt are registered by default; a remote
provider registers at the composition root. Registering does no I/O, and auto-detection filters on
the registration before building anything, so a remote backend only connects when it is chosen. See:
crates/adapters/delonix-vm/src/lib.rs::VmBackend, register_backend, select_backend,
Traits as ports.
Workload — Two related things. kind: Workload is a sugar Kind with spec.type:
container|pod|vm|microvm that lowers to the matching Kind at load time
(ADR-0001). delonix workload is the day-2 command group
(ls, describe, stop, rm) that lists and acts on containers and VMs together
(ADR-0002). See:
crates/contexts/delonix-stack/src/kinds.rs::WORKLOAD_LOWERS_TO,
bins/delonix-runtime-bin/src/cmd/workload.rs.
Worktree — A git worktree: a second working directory attached to the same repository, on its
own branch. Every task here gets its own, created from origin/main in a persistent directory
outside the repository (never /tmp), and is removed together with its branch at the end. See:
One worktree per task.
Next: Overview and reading paths — that is the end of the course; go back to the reading paths by role to pick what to deepen next.