旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

サービスとルート

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

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

 
flowchart LR
  A(API client)
  B("`Route 
  (/mock)`")
  C("`Service
  (example_service)`")
  D(Upstream 
  application)
  
  A <--requests
  responses--> B
  subgraph id1 ["`
  **KONG GATEWAY**`"]
    B <--requests
    responses--> C
  end
  C <--requests
  responses--> D

  style id1 rx:10,ry:10

サービスの定義

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

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

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

ルートとは

ルートとは、アップストリームアプリケーション内のリソースへのパスのことです。ルートはサービスに追加され、基礎となるアプリケーションへのアクセスを可能にします。Kong Gatewayではルートは通常、Kong Gatewayアプリケーションで公開されるエンドポイントにマップされます。ルートは、サービス関連するリクエストに一致するルールを定義することもできます。このため、1つのルートで複数のエンドポイントを参照できます。基本的なルートには名前、パス、既存のサービスのリファレンスが必要です。

また、次の方法でルートを構成することもできます。

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

Kong Gatewayがリクエストをどうルーティングするかの説明については、ルートを参照してください。

サービスとルートの管理

次のチュートリアルでは、 Kong Gateway の Admin API を使用したサービスやルートの管理やテストに関して一通り説明します。Kong Gateway は、Kong Konnect と decK を含む、コンフィギュレーション管理のための他のオプションも提供しています。

チュートリアルのこのセクションでは、次の手順を完了します。

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

前提条件

この章は、「 Get Started with Kong 」シリーズの一部です。最適な効果を得るために、シリーズを最初からご覧になることをお勧めします。

導入であるGet Kongには、ローカルKong Gatewayを実行するためのツールの前提条件と手順が含まれています。

Get Kongの手順をまだ完了していない場合は、続行する前に完了してください。

サービスの管理

サービスの作成

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

上記例にはリクエストボディに次の2つの文字列が含まれています。
- name：サービス名
- url : サービスのhost、port、およびpath属性を設定する引数
リクエストが成功すると、Kong Gateway からの 201 レスポンスヘッダーが表示され、サービスが作成され、レスポンスボディが次のようになっていることを確認します。
```
{
  "host": "httpbin.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": "httpbin.org",
  "name": "example_service",
  "enabled": true,
  ...
}
```
サービスの更新

既存のサービス構成は、 PATCHリクエストをサービス URL に送信することで動的に更新できます。

サービス再試行を5から6に動的に設定するには、このPATCHリクエストを送信します。
```
curl --request PATCH \
  --url localhost:8001/services/example_service \
  --data retries=6
```
応答本文には、更新された値を含む完全なサービス構成が含まれています。
```
{
  "host": "httpbin.org",
  "name": "example_service",
  "enabled": true,
  "retries": 6,
  ...
}
```
サービスの一覧表示

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

管理APIドキュメントは、完全なサービス更新仕様を提供します。

ブラウザで次の URL に移動すると、Kong Manager UI でサービスの構成を表示することもできます。

Kong Manager OSS: http://localhost:8002/services
Kong Manager Enterprise: http://localhost:8002/default/services（default はワークスペース名）。

ルートの管理

ルートを作成

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

/mockパスに新しいルートを設定して、トラフィックを以前に作成したexample_serviceサービスに誘導します。

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
    }
  ]
}

管理APIドキュメントにはルートオブジェクトの管理に必要な情報が網羅されています。

Kong Manager UIでルートの設定を表示するには、ブラウザで次のURLに移動します：http://localhost:8002/default/routes

リクエストのプロキシ

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

デフォルトでは、 Kong GatewayのAdmin APIはポート8001で管理リクエストをリッスンします。これは、 コントロールプレーン（CP） と呼ばれる場合があります。クライアントはポート 8000 を使用してデータ要求を行います。これは多くの場合、 データプレーン（DP） と呼ばれます。

Httpbin は、クライアントに対して行われたリクエストに関する情報をエコーバックする/anythingリソースを提供します。Kong Gatewayを介してリクエストを/anythingリソースにプロキシします。

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

次のような応答が表示されます。

{
  "startedDateTime": "2022-08-24T13:44:28.449Z",
  "clientIPAddress": "172.19.0.1",
  "method": "GET",
  "url": "http://localhost/anything",
  "httpVersion": "HTTP/1.1",
  "cookies": {},
  "headers": {
    "host": "httpbin.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/anything",
    "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を入手

次へ Rate Limiting