B!

Kong Gateway の基本的な使い方や設定について

10 min 1,231 views

この記事について

この記事は Kong Gateway をはじめて設定する方や、Kong Gateway の基本的な使い方や設定を知りたい方に向けた内容となっています。この記事を読むと Kong Gateway の基本操作が分かるようになります。

Kong Gateway の Service, Route という用語について

はじめに Kong Gateway で使われる独自の用語について説明します。Kong Gateway は、クライアントリクエストを API エンドポイントに中継（プロキシー）する役割を果たします。そこで、Kong Gateway がどのようなリクエストをどこに中継するかという内容を設定するために、Service, Route と呼ばれるオブジェクトの概念が使われます。

Service とは

Kong Gateway の Service は API のエンドポイントを表すもの（オブジェクト）です。Kong Gateway では Service というオブジェクトに API エンドポイントを紐づけて管理します。

Route とは

Kong Gateway の Route はどのようなクライアントリクエストをどの API エンドポイント（Service）にプロキシーするか定義するもの（オブジェクト）です。Kong Gateway では Route というオブジェクトにプロキシー定義内容を紐づけて管理します。

Service, Route の設定・操作例

それでは Kong Gateway で Service と Route オブジェクトを作成して、クライアントリクエストを Kong Gateway にプロキシーさせてみます。この例では、Kong 社が提供している mockbin.org というサービスの http://mockbin.org/request を API エンドポイントとして利用します。なお、後述する操作内容は Kong Gateway がインストールされているローカルホストでの操作を前提としています。

Service オブジェクトの作成

Service オブジェクトを mockbin-request という名前で作成し、API エンドポイントに http://mockbin.org/request を指定します。

Service オブジェクトの作成は、Kong Manager による GUI での作成方法と、Admin API によるコマンドでの作成方法があります。どちらも同じ設定内容になりますので、状況に応じて任意の方法で操作ください。

Kong Manager での作成

Service オブジェクトの作成１

Kong Manager の URL は kong.conf にある admin_gui_url パラメーターの設定次第ですが、ローカルホストで環境を構築した多くの場合は http://localhost:8002/manager になります。任意のブラウザで当該 URL にアクセスします。

① Kong Manager の左側のメニューから「Services」を選択します

② 画面右上にある [New Service] ボタンを押下します

Service オブジェクトの作成２

③ Service オブジェクトに任意の名前を付けます

④ API のエンドポイントを設定します

Service オブジェクトの作成３

⑤ 以上の手順で作成した Service オブジェクトが表示されます

Admin API によるコマンドでの作成

curl -i -s -X POST http://localhost:8001/services --data name=mockbin-request --data url='http://mockbin.org/request'

実際の実行例です。Service オブジェクトの作成が成功すると 201 レスポンスが返ります。

[root@localhost ~]# curl -i -s -X POST http://localhost:8001/services --data name=mockbin-request --data url='http://mockbin.org/request'
HTTP/1.1 201 Created
Date: Thu, 24 Nov 2022 07:52:50 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
X-Kong-Admin-Request-ID: iM164XWypK7eTnNZfuziT1KWtmSTA77X
Content-Length: 382
X-Kong-Admin-Latency: 12
Server: kong/2.8.2.0-enterprise-edition

{"retries":5,"updated_at":1669276370,"name":"mockbin-request","port":80,"client_certificate":null,"protocol":"http","connect_timeout":60000,"id":"98350dc1-d690-4416-af29-52bd193de2f5","tls_verify_depth":null,"host":"mockbin.org","enabled":true,"write_timeout":60000,"path":"/request","ca_certificates":null,"tls_verify":null,"tags":null,"created_at":1669276370,"read_timeout":60000}
[root@localhost ~]#

Service オブジェクトの確認方法

作成した Service オブジェクトは次のように確認することができます。

curl -X GET http://localhost:8001/services

以下は実際の実行例です。jq というコマンドをパイプで繋げて内容を見やすくしていますが、jq コマンドがインストールされていない場合は、無くても問題ありません。

[root@localhost ~]# curl -s -X GET http://localhost:8001/services | jq
{
  "data": [
    {
      "retries": 5,
      "updated_at": 1669276370,
      "name": "mockbin-request",
      "port": 80,
      "client_certificate": null,
      "protocol": "http",
      "connect_timeout": 60000,
      "id": "98350dc1-d690-4416-af29-52bd193de2f5",
      "tls_verify_depth": null,
      "host": "mockbin.org",
      "enabled": true,
      "write_timeout": 60000,
      "path": "/request",
      "ca_certificates": null,
      "tls_verify": null,
      "tags": null,
      "created_at": 1669276370,
      "read_timeout": 60000
    }
  ],
  "next": null
}
[root@localhost ~]#

Route の作成

次にどのようなクライアントリクエストをどの API エンドポイント（Service オブジェクト）にプロキシーするか、Route オブジェクトで設定します。

Route オブジェクトの作成も Kong Manager による GUI での作成方法と、Admin API によるコマンドでの作成方法があります。どちらも同じ設定内容になりますので、状況に応じて任意の方法で操作ください。

Kong Manager での作成

Route の作成１

① Kong Manager の左側のメニューから Routes を選択します

② Route の定義を適用する Service オブジェクトを選択します

③ Route オブジェクトに任意の名前をつけます

④ Path を設定します：この Path 設定はクライアントからアクセスした際に [Kong のアドレス：ポート番号] + [Path] （例：http://localhost:8000/path）となる Path です

Route の作成２

⑤ 以上の手順で作成した Route オブジェクトが表示されます

Admin API によるコマンドでの作成

curl -i -X POST http://localhost:8001/services/mockbin-request/routes --data 'paths[]=/mock' --data name=mockbin-request-route

実際の実行例です。

[root@localhost ~]# curl -i -X POST http://localhost:8001/services/mockbin-request/routes --data 'paths[]=/mock' --data name=mockbin-request-route
HTTP/1.1 201 Created
Date: Thu, 24 Nov 2022 09:25:30 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
X-Kong-Admin-Request-ID: Noy91OKm3zV41wePedA2d17srTqKtzwa
Content-Length: 493
X-Kong-Admin-Latency: 9
Server: kong/2.8.2.0-enterprise-edition

{"updated_at":1669281930,"headers":null,"name":"mockbin-request-route","request_buffering":true,"response_buffering":true,"strip_path":true,"service":{"id":"98350dc1-d690-4416-af29-52bd193de2f5"},"preserve_host":false,"path_handling":"v0","https_redirect_status_code":426,"methods":null,"sources":null,"destinations":null,"id":"b315b7f2-30ee-4256-9882-2a4619fec86e","hosts":null,"snis":null,"protocols":["http","https"],"paths":["/mock"],"tags":null,"created_at":1669281930,"regex_priority":0}
[root@localhost ~]#

Route オブジェクトの確認方法

作成した Route オブジェクトは次のように確認できます。

curl -X GET http://localhost:8001/services/mockbin-request/routes

実際の実行例です。

[root@localhost ~]# curl -s -X GET http://localhost:8001/services/mockbin-request/routes | jq  
{
  "data": [
    {
      "updated_at": 1669281930,
      "headers": null,
      "name": "mockbin-request-route",
      "request_buffering": true,
      "response_buffering": true,
      "strip_path": true,
      "service": {
        "id": "98350dc1-d690-4416-af29-52bd193de2f5"
      },
      "preserve_host": false,
      "path_handling": "v0",
      "https_redirect_status_code": 426,
      "methods": null,
      "sources": null,
      "destinations": null,
      "id": "b315b7f2-30ee-4256-9882-2a4619fec86e",
      "hosts": null,
      "snis": null,
      "protocols": [
        "http",
        "https"
      ],
      "paths": [
        "/mock"
      ],
      "tags": null,
      "created_at": 1669281930,
      "regex_priority": 0
    }
  ],
  "next": null
}
[root@localhost ~]#

Kong Gateway の動作確認

それでは作成した Service, Route オブジェクトについて動作確認をします。作成した Route オブジェクトのエンドポイントにアクセスし、Service オブジェクトで設定したエンドポイントに転送（proxy）されてレスポンスが得られれば成功です。

[root@localhost ~]# curl -s -X GET http://localhost:8000/mock
{
  "startedDateTime": "2022-11-24T09:48:56.027Z",
  "clientIPAddress": "127.0.0.1",
  "method": "GET",
  "url": "http://localhost/request",
  "httpVersion": "HTTP/1.1",
  "cookies": {},
  "headers": {
    "host": "mockbin.org",
    "connection": "close",
    "accept-encoding": "gzip",
    "x-forwarded-for": "127.0.0.1,xxx.xxx.xxx.xxx, xxx.xxx.xxx.xxx",
    "cf-ray": "76f13b505db4e368-NRT",
    "x-forwarded-proto": "http",
    "cf-visitor": "{\"scheme\":\"http\"}",
    "x-forwarded-host": "localhost",
    "x-forwarded-port": "80",
    "x-forwarded-path": "/mock",
    "x-forwarded-prefix": "/mock",
    "user-agent": "curl/7.61.1",
    "accept": "*/*",
    "cf-connecting-ip": "xxx.xxx.xxx.xxx",
    "cdn-loop": "cloudflare",
    "x-request-id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxxx",
    "via": "1.1 vegur",
    "connect-time": "0",
    "x-request-start": "1669283336026",
    "total-route-time": "0"
  },
  "queryString": {},
  "postData": {
    "mimeType": "application/octet-stream",
    "text": "",
    "params": []
  },
  "headersSize": 580,
  "bodySize": 0
}
[root@localhost ~]#
<PREV
Kong Vitals とは
NEXT>
podman の使い方
関連記事