[github-actions]

agentgateway/agentgateway#4118 — feat(hbone): serve the metrics endpoint over HBONE

Docs versions: standalone/main, kubernetes/main

No code-path rule covers 5 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• crates/agentgateway/src/app.rs
• crates/agentgateway/src/lib.rs
• crates/agentgateway/src/management/hyper_helpers.rs
• crates/agentgateway/src/proxy/gateway.rs
• crates/agentgateway/src/proxy/tcpproxy.rs

What changes for users: Prometheus can scrape the proxy /metrics endpoint over HBONE when the stats listener is bound to all interfaces, such as 0.0.0.0:15020. A loopback-only stats listener is not exposed over HBONE. Standalone configs with an hbone: block can also omit hbone.poolUnusedReleaseTimeout.

What the docs now say: The Kubernetes data plane metrics page now states the HBONE scraping condition and that routes and policies do not apply to the metrics request. The standalone Prometheus page now tells readers to bind statsAddr to a non-loopback address when another workload scrapes the endpoint, such as through HBONE.

How agentgateway-4118 was drafted, and what was not verified

• Code PR: feat(hbone): serve the metrics endpoint over HBONE agentgateway#4118
• Code issue: HBONE: forward CONNECTs for the pod own non-listener ports to localhost agentgateway#4116
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main; documented in the development tree, which is where unreleased changes go.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add the HBONE metrics scraping behavior to the metrics pages named by the code-path targets.
• Learned: the code diff also fixes hbone.poolUnusedReleaseTimeout, but no authorized prose page owns standalone HBONE pool fields beyond generated schema coverage.
• Did: Updated the Kubernetes data plane metrics shared asset and the standalone Prometheus page; wrote a feature release-note proposal.

Why a documentation change is necessary

The pull request exposes the data plane metrics service through the HBONE path when the requested port matches the stats listener and that listener is bound on an unspecified address. The existing metrics pages explain direct scraping on port 15020, but they do not tell readers that ambient-mesh scraping can reach the same endpoint over HBONE or that loopback-bound stats listeners stay private. The diff also shows that the metrics request bypasses binds, routes, and policies, which matters to readers who expect normal gateway routing to apply.

What changed on disk

• assets/agw-docs/pages/observability/metrics/dataplane.md: Added a main-only note for Kubernetes data plane metrics over HBONE.
• content/docs/standalone/main/documentation/observability/metrics/prometheus.md: Added the standalone statsAddr binding requirement for scrapers in another workload.

How to verify this change

1. In an ambient-mesh environment, run an agentgateway proxy whose stats listener is bound to all interfaces on port 15020.
2. From a meshed scraper workload, query the proxy metrics endpoint.

   curl -s http://<proxy-pod-ip>:15020/metrics | grep agentgateway_build_info

   The output includes agentgateway_build_info.
3. Bind the stats listener to loopback, such as 127.0.0.1:15020, and repeat the scrape from the meshed workload. The metrics endpoint is not exposed over HBONE.

What was not verified

• The configuration was not applied to a cluster, so every command in this diff is unrun.
• Internal links are unchecked because Hugo was not run.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#4118 — feat(hbone): serve the metrics endpoint over HBONE

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Code issue: HBONE: forward CONNECTs for the pod own non-listener ports to localhost agentgateway#4116
• Summary (read from the body): - Expose metrics over HBONE
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 5 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • crates/agentgateway/src/app.rs
  • crates/agentgateway/src/lib.rs
  • crates/agentgateway/src/management/hyper_helpers.rs
  • crates/agentgateway/src/proxy/gateway.rs
  • crates/agentgateway/src/proxy/tcpproxy.rs

Release notes

This pull request also adds its release-note entries:

• content/docs/kubernetes/main/release-notes/release-notes.md: Metrics scraping over HBONE (feature, in a new 1.8 section)
• content/docs/standalone/main/release-notes/release-notes.md: Metrics scraping over HBONE (feature, in a new 1.8 section)

Check these release-note links and names. Each note is on its page, but a link may not reach the drafted content there, or a name may belong to the other mode:

• content/docs/kubernetes/main/release-notes/release-notes.md: feat(hbone): serve the metrics endpoint over HBONE agentgateway#4118's note links to /documentation/observability/metrics/, which in this tree is content/docs/kubernetes/main/documentation/observability/metrics/_index.md, a page this draft did not change. A note placed in more than one tree resolves its links in each one; check that the link reaches the drafted content here, or word the note for this tree.
• content/docs/kubernetes/main/release-notes/release-notes.md: feat(hbone): serve the metrics endpoint over HBONE agentgateway#4118's note names 0.0.0.0:15020, which content/docs/standalone/main mentions and content/docs/kubernetes/main does not. Check that this tree's readers can set it, or word the note for this mode.
• content/docs/standalone/main/release-notes/release-notes.md: feat(hbone): serve the metrics endpoint over HBONE agentgateway#4118's note links to /documentation/observability/metrics/, which in this tree is content/docs/standalone/main/documentation/observability/metrics/_index.md, a page this draft did not change. A note placed in more than one tree resolves its links in each one; check that the link reaches the drafted content here, or word the note for this tree.

Draft branch: pr-tracker-draft-agentgateway-4118

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	e336ff0
Status:	✅  Deploy successful!
Preview URL:	https://7f78dccc.agentproxy.pages.dev
Branch Preview URL:	https://pr-tracker-draft-agentgatewa-56aa.agentproxy.pages.dev

View logs

[kristin-kronstain-brown]

Moved this PR's release-notes entry to the combined release-notes PR, #1482, so the draft PRs stop conflicting on the release-notes pages. Review or change the entry there.