feat: give workloads an interface they can claim

[scotwells]

Compute asks for a network interface the way a pod asks for storage. It declares what an interface needs, and gets back an object carrying everything required to bring up a NIC.

Related to #164. The compute side has to move before that issue closes.

What a consumer writes

A workload declares its interface once, and every replica gets one of its own:

networkInterfaceClaimTemplates:
  - metadata:
      name: eth0
    spec:
      network:
        name: default
      ipFamilies:
        - IPv6
        - IPv4
      reclaimPolicy: Retain
      addresses:
        - class: public-unicast-ipv4

Nothing here names a subnet, a prefix length, or an address. A consumer names a kind of address and the platform decides the rest. This is the same shape a StatefulSet uses for storage, and it behaves the same way: one declaration, one claim per slot, each outliving the instance that fills it.

What they get back

The addresses land on the object compute already watches, so answering "what address did this instance get" costs no second lookup:

status:
  addresses:
    - family: IPv6
      address: 2001:db8:a001::/96
      primary: true
    - family: IPv4
      address: 10.128.0.2/32
  externalAddresses:
    - family: IPv4
      address: 198.51.100.11
  conditions:
    - type: Bound       status: "True"
    - type: Allocated   status: "True"
    - type: Programmed  status: "True"
    - type: Ready       status: "True"

Today Instance declares a field for the address, prints it as a column, and never fills it in. A consumer running a get sees a blank where the answer belongs. This fills it in.

Why allocation and programming are reported apart

An address that exists is not an address that carries traffic. Allocation happens as soon as a claim exists. Programming waits for the data plane. Reporting them together would release an instance before its packets can move, so they stay separate and readiness needs both.

What a provider reads

One object, no traversal:

spec:
  network:
    name: default
  interfaceName: eth0
  mtu: 1460
  addresses:
    - family: IPv6
      address: 2001:db8:a001::/96
      gateway: 2001:db8:a001::1
      primary: true
    - family: IPv4
      address: 10.128.0.2/32
      gateway: 10.128.0.1

A provider bringing up a NIC needs the address, the gateway, the MTU, and the network. Today it assembles those by walking four resources, which means those four cannot change without breaking every provider, and a new provider has to learn all of them to bring up one interface.

An address that survives its instance

An interface outlives the instance holding it. Under a retain policy, deleting a workload's claim leaves the interface in place still holding its addresses, and a replacement of the same slot binds it again and comes back on the same address.

Event	Delete	Retain
Instance replaced or rescheduled	same interface, same addresses	same
Scale down then back up	new interface, new addresses	same interface, same addresses
Workload deleted then recreated	new interface, new addresses	same interface, same addresses

An interface survives a redeploy on its own. Surviving a scale down takes retain.

What stops being anyone else's problem

1. Compute no longer creates network bindings or subnet claims, and no longer needs to know a network context exists.
2. Every instance gets its own interface and its own addresses. Today one allocation is shared across a whole deployment, so instances cannot have distinct addresses.
3. Providers read one resource rather than four.

When it cannot be satisfied

A claim that cannot bind says why. An exhausted pool, a family the network does not carry, and a namespace that names no project each report the cause rather than a generic not ready, because an instance stuck behind an unsatisfiable claim is a new way to be stuck and it needs to be legible.

Testing

The suites run against a real IPAM service in a two cluster environment, not a mock. Each one checks the addresses the operator publishes against the allocations IPAM actually holds, so a controller that invented an address would fail them. Two projects allocate through identical class names into separate address space, and neither can see the other's allocations.

Running IPAM for real found four defects that a mock would have passed, including one that leaked addresses and one that wedged a claim permanently. Each is fixed here.

Scope

The data plane path and the attachment that realizes an interface are a separate change. The programmed condition is defined and stays unknown until then. Nothing is removed: network bindings, subnet claims and subnets keep working, and providers move over on their own schedule.