Expose a second endpoint in the gateway actuator example and note path based routes

[gohri81-tech]

Closes gh-1265

The issue asked for two things on the Actuator API page: another endpoint in the management.endpoints.web.exposure.include example, and a note about root routes. Both are here now.

The example exposes gateway,health instead of gateway alone.

The note describes when a route with a path predicate is matched instead of an actuator endpoint:

• On a single port it is not. The actuator's handler mapping is ordered ahead of RoutePredicateHandlerMapping, whose order defaults to 1 (spring.cloud.gateway.server.webflux.handler-mapping.order), so a route with Path=/** does not prevent /actuator/gateway from being served.
• It is when the endpoints have been given their own management.server.port. The application port then stops serving them, while a route there whose predicate covers /actuator/** still matches and forwards those requests to its uri. getHandlerInternal only skips routing for requests arriving on the management port, so the endpoints stay reachable there.
• It is also when that order property has been lowered below the actuator handler mapping's, in which case routes are consulted first.

It closes with the two ways out: route the prefixes you actually want rather than /**, or give the endpoints their own management port. The actuator handler mapping's numeric order is deliberately not quoted, so the page does not go stale on a Boot internal.

My first attempt at this note explained the endpoint's reachability through the gateway's handler mapping, which @spencergibb rightly rejected: /gateway is an ordinary actuator endpoint registered in the same context, so that described the wrong thing, and the property name I quoted for the order no longer exists under that prefix. That note was dropped in 24ebcd7 and rewritten in 5253ab2 after his follow-up.

Documentation only, no code change.

One artefact I can't avoid through the web editor: the final |=== line shows as changed because the file has no trailing newline. Happy to redo the change locally if you would rather not carry it.

[spencergibb]

This doesn't make sense to me. Gateway actuator doesn't have anything to do with it's handler mapping. They are loaded in the same context as the regular actuator.

[gohri81-tech]

You're right, and I've removed the note (24ebcd7). The PR is now just the one line the issue actually asked for, management.endpoints.web.exposure.include=gateway,health.

Two things were wrong with what I wrote. The smaller one: I quoted spring.cloud.gateway.handler-mapping.order, but GatewayProperties.PREFIX is spring.cloud.gateway.server.webflux on main, so that property name doesn't exist any more. The bigger one is your point - the /gateway endpoint is an ordinary actuator endpoint registered by Boot's actuator infrastructure in the same context, so explaining its reachability through RoutePredicateHandlerMapping describes the wrong thing entirely. Framing standard Boot behaviour as gateway-specific would have been worse than saying nothing.

That leaves the other half of gh-1265 open, the "note or warning about root routes" the reporter asked for. I'd rather ask than guess again: is that worth documenting at all on this page, and if so would you want it phrased purely in Boot terms (actuator endpoints are mapped independently of the gateway routes, so a catch-all route does not affect them) with no mention of handler mappings or ordering? Happy to add that, or to leave the PR as the example change only and let the root-route part of the issue be closed separately.

One bit of noise I can't avoid through the web editor: it rewrites the final |=== line because the file has no trailing newline. Let me know if you want that reverted and I'll redo the change locally.

[spencergibb]

I see. I note about path-based routes that would match instead of actuator would be helpful. I suppose I was confused about the wording.

[gohri81-tech]

Thanks - that's added in 5253ab2, and this time the note only talks about the case you named, a path based route matching instead of the actuator endpoint, with no claim that the gateway is involved in mapping the endpoint itself.

What it says:

• On a single port the actuator's handler mapping is ordered ahead of RoutePredicateHandlerMapping (order 1 by default, from spring.cloud.gateway.server.webflux.handler-mapping.order), so a route with Path=/** does not prevent /actuator/gateway from being served.
• It does match instead of the endpoint when the endpoints have been moved to their own management.server.port, because the application port then stops serving them. getHandlerInternal only returns Mono.empty() for requests arriving on the management port, so on the application port a route whose predicate covers /actuator/** matches and forwards them to its uri.
• Or when that order property has been lowered below the actuator handler mapping's, in which case routes are consulted first.

And one line on what to do about it: list the prefixes you actually want to route instead of using /**, or give the endpoints their own management port.

I deliberately left out the actuator handler mapping's numeric order so the page does not go stale on a Boot internal - "ordered ahead of" is the part that matters to a reader.

The title and description are updated to cover both halves of gh-1265 again. Same caveat as before: I can't build the docs here, so please reword anything that isn't how you would put it, and the final |=== line still shows as changed because the file has no trailing newline.

[gohri81-tech]

A gentle nudge on this one when you have a moment. The note about path based routes was rewritten in 5253ab2 along the lines you suggested, so it now only describes the case you named and makes no claim that the gateway is involved in mapping the endpoint itself. The earlier review is still marked as requesting changes, so it would be good to know whether the new wording reads correctly to you.

Both halves of gh-1265 are covered now: the example exposes gateway,health, and the note is in place. Please reword anything that is not how you would put it, or let me know if you would rather drop the note and close that part of the issue separately. Thank you.