docs: a network in every location it is used - #370
Merged
Conversation
A Network is defined in a consumer's project control plane, but instances run in edge cells that cannot read it. The cell-side claim reconciler needs two facts off the Network before it can serve a claim -- the address families it carries and its MTU -- and nothing carries them across, so every claim rejects and every instance stalls on its network scheduling gate. The proposal makes a network's presence in a location a declared thing: a consumer creates a NetworkBinding on the Karmada hub owned by itself, a hub-resident controller turns bindings for a (network, location) pair into one NetworkContext carrying the network's rules, and Karmada delivers it to the cell. Key changes: - Add docs/enhancements/network-in-every-location.md, tracking issue #369 - Resolve teardown vs retained addresses, cross-cluster garbage collection, staleness watches, and the ipFamilies default conflict - State which resource answers "can this workload run here"
The first draft told the story through compute workloads, which reads as if a workload deployment is the only thing that needs a network in a location. Load balancers, gateways, connectors, and infrastructure providers all need the same presence, and one of them is not a hub object. Key changes: - Frame the consumer as any resource attaching to a network in a place, with compute as the first one rather than the shape of the design - Add a consumer contract: create a binding, watch it, delete it, and never read the shared context to decide whether to proceed - Give consumers that cannot own a hub object their own section instead of an aside, and say plainly what guarantee they lose - Separate what reads a NetworkContext for the network's rules from what reads a binding for readiness - Rework the worked example to two consumer kinds sharing one presence
scotwells
changed the title
Karmada is an implementation of the federation control plane, not the name of the thing the design depends on. The proposal now refers to the federation control plane throughout, and defines "the hub" once as the short form used where the point is that bindings and contexts live in its namespaces. The consumer contract told a consumer to watch its binding for Ready without ever saying what the binding reports. Key changes: - Refer to the federation control plane rather than to Karmada - Add a binding status section: one Ready condition, the context reference as a breadcrumb, and the four reasons a binding is not ready - Say that every binding for a pair carries the same answer, and why - Say what the binding deliberately does not report: the consumer count, the network's rules, and data-plane programming
The binding is the only object a consumer watches, so a list of failure reasons is not enough. It needs the states in order, what moves between them, and what a consumer should do in each. Key changes: - Table every state including the Pending default, with the action each one calls for, and mark which faults the consumer can fix - Describe the happy path, the case where a second consumer skips the middle state, and the three ways Ready regresses - Say that a regression does not withdraw addresses already handed out, so a brief control plane fault is not read as a teardown signal - Say the binding never reports its own deletion, and that presence teardown is not a binding state - Propose spec.network and spec.location as immutable, since a mutated binding crosses between two shared presences with no state to describe it - Trim the failure table to the reasons the attaching resource reports
ecv
approved these changes
Aug 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
An enhancement proposal for #369: making a network present in every location it is used.
A network is declared in one project control plane. The things that attach to it run somewhere else, in places that cannot read that project. Nothing carries the network's rules across, so a component attaching to a network at a location cannot learn which address families it carries or what MTU its interfaces use.
What it proposes
A network's presence in a location becomes a declared thing.
NetworkBindingon the Karmada hub, tied to the lifetime of the resource that needs it.NetworkContextcarrying the network's families and MTU.A consumer is any resource attaching something to a network in a place. A compute workload deployment is the one that exists today. A load balancer, a gateway, a connector, and a provider standing up an attachment are the same shape, and none is a special case.
Consumers of different kinds share one presence and never learn about each other. Nothing counts by hand, because the count is a list.
What every consumer gets is the same guarantee: a network means the same thing in every location it reaches, and a change to it converges everywhere.
What it settles
Retained addresses. An address that outlives its consumer must not lose the network under it when the last declaration goes.
Garbage collection. Network deletion finds its contexts through an index that returns nothing once contexts live on the hub, which would delete a network and orphan every copy.
Staleness. A first attach should succeed when the network arrives, not on a 60 second retry, and an MTU change should reach what already exists.
The address family default. Networks default to IPv4 and consumers to IPv6, and the mismatch is a hard rejection, so the default case cannot bind.
Location authority. Two resources answer "can this run here" today, and they can disagree.
Consumers that cannot own a hub object. The project-plane consumers NSO has today get a weaker cleanup guarantee, and the proposal says so rather than assuming every consumer is a hub object.
What it does not do
No implementation. API shape and controller responsibilities only.
It also names the things it depends on and does not design: no NSO manager runs on any cell today, nothing seeds per-project IPAM objects, nothing sets
Programmed, and a consumer has no permission to create a binding on the hub.Part of #164. Completes the design in #360. The first consumer is datum-cloud/compute#112, with the addressing model in datum-cloud/compute#210.