アクチュエーター 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.server.webflux.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" }
}]

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

ゲートウェイで定義されているルートを取得するには、GET リクエストを /actuator/gateway/routes に送信します。結果として得られるレスポンスは次のようになります（デフォルトの詳細形式）。

[{
  "predicate": "Paths: [/first], match trailing slash: true",
  "route_id": "first_route",
  "filters": [
    "[[PreserveHostHeader], order = 0]"
  ],
  "uri": "https://www.uri-destination.org",
  "order": 0
},
{
  "predicate": "Paths: [/second], match trailing slash: true",
  "route_id": "second_route",
  "filters": [],
  "uri": "https://www.uri-destination.org",
  "order": 0
}]

spring.cloud.gateway.server.webflux.actuator.verbose.enabled=false の場合、述語とフィルターは、人間が読める説明ではなく、生の Java クラス文字列として表示されます。

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

パスタイプ説明

パス	タイプ	説明
`route_id`	String	ルート ID。
`predicate`	String	経路述語を人間が読みやすい文字列形式で表現したもの（詳細形式）。
`filters`	配列	ルートに適用された `GatewayFilter` ファクトリ。
`uri`	String	ルートの宛先 URI。
`order`	番号	ルートの順序。

route_id

String

ルート ID。

predicate

String

経路述語を人間が読みやすい文字列形式で表現したもの（詳細形式）。

filters

配列

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

uri

String

ルートの宛先 URI。

order

番号

ルートの順序。

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

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

{
  "route_id": "first_route",
  "predicate": "(Paths: [/first], match trailing slash: true)",
  "filters": [],
  "uri": "https://www.uri-destination.org",
  "order": 0
}

GET /actuator/gateway/routes/{id} のレスポンスフォーマットでは、述語は単一の人間が読みやすい文字列として表現されます。これは、POST を介してルートを作成する際に必要となるショートカット DSL 文字列フォーマットとは異なります。正しい POST リクエスト本文フォーマットについては、特定のルート定義の作成と削除を参照してください。

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

パスタイプ説明

パス	タイプ	説明
`route_id`	String	ルート ID。
`predicate`	String	経路述語を人間が読みやすい文字列形式で表現したもの。
`filters`	配列	ルートに適用されるフィルターのコレクション。
`uri`	String	ルートの宛先 URI。
`order`	番号	ルートの順序。

route_id

String

ルート ID。

predicate

String

経路述語を人間が読みやすい文字列形式で表現したもの。

filters

配列

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

uri

String

ルートの宛先 URI。

order

番号

ルートの順序。

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

これらのエンドポイントを介して変更または削除できるのは、アクチュエーターエンドポイントを介して作成されたルートのみです。アプリケーション構成で定義されたルート（たとえば、application.yml または @Bean 経由）は、アクチュエーターの観点からは読み取り専用です。構成で定義されたルートを削除しようとすると、404 Not Found が返されます。

ルート定義を作成するには、ルートフィールドを指定する JSON ボディを含む POST リクエストを /actuator/gateway/routes/{id_route_to_create} に送信します。述語とフィルターは、GET /actuator/gateway/routes/{id} が返す構造化フォーマットとは異なり、ショートカット DSL 文字列 (例: "Path=/foo/**" または "StripPrefix=1") として指定する必要があります。正しいリクエストフォーマットの例を以下に示します。

{
  "predicates": ["Path=/mypath/**", "Weight=mygroup,20"],
  "filters": ["StripPrefix=1"],
  "uri": "http://backend-service:8080",
  "order": 0
}

作成が成功すると、201 Created が返されます。ルートを作成した後、アプリケーションを再起動せずに変更を適用するには、POST /actuator/gateway/refresh を呼び出してください。

既存のルート ID に対して POST を実行する前に、まずそのルートを削除してください。そうすると、ルート定義が内部的に複製され、後続の GET /actuator/gateway/routes リクエストで 500 Internal Server Error が発生します。アクチュエーター管理の既存ルートを更新するには、まずそのルートを削除してから再作成する必要があります。

DELETE を /actuator/gateway/routes/{id} に送信します。
更新された定義を POST から /actuator/gateway/routes/{id} に送信します。
POST を /actuator/gateway/refresh に送信します。

ルート定義を削除するには、DELETE リクエストを /actuator/gateway/routes/{id_route_to_delete} に送信します。削除が成功すると、200 OK が返されます。ルートを削除した後、アプリケーションを再起動せずに変更を適用するには、POST /actuator/gateway/refresh を呼び出します。

複数のルート定義の作成

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

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

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

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

ID HTTP メソッド説明

ID	HTTP メソッド	説明
`globalfilters`	GET	ルートに適用されているグローバルフィルターのリストを表示します。
`routefilters`	GET	特定のルートに適用されている `GatewayFilter` ファクトリのリストを表示します。
`refresh`	POST	ルートキャッシュをクリアします。
`routes`	GET	ゲートウェイで定義されているルートのリストを表示します。
`routes/{id}`	GET	特定のルートに関する情報を表示します。
`routes/{id}`	POST	ゲートウェイに新しいルートを追加します。述語とフィルターにはショートカット DSL 文字列形式を使用します。成功した場合は `201 Created` を返します。
`routes/{id}`	DELETE	ゲートウェイから既存のルートを削除します。アプリケーション構成で定義されたルートは、このエンドポイントでは削除できません（`404 Not Found` を返します）。

globalfilters

GET

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

routefilters

GET

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

refresh

POST

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

routes

GET

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

routes/{id}

GET

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

routes/{id}

POST

ゲートウェイに新しいルートを追加します。述語とフィルターにはショートカット DSL 文字列形式を使用します。成功した場合は 201 Created を返します。

routes/{id}

DELETE

ゲートウェイから既存のルートを削除します。アプリケーション構成で定義されたルートは、このエンドポイントでは削除できません（404 Not Found を返します）。