Skip to content

feat(cni): record the host device when the NAD is written - #21

Merged
scotwells merged 1 commit into
mainfrom
feat/nad-host-interface-at-creation
Sep 15, 2026
Merged

scotwells merged 1 commit into
mainfrom
feat/nad-host-interface-at-creation

Conversation

@scotwells

Copy link
Copy Markdown
Collaborator

Unikernel workloads start and then serve nothing: requests to them time out while the instance reports healthy in the API and the console. The runtime has to name its host device in the same request that asks for the interface, but the device name was only recorded by the data plane during the CNI add that creates the device — after the runtime has already had to decide. Finding nothing to read, it falls back to a name derived from its own container identifier, which matches no device that exists, and the guest boots with no interface at all. This records the name when the attachment definition is written, which is the first moment it is knowable.

The name is derived from the VPC and the attachment identifier, both of which this controller already holds at that point, and it already computes the same value for the attachment's status. The data plane writes the same key from the same inputs during the add, so the two always agree and the later write is a no-op. General purpose workloads are unaffected because their hypervisor is handed the device explicitly rather than having to name it.

Test plan

  • A newly created attachment definition carries the host interface annotation before any workload is scheduled against it
  • The recorded name matches what the data plane creates for the same attachment
  • A unikernel guest reaches a running state with a working interface rather than stopping shortly after boot
  • Veth attachments and general purpose workloads are unchanged and keep serving traffic

Notes for review

This is deliberately testable in isolation rather than assumed. It is not yet confirmed that the runtime reads this key when it chooses the device name — that component is closed source, it logs nothing on a successful read, and two attempts to prove it by hand on a live cell were inconclusive because the window between the definition being written and the request being issued is well under a second. The structural evidence is mixed: the runtime demonstrably reads this definition and hard-fails when a sibling key is absent, which suggests it does consult it; but its own debug output shows the interface name being derived from the container identifier before the add is issued, which suggests it may not. Landing this makes the annotation present early enough that the question can be answered by observation on a cell instead of by racing it.

If the runtime turns out to ignore the key, this change is still correct and costs nothing: the definition becomes self-describing at creation, and anything else that wants the device name can read it without waiting for the add.

Relates to datum-cloud/galactic#563, which fixed a separate missing key on the same annotation.

The host device name is derived from the VPC and the attachment
identifier, both of which this controller holds when it writes the
attachment definition. Until now it was recorded only by the data plane,
during the CNI ADD that creates the device, which is too late for a
runtime that has to name the device in the same request that asks for the
interface. Such a runtime finds nothing to read and falls back to a name
of its own, which matches no device that exists.

Writing the name when the definition is written makes it a prediction the
ADD later fulfils rather than a fact only the ADD can report. The data
plane writes the same key from the same inputs, so the two always agree
and the later write is a no-op.

Key changes:
- Record the host interface name on the attachment definition from the
  controller that creates it
- Pin the annotation key in a test: it is a contract with the data plane
  and with the runtime that reads it, and nothing else here would fail if
  it were renamed
@scotwells
scotwells requested a review from a team as a code owner September 15, 2026 21:24
@scotwells
scotwells merged commit 4387dc5 into main Sep 15, 2026
8 checks passed
@scotwells
scotwells deleted the feat/nad-host-interface-at-creation branch September 15, 2026 21:33
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