サービスとルート

Kong Gateway の管理者は、オブジェクトモデルを使用して、トラフィック管理ポリシーを定義します。モデルには 2 つの重要なオブジェクトである、サービスとルートがあります。サービスとルートは、リクエストとレスポンスがシステムを通過するルーティングパスを定義するため、協調して設定されます。

以下のハイレベルの概要は、リクエストがルートに到着してサービスに転送され、レスポンスが逆の経路をたどることを示しています。

サービスとルート

サービスとは

Kong Gateway では、サービスは既存のアップストリームアプリケーションを抽象化したものです。サービスは、プラグイン設定やポリシーなどのオブジェクトのコレクションを格納でき、ルートと関連付けることができます。

サービスを定義する際、管理者は名前とアップストリームアプリケーションの接続情報を指定します。接続情報は、url フィールドに単一の文字列として指定するか、protocol、host、port、path の各値を個別に指定します。

サービスはアップストリームアプリケーションと 1 対多の関係を持つため、管理者は高度なトラフィック管理を作成できます。

ルートとは

ルートとは、アップストリームアプリケーション内のリソースへの経路です。アプリケーションにアクセスできるように、ルートがサービスに追加されます。Kong Gateway では、ルートは通常、Kong Gateway アプリケーションを通じて公開されるエンドポイントにマッピングされます。ルートは、リクエストと関連サービスを一致させるルールを定義することもできます。このため、1 つのルートで複数のエンドポイントを参照できます。基本的なルートは、名前と 1 つまたは複数の経路を持ち、既存のサービスを参照します。

以下を使用して、ルートを設定することも可能です。

プロトコル: アップストリームアプリケーションとの通信に使用されるプロトコルです。
ホスト: ルートに一致するドメインのリストです。
メソッド: ルートに一致する HTTP メソッドです。
ヘッダー: リクエストのヘッダーで期待される値のリストです。
リダイレクトステータスコード: HTTPS ステータスコードです。
タブ: ルートをグループ化するオプションの文字列のセットです。

Kong Gateway がリクエストをルーティングする方法については、「ルート」を参照してください。

サービスとルートの管理

以下のチュートリアルでは、Kong Gateway Admin API を使用して、サービスとルートを管理およびテストする方法を説明します。Kong Gateway は、Kong Konnect や decK など、その他の設定管理オプションを提供しています。

このチュートリアルでは、以下のステップを実行します。

HTTP リクエストとレスポンスのテスト機能を提供する Mockbin API をポイントするサービスを作成します。
実行中の Kong Gateway 上のクライアントが利用できる URL パスを提供し、ルートを定義します。
新しい Mockbin サービスを使用してテストリクエストをエコーし、Kong Gateway が API リクエストをどのようにプロキシするかを理解します。

必要なもの

このページは、「Kong 入門」チュートリアルの一部です。チュートリアルは最初から順にお読みになることを推奨します。

ステップ 1 の「Kong を始める」では、ツールに必要なものとローカルの Kong Gateway を実行する手順を説明しています。

このステップをまだ完了していない場合は、先に完了してください。

サービスの管理

サービスの作成

新しいサービスを追加するには、Kong Gateway Admin API の /services ルートに POST リクエストを送信します。
```
curl -i -s -X POST http://localhost:8001/services \
  --data name=example_service \
  --data url='http://mockbin.org'
```
このリクエストは、アップストリーム URL (http://mockbin.org) にマッピングされた新しいサービスの作成を、Kong Gateway に指示します。

この例では、リクエストボディに 2 つの文字列が含まれています。
- name: サービスの名前です。
- url: サービスの host、port、path 属性を入力する引数です。
リクエストが成功すると、サービスが作成されたことを確認する Kong Gateway からの 201 レスポンスヘッダーが表示され、レスポンスボディは以下のようになります。
```
{
  "host": "mockbin.org",
  "name": "example_service",
  "enabled": true,
  "connect_timeout": 60000,
  "read_timeout": 60000,
  "retries": 5,
  "protocol": "http",
  "path": null,
  "port": 80,
  "tags": null,
  "client_certificate": null,
  "tls_verify": null,
  "created_at": 1661346938,
  "updated_at": 1661346938,
  "tls_verify_depth": null,
  "id": "3b2be74e-335b-4f25-9f08-6c41b4720315",
  "write_timeout": 60000,
  "ca_certificates": null
}
```
リクエストで明示的に指定されていないフィールドは、自動的に現在の Kong Gateway の設定に基づくデフォルト値になります。
サービス設定の表示

サービスを作成すると、上記のレスポンスに示すように、Kong Gateway はサービスに一意の id を割り当てます。id フィールド、またはサービス作成時に提供された名前は、その後のリクエストでサービスを識別するために使用できます。このサービス URL は、/services/{service name or id} 形式になります。

サービスの現在のステートを確認するには、サービス URL に GET リクエストを送信します。
```
curl -X GET http://localhost:8001/services/example_service
```
リクエストが成功すると、以下のように、レスポンスボディにサービスの現在の設定が含まれます。
```
{
  "host": "mockbin.org",
  "name": "example_service",
  "enabled": true,
  ...
}
```
サービスの更新

既存のサービス設定は、サービス URL に PATCH リクエストを送信して動的に更新できます。

サービスの再試行回数を 5 回から 6 回に動的に設定するには、以下の PATCH リクエストを送信します。
```
curl --request PATCH \
  --url localhost:8001/services/example_service \
  --data retries=6
```
レスポンスボディには、更新された値を含む完全なサービス設定が含まれます。
```
{
  "host": "mockbin.org",
  "name": "example_service",
  "enabled": true,
  "retries": 6,
  ...
}
```
サービスの一覧表示

ベースとなる /services URL に GET リクエストを送信して、現在のサービスを一覧表示できます。
```
curl -X GET http://localhost:8001/services
```

Admin API のドキュメントに、サービス更新の完全な仕様が記載されています。

ルートの管理

ルートの作成

ルートは、リクエストが Kong Gateway によってどのようにプロキシされるかを定義します。サービス URL に POST リクエストを送信して、特定のサービスに関連するルートを作成できます。

前のステップで作成した example_service サービスにトラフィックを誘導するため、/mock パス上に新しいルートを設定します。

curl -i -X POST http://localhost:8001/services/example_service/routes \
  --data 'paths[]=/mock' \
  --data name=example_route

ルートの作成が成功すると、API は以下のような 201 レスポンスコードとレスポンスボディを返します。

{
  "paths": [
    "/mock"
  ],
  "methods": null,
  "sources": null,
  "destinations": null,
  "name": "example_route",
  "headers": null,
  "hosts": null,
  "preserve_host": false,
  "regex_priority": 0,
  "snis": null,
  "https_redirect_status_code": 426,
  "tags": null,
  "protocols": [
    "http",
    "https"
  ],
  "path_handling": "v0",
  "id": "52d58293-ae25-4c69-acc8-6dd729718a61",
  "updated_at": 1661345592,
  "service": {
    "id": "c1e98b2b-6e77-476c-82ca-a5f1fb877e07"
  },
  "response_buffering": true,
  "strip_path": true,
  "request_buffering": true,
  "created_at": 1661345592
}

ルート設定の表示

サービスと同様に、ルートを作成すると、Kong Gateway は上記のレスポンスに示すように、一意の id を割り当てます。id フィールド、またはルート作成時に提供された名前は、その後のリクエストでルートを識別するために使用できます。ルート URL は、次のいずれかの形式になります。
- /services/{service name or id}/routes/{route name or id}
- /routes/{route name or id}
example_route ルートの現在のステートを確認するには、サービス URL に GET リクエストを送信します。
```
curl -X GET http://localhost:8001/services/example_service/routes/example_route
```
レスポンスボディには、ルートの現在の設定が含まれます。
```
{
  "paths": [
    "/mock"
  ],
  "methods": null,
  "sources": null,
  "destinations": null,
  "name": "example_route",
  "headers": null,
  "hosts": null,
  "preserve_host": false,
  "regex_priority": 0,
  "snis": null,
  "https_redirect_status_code": 426,
  "tags": null,
  "protocols": [
    "http",
    "https"
  ],
  "path_handling": "v0",
  "id": "189e0a57-205a-4f48-aec6-d57f2e8a9985",
  "updated_at": 1661347991,
  "service": {
    "id": "3b2be74e-335b-4f25-9f08-6c41b4720315"
  },
  "response_buffering": true,
  "strip_path": true,
  "request_buffering": true,
  "created_at": 1661347991
}
```
ルートの更新

サービスと同様に、既存のルート設定は、ルート URL に PATCH リクエストを送信して動的に更新できます。

タグは、グループ化およびフィルタリングするため、ルートに関連付けることができるオプションの文字列のセットです。サービスエンドポイントに PATCH リクエストを送信してルートを指定することで、タグを割り当てることができます。

値が tutorial のタグを割り当てて、ルートを更新します。
```
curl --request PATCH \
  --url localhost:8001/services/example_service/routes/example_route \
  --data tags="tutorial"
```
上記の例では、ルート URL にサービスとルートの name フィールドを使用しました。

タグの適用が成功すると、レスポンスボディには以下のような JSON 値が含まれます。
```
...
"tags":["tutorial"]
...
```

ルートの一覧表示

Admin API は、現在設定されているすべてのルートの一覧を表示することもできます。

curl http://localhost:8001/routes

このリクエストは HTTP 200 ステータスコードと、Kong Gateway インスタンスに設定されているすべてのルートを含む JSON レスポンスボディオブジェクト配列を返します。以下のようなレスポンスになります。

{
  "next": null,
  "data": [
    {
      "paths": [
        "/mock"
      ],
      "methods": null,
      "sources": null,
      "destinations": null,
      "name": "example_route",
      "headers": null,
      "hosts": null,
      "preserve_host": false,
      "regex_priority": 0,
      "snis": null,
      "https_redirect_status_code": 426,
      "tags": [
        "tutorial"
      ],
      "protocols": [
        "http",
        "https"
      ],
      "path_handling": "v0",
      "id": "52d58293-ae25-4c69-acc8-6dd729718a61",
      "updated_at": 1661346132,
      "service": {
        "id": "c1e98b2b-6e77-476c-82ca-a5f1fb877e07"
      },
      "response_buffering": true,
      "strip_path": true,
      "request_buffering": true,
      "created_at": 1661345592
    }
  ]
}

Admin API のドキュメントに、ルートオブジェクト管理の完全な仕様が記載されています。

リクエストのプロキシ

API ゲートウェイである Kong は、クライアントからのリクエストを受け取り、現在の設定に基づいて適切なアップストリームアプリケーションにルーティングします。前のステップで設定したサービスとルートを使用して、http://localhost:8000/mock で https://mockbin.org/ にアクセスできます。

デフォルトでは、Kong Gateway の Admin API は、ポート 8001 で管理リクエストを listen し、これは「コントロールプレーン」と呼ばれます。クライアントは、ポート 8000 を使用してデータリクエストを行い、これは「データプレーン」と呼ばれます。

Mockbin は /requests リソースを提供し、リクエストに関する情報をクライアントへエコーバックします。Kong Gateway 経由で /requests リソースにリクエストをプロキシします。

curl -X GET http://localhost:8000/mock/requests

以下のようなレスポンスが表示されるはずです。

{
  "startedDateTime": "2022-08-24T13:44:28.449Z",
  "clientIPAddress": "172.19.0.1",
  "method": "GET",
  "url": "http://localhost/requests",
  "httpVersion": "HTTP/1.1",
  "cookies": {},
  "headers": {
    "host": "mockbin.org",
    "connection": "close",
    "accept-encoding": "gzip",
    "x-forwarded-for": "172.19.0.1,98.63.188.11, 162.158.63.41",
    "cf-ray": "73fc85d999f2e6b0-EWR",
    "x-forwarded-proto": "http",
    "cf-visitor": "{\"scheme\":\"http\"}",
    "x-forwarded-host": "localhost",
    "x-forwarded-port": "80",
    "x-forwarded-path": "/mock/requests",
    "x-forwarded-prefix": "/mock",
    "user-agent": "curl/7.79.1",
    "accept": "*/*",
    "cf-connecting-ip": "00.00.00.00",
    "cdn-loop": "cloudflare",
    "x-request-id": "1dae4762-5d7f-4d7b-af45-b05720762878",
    "via": "1.1 vegur",
    "connect-time": "0",
    "x-request-start": "1661348668447",
    "total-route-time": "0"
  },
  "queryString": {},
  "postData": {
    "mimeType": "application/octet-stream",
    "text": "",
    "params": []
  },
  "headersSize": 588,
  "bodySize": 0
}

« 前へ
Kong を始める

次へ »
レート制限