fix: stale HTTPRoute/GRPCRoute/TLSRoute/TCPRoute/UDPRoute status after gateway-only spec changes

[yuehaii]

What type of PR is this?
fix: stale HTTPRoute/GRPCRoute/TLSRoute/TCPRoute/UDPRoute/ status after gateway-only spec changes

Issue description
When a Gateway resource is updated without touching any Route resource (e.g. a listener hostname or allowedRoutes change), the Route's status.parents[*].conditions become stale, the observedGeneration field continues pointing at the old gateway generation instead of the new one.

Root cause
The bug only manifests as False→False (same outcome, only ObservedGeneration should advance). If the gateway update trigger a new route reconcile, GetGeneration() hasn't changed because the route was not modified. So the newly computed condition is byte-for-byte identical to what's already in the store and never trigger the status update.

Fix
Fixed the conformance test failure, by embed the gateway's generation into the 'Message' field. This guarantees that any gateway update produces a different 'Message' string, which breaks the DeepEqual gate

Verification

1. unit test

go test ./internal/gatewayapi/runner/... -v -run "TestHTTPRouteStatusStaleAfterAllowedRoutesChange" -count=1 2>&1 | tail -15
=== RUN TestHTTPRouteStatusStaleAfterAllowedRoutesChange
--- PASS: TestHTTPRouteStatusStaleAfterAllowedRoutesChange (0.15s)
PASS
1.777439888886663e+09 info gateway-api runner/runner.go:557 shutting down {"runner": "gateway-api"}
ok github.com/envoyproxy/gateway/internal/gatewayapi/runner 1.612s

go test ./internal/gatewayapi/runner/... -v -run TestHTTPRouteStatusStaleAfterListenerHostnameChange -count=1 2>&1 | tail -50
=== RUN TestHTTPRouteStatusStaleAfterListenerHostnameChange
--- PASS: TestHTTPRouteStatusStaleAfterListenerHostnameChange (0.15s)
PASS
1.7774398311383302e+09 info gateway-api runner/runner.go:557 shutting down {"runner": "gateway-api"}
ok github.com/envoyproxy/gateway/internal/gatewayapi/runner 1.663s

2. integration test

Step 1 — Bug Reproduction (unpatched controller)

Setup: Gateway listener on other.example.com, HTTPRoute hostname test.example.com (no match).

Step	Gateway gen	Accepted condition	observedGeneration
Create gateway + route	1	False / NoMatchingListenerHostname	1
Add matching listener (gateway-only edit)	2	False / NoMatchingListenerHostname ❌ (stale — should be True)	still 1 ❌

---

Step 2 — Fix Verification (patched controller)

Step	Gateway gen	Accepted condition	observedGeneration
Reset: only other.example.com listener	3	False / NoMatchingListenerHostname	3
Add another.example.com (same False outcome, only gen changes)	4	False / NoMatchingListenerHostname	4 ✅
Add matching test.example.com listener	5	True / Accepted	5 ✅

Which issue(s) this PR fixes:
Fixes #8861

Release Notes: Yes

[netlify]

✅ Deploy Preview for cerulean-figolla-1f9435 ready!

Name	Link
🔨 Latest commit	4f4d7bf
🔍 Latest deploy log	https://app.netlify.com/projects/cerulean-figolla-1f9435/deploys/6a491bd622791f00085ae52e
😎 Deploy Preview	https://deploy-preview-8876--cerulean-figolla-1f9435.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9f6c48c111

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[yuehaii]

hi @zirain @zhaohuabing @rudrakhp . Good day. I am not sure who is the maintainer of the related code in this pr. Can you please help review this pr when you are convenient? Thanks in advance.

[zirain]

a route may have multiple parents, what will happen then?

[yuehaii]

each parent's generation will be updated into the store's watchable map. so if there is one parent gateway generation change, it will trigger the route status update event.

[codecov]

Codecov Report

❌ Patch coverage is 70.83333% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.64%. Comparing base (4eb8bb6) to head (4f4d7bf).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/gatewayapi/helpers.go	0.00%	5 Missing ⚠️
internal/gatewayapi/route.go	89.47%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8876      +/-   ##
==========================================
+ Coverage   75.20%   75.64%   +0.44%     
==========================================
  Files         252      252              
  Lines       41049    41483     +434     
==========================================
+ Hits        30871    31380     +509     
+ Misses       8086     7945     -141     
- Partials     2092     2158      +66     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[yuehaii]

working on the conformance test failure

[yuehaii]

I have fixed the conformance test failure, by embed the gateway's generation into the 'Message' field. @zirain , can you please help review again? this guarantees that any gateway update produces a different 'Message' string, which breaks the DeepEqual gate at

gateway/internal/gatewayapi/status/conditions.go

Line 39 in cbb4337

if !reflect.DeepEqual(conditions[j], update) {

[zirain]

can you fix the conlict and add a e2e for this?

[arkodg]

this is a bug, but the fix doesnt look right

if a Gateway does not attach to a Route anymore, Envoy Gateway should remove any status created by it

1. We delete status keys in

   gateway/internal/gatewayapi/runner/runner.go

   Line 620 in cbb4337

   // Delete status keys

but we dont update status for it

gateway/internal/provider/kubernetes/status.go

Line 95 in cbb4337

if update.Delete {

this is something we should do in the provider layer

[yuehaii]

this is a bug, but the fix doesnt look right

if a Gateway does not attach to a Route anymore, Envoy Gateway should remove any status created by it

1. We delete status keys in

   gateway/internal/gatewayapi/runner/runner.go

   Line 620 in cbb4337

   // Delete status keys

but we dont update status for it

gateway/internal/provider/kubernetes/status.go

Line 95 in cbb4337

if update.Delete {

this is something we should do in the provider layer

thanks for the input. when the gateway's host is updated, the subscription will receives an update with update.Delete = false. so the 'update.Delete == true' seems unrelated with normal reconcile issue for any normal gateway update.

the 'update.Delete' is set to true only when an entry is explicitly removed from the map, e.g. route deleted from cluster. as you indicated, this happens only in deleteAllKeys() when 'r.ProviderResources.ListenerSetStatuses.Delete(key)' been called.

please let me know if I miss anything.

[yuehaii]

I added an e2e test. But it always PASS even without the fix.

go test -v -tags e2e -timeout 10m ./e2e --gateway-class=envoy-gateway -run-test HTTPRouteStaleStatus
….
--- PASS: TestE2E/HTTPRouteStaleStatus (3.38s)
--- PASS: TestE2E/HTTPRouteStaleStatus/route_initially_rejected_due_to_hostname_mismatch (0.24s)
--- PASS: TestE2E/HTTPRouteStaleStatus/gateway_updated_to_add_matching_listener (0.48s)
--- PASS: TestE2E/HTTPRouteStaleStatus/route_status_updated_to_Accepted=True_after_gateway_change (0.24s)
--- PASS: TestE2E/HTTPRouteStaleStatus/condition_message_contains_gateway_generation (0.48s)

I launched the integration test again with envoy-gateway v1.7.0. But I can't reproduce the issue.
After adding one more listener marching the http route hostname. The http route status been updated as expected.

kubectl get HTTPRoute -A
	NAMESPACE              NAME               HOSTNAMES                 AGE
	envoy-gateway-system   no-match-route-1   ["route-1.example.com"]   78s
	envoy-gateway-system   no-match-route-2   ["route-2.example.com"]   78s
	envoy-gateway-system   no-match-route-3   ["route-3.example.com"]   77s
	envoy-gateway-system   no-match-route-4   ["route-4.example.com"]   77s
	envoy-gateway-system   no-match-route-5   ["route-5.example.com"]   76s

// before updating the listener
kubectl get gateway multi-listener-gw -n envoy-gateway-system -o jsonpath='{range .spec.listeners[*]}name={.name} port={.port} protocol={.protocol} hostname={.hostname}{"\n"}{end}' 
	name=listener-a port=8880 protocol=HTTP hostname=listener-a.example.com
	name=listener-b port=8881 protocol=HTTP hostname=listener-b.example.com
	name=listener-c port=8882 protocol=HTTP hostname=listener-c.example.com
kubectl describe HTTPRoute no-match-route-1 -n envoy-gateway-system 
	Name:         no-match-route-1
	Namespace:    envoy-gateway-system
	Labels:       <none>
	Annotations:  <none>
	API Version:  gateway.networking.k8s.io/v1
	Kind:         HTTPRoute
	Metadata:
	  Creation Timestamp:  2026-05-12T01:56:13Z
	  Generation:          1
	  Resource Version:    153153
	  UID:                 d7cc4ac3-1458-430a-895f-5ee0c18fef60
	Spec:
	  Hostnames:
	    route-1.example.com
	  Parent Refs:
	    Group:  gateway.networking.k8s.io
	    Kind:   Gateway
	    Name:   multi-listener-gw
	  Rules:
	    Backend Refs:
	      Group:   
	      Kind:    Service
	      Name:    envoy-gateway
	      Port:    80
	      Weight:  1
	    Matches:
	      Path:
	        Type:   PathPrefix
	        Value:  /route-1
	Status:
	  Parents:
	    Conditions:
	      Last Transition Time:  2026-05-12T01:56:13Z
	      Message:               There were no hostname intersections between the HTTPRoute and this parent ref's Listener(s).
	      Observed Generation:   1
	      Reason:                NoMatchingListenerHostname
	      Status:                False
	      Type:                  Accepted
	      Last Transition Time:  2026-05-12T01:56:13Z
	      Message:               Failed to process route rule 0 backendRef 0: TCP Port 80 not found on Service envoy-gateway-system/envoy-gateway.
	      Observed Generation:   1
	      Reason:                PortNotFound
	      Status:                False
	      Type:                  ResolvedRefs
	    Controller Name:         gateway.envoyproxy.io/gatewayclass-controller
	    Parent Ref:
	      Group:  gateway.networking.k8s.io
	      Kind:   Gateway
	      Name:   multi-listener-gw
	Events:       <none>

// after listener been updated
kubectl get gateway multi-listener-gw -n envoy-gateway-system -o jsonpath='{range .spec.listeners[*]}name={.name} port={.port} protocol={.protocol} hostname={.hostname}{"\n"}{end}' 
	name=listener-route-1 port=8880 protocol=HTTP hostname=route-1.example.com
	name=listener-a port=8880 protocol=HTTP hostname=listener-a.example.com
	name=listener-b port=8881 protocol=HTTP hostname=listener-b.example.com
	name=listener-c port=8882 protocol=HTTP hostname=listener-c.example.com
kubectl describe HTTPRoute no-match-route-1 -n envoy-gateway-system 
	Name:         no-match-route-1
	Namespace:    envoy-gateway-system
	Labels:       <none>
	Annotations:  <none>
	API Version:  gateway.networking.k8s.io/v1
	Kind:         HTTPRoute
	Metadata:
	  Creation Timestamp:  2026-05-12T01:56:13Z
	  Generation:          1
	  Resource Version:    155492
	  UID:                 d7cc4ac3-1458-430a-895f-5ee0c18fef60
	Spec:
	  Hostnames:
	    route-1.example.com
	  Parent Refs:
	    Group:  gateway.networking.k8s.io
	    Kind:   Gateway
	    Name:   multi-listener-gw
	  Rules:
	    Backend Refs:
	      Group:   
	      Kind:    Service
	      Name:    envoy-gateway
	      Port:    80
	      Weight:  1
	    Matches:
	      Path:
	        Type:   PathPrefix
	        Value:  /route-1
	Status:
	  Parents:
	    Conditions:
	      Last Transition Time:  2026-05-12T02:01:14Z
	      Message:               Route is accepted
	      Observed Generation:   1
	      Reason:                Accepted
	      Status:                True
	      Type:                  Accepted
	      Last Transition Time:  2026-05-12T02:01:14Z
	      Message:               Failed to process route rule 0 backendRef 0: TCP Port 80 not found on Service envoy-gateway-system/envoy-gateway.
	      Observed Generation:   1
	      Reason:                PortNotFound
	      Status:                False
	      Type:                  ResolvedRefs
	    Controller Name:         gateway.envoyproxy.io/gatewayclass-controller
	    Parent Ref:
	      Group:  gateway.networking.k8s.io
	      Kind:   Gateway
	      Name:   multi-listener-gw
	Events:       <none>

[github-actions]

This pull request has been automatically marked as stale because it has not had activity in the last 30 days. Please feel free to give a status update now, ping for review, when it's ready. Thank you for your contributions!

[zirain]

@yuehaii can you rebase this one with main?

[zirain]

can you rebase with main correctly, I think that would also make the DCO happy.

[yuehaii]

error: Get "http://172.18.0.205:8080/bar": dial tcp 172.18.0.205:8080: connect: connection refused, not counting the round trip

/retest

[yuehaii]

can you rebase with main correctly, I think that would also make the DCO happy.

hi @zirain , good morning. I have rebased the code and fixed the CI failures. could you please review this pr again when it is convenient? thanks.

[arkodg]

thanks for the input. when the gateway's host is updated, the subscription will receives an update with update.Delete = false. so the 'update.Delete == true' seems unrelated with normal reconcile issue for any normal gateway update.

the 'update.Delete' is set to true only when an entry is explicitly removed from the map, e.g. route deleted from cluster. as you indicated, this happens only in deleteAllKeys() when 'r.ProviderResources.ListenerSetStatuses.Delete(key)' been called.

please let me know if I miss anything.

thanks for the correction, but this is the area of the code that needs to be fixed

gateway/internal/provider/kubernetes/status.go

Line 26 in dc73f48

func (r *gatewayAPIReconciler) updateStatusFromSubscriptions(ctx context.Context, extensionManagerEnabled bool) {

[yuehaii]

thanks for the input. when the gateway's host is updated, the subscription will receives an update with update.Delete = false. so the 'update.Delete == true' seems unrelated with normal reconcile issue for any normal gateway update.
the 'update.Delete' is set to true only when an entry is explicitly removed from the map, e.g. route deleted from cluster. as you indicated, this happens only in deleteAllKeys() when 'r.ProviderResources.ListenerSetStatuses.Delete(key)' been called.
please let me know if I miss anything.

thanks for the correction, but this is the area of the code that needs to be fixed

gateway/internal/provider/kubernetes/status.go

Line 26 in dc73f48

func (r *gatewayAPIReconciler) updateStatusFromSubscriptions(ctx context.Context, extensionManagerEnabled bool) {

The stale status problem is that when a gateway-only change happens, the watchable DeepEqual gate suppresses the update before it even reaches updateStatusFromSubscriptions. So updateStatusFromSubscriptions in status.go never gets called.
The fix must happen before Store() is called, so the stored value differs from the previous one even when the condition outcome is the same.
The cleanest fix would be at the runner level: after translating, compare the new status with the previously stored status and if the Gateway generation increased, touch the status (e.g. set a generation aware field) to ensure DeepEqual returns false and the update flows through.