Skip to content

feat(operator): derive endpoint readiness from Gateway route acceptance - #258

Open
dcmcand wants to merge 1 commit into
mainfrom
feat/233-route-acceptance-core
Open

dcmcand wants to merge 1 commit into
mainfrom
feat/233-route-acceptance-core

Conversation

@dcmcand

@dcmcand dcmcand commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Slice 1: Route acceptance can be read and turned into a condition

Part of #233. Today an endpoint condition says Applied as soon as the AIGatewayRoute is written, even when the Gateway rejects the generated HTTPRoute (for example a missing listener gives Accepted=False/NoMatchingParent). This PR adds a tested reader and derivation that turn the applied AIGatewayRoute plus its generated HTTPRoute into the endpoint condition, and teaches the requeue and failure helpers the new reasons. Nothing calls them yet, so reconciler behavior is unchanged; the PassthroughModel and LLMModel reconcilers adopt them in the next two PRs of this stack.

Spec / plan: design notes for #233 (kept outside the repo); this is slice 1 of 3.
Contracts touched: gatewayRequeue, hasGatewayFailure, phaseWithGatewayFailure (unchanged, picks up RouteNotAccepted), endpointCondition, readRouteAcceptance, routeAcceptanceCondition. Recorded in the new docs/architecture/contracts.md.
Depends on: #173

What changes

  • readRouteAcceptance gets the HTTPRoute of the same name, treats it as stale unless its parentRef and hostnames still match the AIGatewayRoute, and uses the matching status.parents[] entry's Accepted condition only when its observedGeneration equals the HTTPRoute generation.
  • routeAcceptanceCondition: True/Applied when accepted; otherwise Unknown/RoutePending while a 2 minute creation window or previous-condition window is open, then False/RouteNotAccepted naming the Gateway and listener (with the Envoy Gateway reason, or the AI Gateway message when there is one).
  • endpointCondition: keeps ApplyFailed / GatewayCRDUnavailable; other read errors are Unknown/RouteStatusUnreadable, or keep an existing RouteNotAccepted with the error appended once; lastTransitionTime comes from an injected clock.
  • gatewayRequeue keys on reason at any status and returns the shortest interval: RoutePending 5 s, GatewayCRDUnavailable 15 s, RouteStatusUnreadable 15 s, RouteNotAccepted and ApplyFailed 1 min. hasGatewayFailure counts RouteNotAccepted but not the pending or unreadable reasons. Existing inputs give existing outputs.
  • AGENTS.md, docs/architecture/contracts.md, docs/architecture/patterns.md.

Validation

Step Command / action Result
unit + envtest cd operator && make test exit 0, all packages ok
new tests go test ./internal/controller/ -run 'TestGatewayRequeue|TestPhaseWithGatewayFailure|TestShortestRequeue|TestReadRouteAcceptance|TestRouteAcceptanceCondition|TestEndpointCondition' -v all PASS; existing TestGatewayRequeue rows untouched (0 removed lines in conditions_test.go)
lint golangci-lint v2.4.0 under Go 1.24.5, as lint.yaml runs it 0 issues.
live pre-flight fresh NIC Hetzner cluster, AI Gateway v1.1.0, Envoy Gateway v1.9.1, a PassthroughModel see below

Live pre-flight, checking the assumptions the reader relies on:

  • The apply response carries creationTimestamp and status (kubectl replace -o yaml on the AIGatewayRoute).
  • The generated HTTPRoute's spec.parentRefs, spec.hostnames and status.parents[].parentRef match the AIGatewayRoute's exactly; parentRef.namespace is present in status.
  • After a rule change, HTTPRoute generation and the Accepted observedGeneration both moved 1 -> 2 within 2 s.
  • HTTPRoute names equal AIGatewayRoute names in the same namespace.
  • The motivating bug, observed live: for about 5 minutes the PassthroughModel reported InternalEndpointReady=True/Applied while the HTTPRoute was Accepted=False/NoMatchingParent because the llm-internal-https listener was missing.

@dcmcand
dcmcand added this pull request to stack #259 November 20, 2026 11:19
@github-actions

Copy link
Copy Markdown

📄 Docs preview for feat/233-route-acceptance-core:
https://feat-233-route-acceptance-co.llm-serving-pack.pages.dev

@jbouder jbouder left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

Base automatically changed from fix/llmmodel-surface-missing-crd to main November 20, 2026 16:09
Add the pieces that turn an applied AIGatewayRoute into an endpoint
condition based on whether its Gateway accepted the generated HTTPRoute.
Nothing calls them yet, so reconciler behavior is unchanged.

- readRouteAcceptance gets the HTTPRoute of the same name, checks that it
  still mirrors the route's parentRef and hostnames, and takes the
  Accepted condition of the matching status.parents entry only when its
  observedGeneration is current. It also picks up the AIGatewayRoute's
  NotAccepted message.
- routeAcceptanceCondition reports True/Applied when accepted, otherwise
  Unknown/RoutePending while a 2 minute creation window or previous
  condition window is open, then False/RouteNotAccepted naming the
  Gateway and listener.
- endpointCondition keeps ApplyFailed and GatewayCRDUnavailable as
  before, reports other read errors as Unknown/RouteStatusUnreadable
  (or keeps a RouteNotAccepted latch with the error appended once), and
  stamps lastTransitionTime from an injected clock.
- gatewayRequeue now keys on reason at any status and returns the
  shortest interval (RoutePending 5s, RouteStatusUnreadable 15s,
  RouteNotAccepted 1m). hasGatewayFailure becomes its own predicate and
  counts RouteNotAccepted, but not the pending or unreadable reasons.
- Document the contracts and patterns in docs/architecture and point
  AGENTS.md at them.
@dcmcand
dcmcand force-pushed the feat/233-route-acceptance-core branch from c80838c to 8274d28 Compare November 20, 2026 16:09
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