Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 36 additions & 10 deletions docs/design/gateway-api-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -187,16 +187,42 @@ from a normal reconcile with complete current acceptance and nonempty current
targets.


The receipt also records the specific listener. Hostname or parent removal,
listener removal or ownership change, and route/Gateway deletion remove the
affected hostname immediately. Receipt identity rules remain unchanged: a route
with a replacement UID may inherit and rebind a receipt only when all its current
parent references are `Accepted=True`; a replacement under `False` or `Unknown`
cannot inherit it. Gateway UID and class and the listener digest must still
match for retention. A dynamic `allowedRoutes.namespaces.from: Selector` policy
cannot be re-proved without a namespace read, so neither unknown observation
nor route-level `Accepted=False` is retained under that policy. Independent
sibling listener bindings are evaluated separately.
The receipt also records the specific listener, including a SHA-256 digest of
the complete listener. Hostname or parent removal, listener removal, and
route/Gateway deletion remove the affected hostname immediately. A listener-only
digest change may refresh the receipt in place when the route namespace/name,
UID and generation, Gateway UID/class, parent reference, listener name, and
published hostname still match. Every route parent reference must have an
`Accepted=True` condition whose `observedGeneration` equals the current
`HTTPRoute.metadata.generation`. The hostname must still intersect the current
listener, and the listener must allow HTTPRoute and its namespace (`All`, or
`Same` including the default for a same-namespace route). With omitted or empty
`allowedRoutes.kinds`, only HTTP and HTTPS listeners allow HTTPRoute continuity.
`Selector` cannot re-prove continuity without a namespace read and therefore
cannot refresh a receipt.
Current targets must equal the established targets, or be temporarily absent
while the established nonempty targets are retained. This changes only the
receipt annotation, not the hostname intent or its generated RecordSets.

While the matching parent is `Unknown` (including absent or pending status),
the same listener-only continuity checks retain the hostname and the original
receipt without updating its digest. This requires the exact receipted route
UID and generation, not a pending newer route generation. Acceptance of every
parent for that same route generation subsequently refreshes the digest.
`Accepted=False` does not authorize this exception and still withdraws a
listener-digest conflict.

Receipt replay rules otherwise remain unchanged: a route with a replacement UID
may inherit and rebind a receipt only when all its parent references are
`Accepted=True` for its current route generation; a replacement under `False`
or `Unknown` cannot inherit it.
Same-UID pending-generation replay still requires the exact listener digest.
Gateway UID and class must match for retention. A dynamic
`allowedRoutes.namespaces.from: Selector` policy cannot be re-proved without a
namespace read, so neither unknown observation nor route-level `Accepted=False`
is retained under that policy. Independent sibling listener bindings are
evaluated separately. Fresh admission still trusts current route acceptance;
listener-refresh checks do not introduce a second Gateway admission controller.

The receipt records route namespace and name only so a parent-reference removal,
change, deletion, or final not-found reconciliation can requeue the previously
Expand Down
14 changes: 11 additions & 3 deletions internal/go/apps/gatewayendpoint/controllers/gateway/controller.go
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,10 @@ func (r *Reconciler) endpointRecordSetsForGateway(ctx context.Context, gateway *
publishedHostnames[hostname] = struct{}{}
}
}
// Missing addresses retain the established targets, not a replacement.
// A changed target cannot use listener-only receipt continuity.
unchangedTargets := existing != nil && len(existing.Spec.Targets) != 0 &&
(len(targets) == 0 || slices.Equal(targets, existing.Spec.Targets))
hostnames := map[string]struct{}{}
retainedHostnames := map[string]struct{}{}
receiptBindings := map[string]admissionReceiptBinding{}
Expand All @@ -284,15 +288,18 @@ func (r *Reconciler) endpointRecordSetsForGateway(ctx context.Context, gateway *
continue
}
acceptance := routeParentAcceptance(route, binding.ref)
allowListenerContinuity := (acceptance == parentAcceptanceUnknown ||
fullyAccepted && acceptance == parentAcceptanceAccepted) &&
unchangedTargets && listenerAllowsReceiptRefresh(route, gateway, binding.listener)
for _, hostname := range effectiveHostnamesForListener(route, binding.listener) {
match, hasReceipt := admissionReceiptBinding{}, false
conflictingReceipt := false
if _, published := publishedHostnames[hostname]; published {
match, hasReceipt = receipt.matchingBinding(route, gateway, binding, hostname)
match, hasReceipt = receipt.matchingBinding(route, gateway, binding, hostname, allowListenerContinuity)
conflictingReceipt = receipt.conflictsCurrentBinding(route, gateway, binding, hostname)
}
if fullyAccepted && acceptance == parentAcceptanceAccepted {
if conflictingReceipt {
if conflictingReceipt && !hasReceipt {
continue
}
hostnames[hostname] = struct{}{}
Expand All @@ -312,7 +319,8 @@ func (r *Reconciler) endpointRecordSetsForGateway(ctx context.Context, gateway *
continue
}
// Route admission controls serving, not publication intent.
// False and Unknown have the same receipt-retention boundary.
// Unknown may retain the old listener receipt until admission
// can refresh it; False still requires an exact listener digest.
if (acceptance != parentAcceptanceAccepted && !listenerAllowsUnknownRetention(route, gateway, binding.listener)) ||
!hasReceipt {
continue
Expand Down
15 changes: 15 additions & 0 deletions internal/go/apps/gatewayendpoint/controllers/gateway/httproute.go
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,21 @@ func listenerAllowsUnknownRetention(route *gatewayv1.HTTPRoute, gateway *gateway
}
}

func listenerAllowsReceiptRefresh(route *gatewayv1.HTTPRoute, gateway *gatewayv1.Gateway, listener gatewayv1.Listener) bool {
if !listenerAllowsUnknownRetention(route, gateway, listener) {
return false
}
if listener.AllowedRoutes == nil || len(listener.AllowedRoutes.Kinds) == 0 {
return listener.Protocol == gatewayv1.HTTPProtocolType || listener.Protocol == gatewayv1.HTTPSProtocolType
}
for _, kind := range listener.AllowedRoutes.Kinds {
if kind.Kind == "HTTPRoute" && (kind.Group == nil || *kind.Group == gatewayv1.GroupName) {
return true
}
}
return false
}

func parentRefKey(routeNamespace string, ref gatewayv1.ParentReference) string {
namespace := routeNamespace
if ref.Namespace != nil {
Expand Down
10 changes: 8 additions & 2 deletions internal/go/apps/gatewayendpoint/controllers/gateway/receipt.go
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ func newAdmissionReceiptBinding(route *gatewayv1.HTTPRoute, gateway *gatewayv1.G
}, true
}

func (receipt admissionReceipt) matchingBinding(route *gatewayv1.HTTPRoute, gateway *gatewayv1.Gateway, binding routeGatewayBinding, hostname string) (admissionReceiptBinding, bool) {
func (receipt admissionReceipt) matchingBinding(route *gatewayv1.HTTPRoute, gateway *gatewayv1.Gateway, binding routeGatewayBinding, hostname string, allowListenerContinuity bool) (admissionReceiptBinding, bool) {
listenerDigest := gatewayListenerDigest(binding.listener)
if route.UID == "" || route.Generation <= 0 || gateway.UID == "" || listenerDigest == "" {
return admissionReceiptBinding{}, false
Expand All @@ -105,10 +105,16 @@ func (receipt admissionReceipt) matchingBinding(route *gatewayv1.HTTPRoute, gate
candidate.GatewayClass != string(gateway.Spec.GatewayClassName) ||
candidate.ParentRef != parentRef ||
candidate.Listener != string(binding.listener.Name) ||
candidate.ListenerDigest != listenerDigest ||
!receiptHasHostname(candidate, hostname) {
continue
}
if candidate.ListenerDigest != listenerDigest &&
(!allowListenerContinuity || candidate.RouteUID != string(route.UID) || candidate.RouteGeneration != route.Generation) {
// Listener-only continuity cannot cross a route incarnation or
// generation. The caller refreshes only after current admission;
// an Unknown observation keeps this original receipt unchanged.
continue
}
if candidate.RouteUID == string(route.UID) {
if candidate.RouteGeneration == route.Generation {
return candidate, true
Expand Down
Loading
Loading