From 0a6c29d567cfcaecab46c9962eacc424a5e3aa07 Mon Sep 17 00:00:00 2001 From: guido lena cota Date: Mon, 29 Oct 2018 11:35:53 +0100 Subject: [PATCH 1/6] Create outline of Actuator API section --- .../main/asciidoc/spring-cloud-gateway.adoc | 65 ++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index f19defc2..65bf5cb2 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -1086,7 +1086,70 @@ In the example above, CORS requests will be allowed from requests that originate == Actuator API -TODO: document the `/gateway` actuator endpoint +The `/gateway` actuator endpoint allows to monitor and interact with a Spring Cloud Gateway application. To be remotely accessible, the endpoint has to be https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-enabling-endpoints[enabled] and https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-exposing-endpoints[exposed via HTTP or JMX] in the application properties. + +.application.properties +[source,properties] +---- +management.endpoint.gateway.enabled=true # default value +management.endpoints.web.exposure.include=gateway +---- + +=== Retrieving the filters applied to the routes +TODO: GET `/gateway/globalfilters`, GET `/gateway/routefilters` + +=== Refreshing +TODO: POST `/gateway/refresh` + +=== Retrieving the routes defined in the gateway +TODO: GET `/gateway/routes` + +=== Retrieving information about a particular route +TODO: GET `/gateway/routes/{id}`, GET `/gateway/routes/{id}/combinedfilters` + +=== Updating and deleting a particular route +TODO: POST `/gateway/routes/{id}` DELETE `/gateway/routes/{id}` + +=== List of all endpoints +The table below summarises the Spring Cloud Gateway actuator endpoints. Note that each endpoint has `/actuator/gateway` as the base-path. + +[cols="2,2,5"] +|=== +| ID | HTTP Method | Description + +|`globalfilters` +|GET +| Displays the list of <> applied to the routes. + +|`routefilters` +|GET +| Displays the list of <> applied to a particular route. + +|`refresh` +|POST +| TODO + +|`routes` +|GET +| Displays the list of routes defined in the gateway. + +|`routes/{id}` +|GET +| Displays information about a particular route. + +|`routes/{id}/combinedfilters` +|GET +| TODO + +|`routes/{id}` +|POST +| Add a new route to the gateway. + +|`routes/{id}` +|DELETE +| Remove an existing route from the gateway. + +|=== == Developer Guide From 1ebb00ddf383d95f393aa3d4f2276e6d96b3be70 Mon Sep 17 00:00:00 2001 From: Guido Lena Cota Date: Sat, 3 Nov 2018 16:49:42 +0100 Subject: [PATCH 2/6] Add documentation for /gateway/*filters endpoints --- .../main/asciidoc/spring-cloud-gateway.adoc | 37 +++++++++++++++++-- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index 65bf5cb2..e94dd3b6 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -1095,8 +1095,37 @@ management.endpoint.gateway.enabled=true # default value management.endpoints.web.exposure.include=gateway ---- -=== Retrieving the filters applied to the routes -TODO: GET `/gateway/globalfilters`, GET `/gateway/routefilters` +=== Retrieving route filters +==== Global Filters +To retrieve the <> applied to all routes, make a `GET` request to `/actuator/gateway/globalfilters`. The resulting response is similar to the following: + +---- +{ + "org.springframework.cloud.gateway.filter.LoadBalancerClientFilter@77856cc5": 10100, + "org.springframework.cloud.gateway.filter.RouteToRequestUrlFilter@4f6fd101": 10000, + "org.springframework.cloud.gateway.filter.NettyWriteResponseFilter@32d22650": -1, + "org.springframework.cloud.gateway.filter.ForwardRoutingFilter@106459d9": 2147483647, + "org.springframework.cloud.gateway.filter.NettyRoutingFilter@1fbd5e0": 2147483647, + "org.springframework.cloud.gateway.filter.ForwardPathFilter@33a71d23": 0, + "org.springframework.cloud.gateway.filter.AdaptCachedBodyGlobalFilter@135064ea": 2147483637, + "org.springframework.cloud.gateway.filter.WebsocketRoutingFilter@23c05889": 2147483646 +} +---- + +The response contains details of the global filters in place. For each global filter is provided the string representation of the filter object (e.g., `org.springframework.cloud.gateway.filter.LoadBalancerClientFilter@77856cc5`) and the corresponding <> in the filter chain. + +==== Route Filters +To retrieve the <> applied to routes, make a `GET` request to `/actuator/gateway/routefilters`. The resulting response is similar to the following: + +---- +{ + "[AddRequestHeaderGatewayFilterFactory@570ed9c configClass = AbstractNameValueGatewayFilterFactory.NameValueConfig]": null, + "[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]": null, + "[SaveSessionGatewayFilterFactory@4449b273 configClass = Object]": null +} +---- + +The response contains details of the GatewayFilter factories applied to any particular route. For each factory is provided the string representation of the corresponding object (e.g., `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`). Note that the `null` value is due to an imperfect implementation of the endpoint controller, for that it tries to set the order of the object in the filter chain, which is an information that does not apply to GatewayFilter factories. === Refreshing TODO: POST `/gateway/refresh` @@ -1119,11 +1148,11 @@ The table below summarises the Spring Cloud Gateway actuator endpoints. Note tha |`globalfilters` |GET -| Displays the list of <> applied to the routes. +| Displays the list of global filters applied to the routes. |`routefilters` |GET -| Displays the list of <> applied to a particular route. +| Displays the list of GatewayFilter factories applied to a particular route. |`refresh` |POST From ca83d0b9002eace0dfab35f3b6451298f676c1f2 Mon Sep 17 00:00:00 2001 From: Guido Lena Cota Date: Sat, 3 Nov 2018 16:57:55 +0100 Subject: [PATCH 3/6] Add documentation for /gateway/refresh endpoint --- docs/src/main/asciidoc/spring-cloud-gateway.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index e94dd3b6..3f43b7fa 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -1127,8 +1127,8 @@ To retrieve the <> applied to r The response contains details of the GatewayFilter factories applied to any particular route. For each factory is provided the string representation of the corresponding object (e.g., `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`). Note that the `null` value is due to an imperfect implementation of the endpoint controller, for that it tries to set the order of the object in the filter chain, which is an information that does not apply to GatewayFilter factories. -=== Refreshing -TODO: POST `/gateway/refresh` +=== Refreshing the route cache +To clear the routes cache, make a `POST` request to `/actuator/gateway/refresh`. The request returns a 200 without response body. === Retrieving the routes defined in the gateway TODO: GET `/gateway/routes` @@ -1156,7 +1156,7 @@ The table below summarises the Spring Cloud Gateway actuator endpoints. Note tha |`refresh` |POST -| TODO +| Clears the routes cache. |`routes` |GET From ee8085c58bdea925861bae3fc1f00a07360093a6 Mon Sep 17 00:00:00 2001 From: Guido Lena Cota Date: Sat, 3 Nov 2018 17:14:50 +0100 Subject: [PATCH 4/6] Add documentation for /gateway/routes endpoint --- .../main/asciidoc/spring-cloud-gateway.adoc | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index 3f43b7fa..2aedbe21 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -1131,7 +1131,54 @@ The response contains details of the GatewayFilter factories applied to any part To clear the routes cache, make a `POST` request to `/actuator/gateway/refresh`. The request returns a 200 without response body. === Retrieving the routes defined in the gateway -TODO: GET `/gateway/routes` +To retrieve the routes defined in the gateway, make a `GET` request to `/actuator/gateway/routes`. The resulting response is similar to the following: + +---- +[{ + "route_id": "first_route", + "route_object": { + "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@1e9d7e7d", + "filters": [ + "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}" + ] + }, + "order": 0 +}, +{ + "route_id": "second_route", + "route_object": { + "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298", + "filters": [ + "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}" + ] + }, + "order": 0 +}] +---- + +The response contains details of all the routes defined in the gateway. The following table describes the structure of each element (i.e., a route) of the response. + +[cols="3,2,4"] +|=== +| Path | Type | Description + +|`route_id` +| String +| The route id. + +|`route_object.predicate` +| Object +| The route predicate. + +|`route_object.filters` +| Array +| The <> applied to the route. + +|`order` +| Number +| The route order. + +|=== === Retrieving information about a particular route TODO: GET `/gateway/routes/{id}`, GET `/gateway/routes/{id}/combinedfilters` From 43074aba397f8fefdb8177fdff49efee8ca419e5 Mon Sep 17 00:00:00 2001 From: Guido Lena Cota Date: Sat, 3 Nov 2018 18:05:57 +0100 Subject: [PATCH 5/6] Add documentation for GET/POST/DELETE /gateway/routes/{id} endpoints --- .../main/asciidoc/spring-cloud-gateway.adoc | 59 +++++++++++++++---- 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index 2aedbe21..19b5615c 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -1148,9 +1148,7 @@ To retrieve the routes defined in the gateway, make a `GET` request to `/actuato "route_id": "second_route", "route_object": { "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/1736826640@cd8d298", - "filters": [ - "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/674480275@6631ef72, order=0}" - ] + "filters": [] }, "order": 0 }] @@ -1181,12 +1179,55 @@ The response contains details of all the routes defined in the gateway. The foll |=== === Retrieving information about a particular route -TODO: GET `/gateway/routes/{id}`, GET `/gateway/routes/{id}/combinedfilters` +To retrieve information about a single route, make a `GET` request to `/actuator/gateway/routes/{id}` (e.g., `/actuator/gateway/routes/first_route`). The resulting response is similar to the following: -=== Updating and deleting a particular route -TODO: POST `/gateway/routes/{id}` DELETE `/gateway/routes/{id}` +---- +{ + "id": "first_route", + "predicates": [{ + "name": "Path", + "args": {"_genkey_0":"/first"} + }], + "filters": [], + "uri": "http://www.uri-destination.org", + "order": 0 +}] +---- -=== List of all endpoints +The following table describes the structure of the response. + +[cols="3,2,4"] +|=== +| Path | Type | Description + +|`id` +| String +| The route id. + +|`predicates` +| Array +| The collection of route predicates. Each item defines the name and the arguments of a given predicate. + +|`filters` +| Array +| The collection of filters applied to the route. + +|`uri` +| String +| The destination URI of the route. + +|`order` +| Number +| The route order. + +|=== + +=== Creating and deleting a particular route +To create a route, make a `POST` request to `/gateway/routes/{id_route_to_create}` with a JSON body that specifies the fields of the route (see previous section). + +To delete a route, make a `DELETE` request to `/gateway/routes/{id_route_to_delete}`. + +=== Recap: list of all endpoints The table below summarises the Spring Cloud Gateway actuator endpoints. Note that each endpoint has `/actuator/gateway` as the base-path. [cols="2,2,5"] @@ -1213,10 +1254,6 @@ The table below summarises the Spring Cloud Gateway actuator endpoints. Note tha |GET | Displays information about a particular route. -|`routes/{id}/combinedfilters` -|GET -| TODO - |`routes/{id}` |POST | Add a new route to the gateway. From 2ae1eeaa165ab358cc1a1cbdf1a2da60ed498192 Mon Sep 17 00:00:00 2001 From: Guido Lena Cota Date: Sat, 3 Nov 2018 18:09:01 +0100 Subject: [PATCH 6/6] Minor changes to the wording --- docs/src/main/asciidoc/spring-cloud-gateway.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-gateway.adoc b/docs/src/main/asciidoc/spring-cloud-gateway.adoc index 19b5615c..7427db97 100644 --- a/docs/src/main/asciidoc/spring-cloud-gateway.adoc +++ b/docs/src/main/asciidoc/spring-cloud-gateway.adoc @@ -1125,7 +1125,7 @@ To retrieve the <> applied to r } ---- -The response contains details of the GatewayFilter factories applied to any particular route. For each factory is provided the string representation of the corresponding object (e.g., `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`). Note that the `null` value is due to an imperfect implementation of the endpoint controller, for that it tries to set the order of the object in the filter chain, which is an information that does not apply to GatewayFilter factories. +The response contains details of the GatewayFilter factories applied to any particular route. For each factory is provided the string representation of the corresponding object (e.g., `[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]`). Note that the `null` value is due to an incomplete implementation of the endpoint controller, for that it tries to set the order of the object in the filter chain, which does not apply to a GatewayFilter factory object. === Refreshing the route cache To clear the routes cache, make a `POST` request to `/actuator/gateway/refresh`. The request returns a 200 without response body. @@ -1223,7 +1223,7 @@ The following table describes the structure of the response. |=== === Creating and deleting a particular route -To create a route, make a `POST` request to `/gateway/routes/{id_route_to_create}` with a JSON body that specifies the fields of the route (see previous section). +To create a route, make a `POST` request to `/gateway/routes/{id_route_to_create}` with a JSON body that specifies the fields of the route (see the previous subsection). To delete a route, make a `DELETE` request to `/gateway/routes/{id_route_to_delete}`.