Decision record · ADR
ADR-0074: Resolve a machine's host once and render its address everywhere
Status: accepted | Date: 2026-11-07
References: RFC-0002, RFC-0004, ADR-0073
Context
Section titled “Context”A machine binding’s host was passed unchanged into every rendered address: the Engine’s listen address, readiness, metrics, reset, and conditioning URLs, AIPerf’s endpoint, INFERLAB_SERVE_BASE_URL, and a multi-host replica’s rendezvous address. Each consumer then resolved the name itself, with its own resolver. A downstream workspace whose machine’s own hostname resolved through /etc/hosts to 127.0.1.1 saw the Engine bind and readiness succeed on that address while AIPerf, resolving the same name to the machine’s network address, was refused: the server was ready and every Bench failed in warmup with an error that named neither address. Nothing defined whether host was a name or an address, or whose resolution counted, so one fact had as many authorities as consumers.
Decision
Section titled “Decision”Resolution looks up each used machine’s host once, on the machine running InferLab, through the system resolver, takes the first IPv4 address it returns, or the first IPv6 address when there is none, and renders that address in every listen address, endpoint, named port, and client target for the machine; an IP literal is used as written, and an IPv6 address is bracketed wherever it is joined with a port. IPv4 wins on a dual-stack name because pinning one address removes the fallback a client had when it tried each result of its own lookup, and the external Engines, stores, and Gateways InferLab launches are not all known to accept IPv6. Records and dry-run carry the declared host beside its address, and a name that does not resolve fails resolution naming the machine. A loopback address on a server that uses an SSH machine warns when the server starts, naming the machine, its host, and the address: only processes and clients on this machine reach it, which holds for an SSH launch exactly when its target is this machine, and InferLab cannot observe that from the target string, so a rejection would refuse a valid SSH-to-self launch. The lookup runs through getent ahosts, which applies the same name-service configuration as the system resolver and which tests replace on PATH like the other probed tools.
Consequences
Section titled “Consequences”Every consumer of a machine’s address agrees by construction, so readiness can no longer pass on an address the measurement client cannot reach, and the downstream configuration runs unchanged on 127.0.1.1. A machine whose name resolves to loopback on the InferLab machine is named in a warning at start when a server spans SSH machines, before a member fails to reach host 0; the warning does not stop the launch. Records show the address actually used. The resolution is the InferLab machine’s view: a name that a remote machine resolves differently, other than to loopback, is not detected, and an operator who needs a specific interface writes that address as host. A machine whose name has only IPv6 addresses is served on IPv6, which works only where the Engine, store, and Gateway accept a bracketed IPv6 address; a dual-stack machine keeps IPv4.
Alternatives Considered
Section titled “Alternatives Considered”Look up each machine’s host once on the InferLab machine and render the address everywhere (accepted)
Section titled “Look up each machine’s host once on the InferLab machine and render the address everywhere (accepted)”Require an IP address as host in every machine binding (rejected)
Section titled “Require an IP address as host in every machine binding (rejected)”- Cons: Breaks every binding written with a name and makes bindings harder to read and move
Keep host names and fail when the control plane’s and the measurement client’s resolutions disagree (rejected)
Section titled “Keep host names and fail when the control plane’s and the measurement client’s resolutions disagree (rejected)”- Cons: Keeps one authority per consumer and adds a resolution on the Python side only to compare results
Keep host names and only warn when a host resolves to loopback (rejected)
Section titled “Keep host names and only warn when a host resolves to loopback (rejected)”- Cons: Leaves readiness and the measurement client free to disagree, which is the reported failure
Take the resolver’s first address whatever its family (rejected)
Section titled “Take the resolver’s first address whatever its family (rejected)”- Cons: Moves a dual-stack machine from IPv4 to IPv6 without the per-client fallback a name lookup gave, onto components not known to accept IPv6
Reject a loopback address whenever the server uses an SSH machine (rejected)
Section titled “Reject a loopback address whenever the server uses an SSH machine (rejected)”- Cons: Refuses a valid SSH launch whose target is this machine, which InferLab cannot tell apart from a remote one