アクチュエーター API

/gateway アクチュエーターエンドポイントを使用すると、Spring Cloud Gateway アプリケーションを監視および操作できます。/gateway' アクチュエーターエンドポイントは、デフォルトでアクセスが無効になっています。エンドポイントを有効にするには、アプリケーションプロパティで「読み取り専用」または「制限なし」へのアクセスを設定し、HTTP または JMX 経由で公開する必要があります。以下のリストにその方法を示します。

application.properties
management.endpoint.gateway.access=read-only
management.endpoints.web.exposure.include=gateway
management.endpoint.gateway.access を read-only に設定することをお勧めします。これにより、ルートのリフレッシュ、作成、削除の機能が無効になります。アクチュエーターエンドポイントを使用してルートの作成、リフレッシュ、削除を行う機能が必要な場合は、management.endpoint.gateway.access を unrestricted に設定するか、management.endpoint.gateway.enabled=true に設定してください。アクチュエーターエンドポイント経由でルートの作成、削除、リフレッシュを行う機能を有効にする場合は、アクチュエーターエンドポイントが保護されていることを確認するための適切な手順を実行する必要があります。

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

[
   {
      "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

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