feat: prefix-preserving dual-stack IPAM for pre-decided addresses

[scotwells]

Datum's networking layer decides an interface's addresses before the workload is scheduled — an IPv6 endpoint block, optionally an IPv4 address, each with a prefix length that means something. Galactic's CNI cannot currently be told to use them.

static_ip takes a single IPv6 address, forces a /64 mask and allocates no IPv4, so an externally decided /96 comes out as a /64. The only alternative is the pool path, where galactic re-decides the address and the platform's allocation becomes fiction.

This adds an addresses path that carries pre-decided addresses exactly: any number, both families, prefix length preserved, gateway honoured.

{
  "type": "galactic-ipam",
  "addresses": [
    {"address": "fd00:10:ff01:0:1::1/96", "gateway": "fd00:10:ff01::1"},
    {"address": "172.20.1.7/32", "gateway": "172.20.1.1"}
  ]
}

It reuses ipam.addresses, which was already declared and documented as vestigial, rather than inventing a key. static_ip is unchanged as the legacy single-address path. Combining addresses with static_ip or a subnet is a config error rather than a precedence question.

Galactic stores nothing on this path

The marker files under the pool allocators exist because galactic has had to be its own IPAM authority: the file is the allocation, and losing it means double-allocating. That authority is what produces #156, #328 and #329.

Nothing is allocated here, so there is nothing to persist. ADD parses and returns, DEL has nothing to release, and CHECK passes — exactly what static_ip already does two lines away, for the same reason. galactic-ipam is a delegated plugin and on the tap path galactic never configures a guest address at all, so there is nothing on-node for it to verify either.

An earlier revision of this PR added a reservation store. Removing it keeps the new path out of #328's scope rather than extending it.

Related

This is the CNI-side mechanism #197 needs. That issue's problem is two systems each believing they know what is allocated; a plugin that can be handed a decided address, and honour it exactly, is what lets an external authority own the pool. Consumed by the VPC controller in datum-cloud/cloud#6, which renders these addresses into the NAD from what NSO allocated (datum-cloud/network-services-operator#164).

Two existing issues, and how the new path stands against them:

• Nothing reclaims an IP allocation when DEL never runs #328 (nothing reclaims when DEL never runs) does not apply: this path writes no on-disk state, so there is nothing for a missed DEL to leak. The earlier revision of this PR did add such state; removing it keeps the new path out of that issue's scope entirely.
• In-place upgrade can hand a running pod's subnet to a new one #329 (in-place upgrade hands a live pod's subnet to a new one) does not apply either: this path allocates nothing, so there is no prior state to import and no pool view to start empty.

#156 is unchanged — this PR adds a path alongside the pool allocators rather than altering them.

🤖 Generated with Claude Code