アクチュエーター API

/gateway アクチュエーターエンドポイントを使用すると、Spring Cloud Gateway アプリケーションを監視および操作できます。リモートでアクセスできるようにするには、エンドポイントを有効にして、アプリケーションのプロパティで HTTP または JMX を介して公開する必要があります。次のリストは、その方法を示しています。

management.endpoint.gateway.enabled=true # default value
management.endpoints.web.exposure.include=gateway

このエンドポイントは、子アクチュエーターエンドポイントで利用できるものの概要と、各参照で利用できるメソッドを提供します。結果のレスポンスは次のようになります。

[
   {
      "href":"/actuator/gateway/",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routedefinitions",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/globalfilters",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routefilters",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routes",
      "methods":[ "POST", "GET" ]
   },
   {
      "href":"/actuator/gateway/routepredicates",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/refresh",
      "methods":[ "POST" ]
   },
   {
      "href":"/actuator/gateway/routes/route-id-1/combinedfilters",
      "methods":[ "GET" ]
   },
   {
      "href":"/actuator/gateway/routes/route-id-1",
      "methods":[ "POST", "DELETE", "GET" ]
   }
]

詳細なアクチュエーター形式

新しい、より詳細な形式が Spring Cloud Gateway に追加されました。各ルートに詳細が追加され、使用可能な構成とともに、各ルートに関連付けられた述語とフィルターを表示できます。次の例では、/actuator/gateway/routes を構成します。

[
  {
    "predicate": "(Hosts: [**.addrequestheader.org] && Paths: [/headers], match trailing slash: true)",
    "route_id": "add_request_header_test",
    "filters": [
      "[[AddResponseHeader X-Response-Default-Foo = 'Default-Bar'], order = 1]",
      "[[AddRequestHeader X-Request-Foo = 'Bar'], order = 1]",
      "[[PrefixPath prefix = '/httpbin'], order = 2]"
    ],
    "uri": "lb://testservice",
    "order": 0
  }
]

この機能はデフォルトで有効になっています。これを無効にするには、次のプロパティを設定します。

application.properties
spring.cloud.gateway.actuator.verbose.enabled=false

これは、将来のリリースでデフォルトで true になります。

ルートフィルターの取得

このセクションでは、以下を含むルートフィルターを取得する方法について詳しく説明します。

グローバルフィルター

すべてのルートに適用されているグローバルフィルターを取得するには、/actuator/gateway/globalfilters に対して GET リクエストを行います。結果のレスポンスは次のようになります。

{
  "org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@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
}

レスポンスには、配置されているグローバルフィルターの詳細が含まれています。各グローバルフィルターには、フィルターオブジェクト (たとえば、org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@77856cc5) の文字列表現と、フィルターチェーン内の対応する順序があります。

ルートフィルター

ルートに適用された GatewayFilter ファクトリを取得するには、/actuator/gateway/routefilters に対して GET リクエストを行います。結果のレスポンスは次のようになります。

{
  "[AddRequestHeaderGatewayFilterFactory@570ed9c configClass = AbstractNameValueGatewayFilterFactory.NameValueConfig]": null,
  "[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object]": null,
  "[SaveSessionGatewayFilterFactory@4449b273 configClass = Object]": null
}

レスポンスには、特定のルートに適用された GatewayFilter ファクトリの詳細が含まれています。ファクトリごとに、対応するオブジェクトの文字列表現があります(たとえば、[SecureHeadersGatewayFilterFactory@fceab5d configClass = Object])。null 値は、エンドポイントコントローラーの実装が不完全であることが原因であることに注意してください。これは、GatewayFilter ファクトリオブジェクトには適用されないフィルターチェーンでオブジェクトの順序を設定しようとするためです。

ルートキャッシュのリフレッシュ

ルートキャッシュをクリアするには、/actuator/gateway/refresh に POST リクエストを送信します。リクエストは、レスポンス本文なしで 200 を返します。

特定のメタデータ値を持つルートをクリアするには、クエリパラメーター metadata を追加して、クリアするルートが一致する必要がある key:value ペアを指定します。非同期リフレッシュ中にエラーが発生した場合、リフレッシュによって既存のルートが変更されることはありません。

POST リクエストを /actuator/gateway/refresh?metadata=group:group-1 に送信すると、group メタデータが group-1 であるルートのみがリフレッシュされます: first_route および third_route

[{
  "route_id": "first_route",
  "route_object": {
    "predicate": "...",
  },
  "metadata": { "group": "group-1" }
},
{
  "route_id": "second_route",
  "route_object": {
    "predicate": "...",
  },
  "metadata": { "group": "group-2" }
},
{
  "route_id": "third_route",
  "route_object": {
    "predicate": "...",
  },
  "metadata": { "group": "group-1" }
}]

ゲートウェイで定義されたルートの取得

ゲートウェイで定義されたルートを取得するには、/actuator/gateway/routes に対して GET リクエストを行います。結果のレスポンスは次のようになります。

[{
  "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": []
  },
  "order": 0
}]

レスポンスには、ゲートウェイで定義されているすべてのルートの詳細が含まれています。次の表に、レスポンスの各要素(それぞれがルート)の構造を示します。

パス タイプ 説明

route_id

String

ルート ID。

route_object.predicate

オブジェクト

ルート述語。

route_object.filters

配列

ルートに適用された GatewayFilter ファクトリ

order

番号

ルートの順序。

特定のルートに関する情報の取得

単一のルートに関する情報を取得するには、/actuator/gateway/routes/{id} に対して GET リクエストを行います(たとえば、/actuator/gateway/routes/first_route)。結果のレスポンスは次のようになります。

{
  "id": "first_route",
  "predicates": [{
    "name": "Path",
    "args": {"_genkey_0":"/first"}
  }],
  "filters": [],
  "uri": "https://www.uri-destination.org",
  "order": 0
}

次の表に、レスポンスの構造を示します。

パス タイプ 説明

id

String

ルート ID。

predicates

配列

ルート述語のコレクション。各項目は、特定の述語の名前と引数を定義します。

filters

配列

ルートに適用されるフィルターのコレクション。

uri

String

ルートの宛先 URI。

order

番号

ルートの順序。

特定のルート定義の作成と削除

ルート定義を作成するには、ルートのフィールドを指定する JSON 本文を使用して /gateway/routes/{id_route_to_create} への POST リクエストを行います ( 特定のルートに関する情報の取得を参照)。

ルート定義を削除するには、DELETE リクエストを /gateway/routes/{id_route_to_delete} に送信します。

複数のルート定義の作成

単一のリクエストで複数のルート定義を作成するには、ルート ID を含むルートのフィールドを指定する JSON 本文を使用して POST リクエストを /gateway/routes に作成します ( 特定のルートに関する情報の取得を参照)。

ルートの作成中にルートでエラーが発生した場合、ルート定義は破棄されます。

要約: すべてのエンドポイントのリスト

次の表は、Spring Cloud Gateway アクチュエーターエンドポイントをまとめたものです (各エンドポイントにはベースパスとして /actuator/gateway があることに注意してください)。

IDHTTP メソッド 説明

globalfilters

GET

ルートに適用されているグローバルフィルターのリストを表示します。

routefilters

GET

特定のルートに適用されている GatewayFilter ファクトリのリストを表示します。

refresh

POST

ルートキャッシュをクリアします。

routes

GET

ゲートウェイで定義されているルートのリストを表示します。

routes/{id}

GET

特定のルートに関する情報を表示します。

routes/{id}

POST

ゲートウェイに新しいルートを追加します。

routes/{id}

DELETE

ゲートウェイから既存のルートを削除します。