Kong Gateway のインストール手順 - Docker

このガイドでは、Docker を使用して、Kong Gateway をダウンロード、インストール、および起動する方法を紹介します。このガイドでは、データベースを使用する場合と、しない場合の両方の手順を説明します。データベースを使用する手順では、PostgreSQL を使用する場合の手順を紹介します。

オープンソースの Kong Gateway (OSS) イメージを Docker Compose で使用する場合、Kong はビルトインのオーケストレーションとスケーラビリティを備えた Docker Compose テンプレートを提供しています。

一部の旧 Kong Gateway イメージは一般公開されていません。Kong の Docker Hub ページでご希望のパッチ バージョンが見つからない場合は、サポート ポータルからお問い合わせください。

本ソフトウェアには、Kong Software License Agreement が適用されます。Kong Gateway (OSS) は、Apache 2.0 ライセンスの下でライセンスが許諾されています。

必要なもの

• Docker にアクセス可能な Docker 対応システム
• Kong から提供された license.json ファイル

Kong Gateway のインストールの種類を選択します。

• データベースを使用する: Kong の設定をデータベースに保存します。Admin API または宣言型設定ファイルを使用して Kong を設定できます。
• データベースを使用しない (DB レス モード): Kong の設定をノード上のインメモリに保存します。Admin API は読み取り専用です。宣言型設定ファイルを使用して Kong を管理する必要があります。

初めて Kong Gateway を使用する場合は、データベースを使用したインストールを推奨します。

データベースを使用した Kong Gateway のインストール手順

Kong の設定を保存するため、PostgreSQL データベースを使用して Kong Gateway コンテナーをセットアップします。

Kong Gateway で Cassandra は使用しないでください。Cassandra は非推奨であり、サポートが終了する予定です。

データベースの準備

1. コンテナーが互いに検出および通信できるように、カスタム Docker ネットワークを作成します。

   docker network create kong-net

   このネットワークには任意の名前を付けることができます。この例では、kong-net とします。

2. PostgreSQL コンテナーを起動します。

   docker run -d --name kong-database \
     --network=kong-net \
     -p 5432:5432 \
     -e "POSTGRES_USER=kong" \
     -e "POSTGRES_DB=kong" \
     -e "POSTGRES_PASSWORD=kongpass" \
     postgres:13
   

   • POSTGRES_USER と POSTGRES_DB: これらの値を kong に設定します。これは、Kong Gateway が期待するデフォルト値です。
   • POSTGRES_PASSWORD: データベース パスワードに任意の文字列を設定します。

   この例では、kong-database という名前の Postgres コンテナーは、kong-net ネットワーク上の任意のコンテナーと通信できます。

3. Kong データベースを準備します。

   Kong Gateway Kong Gateway (OSS)

   docker run --rm --network=kong-net \
     -e "KONG_DATABASE=postgres" \
     -e "KONG_PG_HOST=kong-database" \
     -e "KONG_PG_PASSWORD=kongpass" \
     -e "KONG_PASSWORD=test" \
    kong/kong-gateway:3.2.1.0 kong migrations bootstrap
   

   docker run --rm --network=kong-net \
     -e "KONG_DATABASE=postgres" \
     -e "KONG_PG_HOST=kong-database" \
     -e "KONG_PG_PASSWORD=kongpass" \
    kong:3.2.1 kong migrations bootstrap
   

   説明:

   • KONG_DATABASE: Kong が使用するデータベースの種類を指定します。
   • KONG_PG_HOST: 前のステップで指定した、kong-net ネットワーク上で通信する Postgres Docker コンテナーの名前です。
   • KONG_PG_PASSWORD: 前のステップで設定した、Postgres コンテナーのパスワードです。
   • KONG_PASSWORD: Kong Gateway の admin スーパー ユーザーのデフォルトのパスワードです。
   • {IMAGE-NAME:TAG} kong migrations bootstrap: 順番に、Kong Gateway コンテナーの名前とタグ、Postgres データベースを準備するため Kong へ渡すコマンドです。

     Kong Gateway の起動

   重要: 以下の設定は、デフォルトの admin_listen 設定を上書きして、あらゆるソースからのリクエストを listen するため、テスト環境での使用のみを目的としています。これらの設定は、インターネットに直接接続されている環境では使用しないでください。

   運用環境で admin_listen ポートをインターネットに公開する必要がある場合は、

   認証により保護してください。

4. (オプション) Kong Gateway の Enterprise ライセンスでは、ライセンス キーを変数にエクスポートできます。

   ライセンス データには、ストレート クォート (' と ") を使用する必要があります。スマートクォート (’ や “) は有効な JSON と見なされません。

   注: 以下のライセンスはあくまで例です。以下の形式に従って、お持ちのライセンスの情報を指定してください。

   export KONG_LICENSE_DATA='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'

5. 以下のコマンドを実行し、Kong Gateway コンテナーを起動します。

   Kong Gateway Kong Gateway (OSS)

   docker run -d --name kong-gateway \
     --network=kong-net \
     -e "KONG_DATABASE=postgres" \
     -e "KONG_PG_HOST=kong-database" \
     -e "KONG_PG_USER=kong" \
     -e "KONG_PG_PASSWORD=kongpass" \
     -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
     -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
     -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
     -e "KONG_ADMIN_GUI_URL=http://localhost:8002" \
     -e KONG_LICENSE_DATA \
     -p 8000:8000 \
     -p 8443:8443 \
     -p 8001:8001 \
     -p 8444:8444 \
     -p 8002:8002 \
     -p 8445:8445 \
     -p 8003:8003 \
     -p 8004:8004 \
     kong/kong-gateway:3.2.1.0
   

   docker run -d --name kong-gateway \
     --network=kong-net \
     -e "KONG_DATABASE=postgres" \
     -e "KONG_PG_HOST=kong-database" \
     -e "KONG_PG_USER=kong" \
     -e "KONG_PG_PASSWORD=kongpass" \
     -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
     -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
     -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
     -p 8000:8000 \
     -p 8443:8443 \
     -p 127.0.0.1:8001:8001 \
     -p 127.0.0.1:8444:8444 \
     kong:3.2.1
   

   説明:

   • --name と --network: 作成するコンテナーの名前とそのコンテナーが通信する Docker ネットワークです。
   • KONG_DATABASE: Kong が使用するデータベースの種類を指定します。
   • KONG_PG_HOST: kong-net ネットワーク上で通信する Postgres Docker コンテナーの名前です。
   • KONG_PG_USER と KONG_PG_PASSWORD: Postgres のユーザー名とパスワードです。Kong Gateway は、KONG_PG_HOST データベースに設定データを保存するためのログイン情報を必要とします。
   • すべての _LOG パラメーター: 出力するログのファイルパスを設定するか、例の値を使用してメッセージを stdout に、エラーを stderr に出力します。
   • KONG_ADMIN_LISTEN: Kong Admin API がリクエストを listen するポートです。
   • KONG_ADMIN_GUI_URL: (Enterprise のみ) Kong Manager にアクセスするための URL です。先頭にプロトコル (例: http://) が付きます。
   • KONG_LICENSE_DATA: (Enterprise のみ) 環境変数として保存したライセンス ファイルがある場合、このパラメーターは環境からライセンスを取得します。

6. インストールを検証します。

   Admin API を使用して /services エンドポイントにアクセスします。

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

   200 ステータス コードが表示されるはずです。

7. (Enterprise のみ) KONG_ADMIN_GUI_URL で指定した URL にアクセスして、Kong Manager が起動していることを確認します。

    http://localhost:8002

Kong Gateway の使用

Kong Gateway インスタンスが動作したら、Kong の「導入ガイド」を参考にして、最初のサービスのセットアップと拡張を行います。

具体的には、インストール直後に以下の操作を行います。

• サービスとルートの作成
• プラグインの設定
• 認証によるサービスの保護

コンテナーのクリーンアップ

Kong Gateway のテストが完了し、コンテナーが不要になった場合は、以下のコマンドを使用してコンテナーをクリーンアップできます。

docker kill kong-gateway
docker kill kong-database
docker container rm kong-gateway
docker container rm kong-database
docker network rm kong-net

DB レス モードでの Kong Gateway のインストール手順

ここでは、DB レス モードで Kong Gateway を起動する手順を説明します。

Docker ネットワークの作成

以下のコマンドを実行します。

docker network create kong-net

このネットワークには任意の名前を付けることができます。この例では、kong-net とします。

このステップは、DB レス モードで Kong を実行する場合には必須ではありませんが、将来 Redis クラスターでバックアップされた Rate Limiting プラグインなどを追加する場合に備えて、行うことをお勧めします。

設定ファイルの準備

1. .yml または .json 形式の宣言型設定ファイルを用意します。

   構文とプロパティは、「宣言型設定の書式」ガイドに記載されています。このファイルに、必要なコア エンティティ(Services、Routes、Plugins、Consumers など) を追加します。

   たとえば、Service と Route を含むシンプルなファイルは、以下のようになります。

   _format_version: "3.0"
    _transform: true
   
    services:
    - host: mockbin.org
      name: example_service
      port: 80
      protocol: http
      routes:
      - name: example_route
        paths:
        - /mock
        strip_path: true
   

   このガイドでは、ファイル名を kong.yml としています。

2. 宣言型設定ファイルをローカルに保存し、ファイルパスをメモします。

DB レス モードでの Kong Gateway の起動

重要: 以下の設定は、デフォルトの admin_listen 設定を上書きして、あらゆるソースからのリクエストを listen するため、テスト環境での使用のみを目的としています。これらの設定は、インターネットに直接接続されている環境では使用しないでください。

運用環境で admin_listen ポートをインターネットに公開する必要がある場合は、

認証により保護してください。

1. (オプション) Kong Gateway の Enterprise ライセンスでは、ライセンス キーを変数にエクスポートできます。

   ライセンス データには、ストレート クォート (' と ") を使用する必要があります。スマートクォート (’ や “) は有効な JSON と見なされません。

   注: 以下のライセンスは例を示すことを目的としています。この形式に従って、お持ちのライセンスの情報を指定してください。

    export KONG_LICENSE_DATA='{"license":{"payload":{"admin_seats":"1","customer":"Example Company, Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_key":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe060fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'

2. kong.yml ファイルを作成したディレクトリから、以下のコマンドを実行して Kong Gateway コンテナーを起動します。

   Kong Gateway Kong Gateway (OSS)

   docker run -d --name kong-dbless \
     --network=kong-net \
     -v "$(pwd):/kong/declarative/" \
     -e "KONG_DATABASE=off" \
     -e "KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml" \
     -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
     -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
     -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_LISTEN=0.0.0.0:8001" \
     -e "KONG_ADMIN_GUI_URL=http://localhost:8002" \
     -e KONG_LICENSE_DATA \
     -p 8000:8000 \
     -p 8443:8443 \
     -p 8001:8001 \
     -p 8444:8444 \
     -p 8002:8002 \
     -p 8445:8445 \
     -p 8003:8003 \
     -p 8004:8004 \
     kong/kong-gateway:3.2.1.0
   

   docker run -d --name kong-dbless \
     --network=kong-net \
     -v "$(pwd):/kong/declarative/" \
     -e "KONG_DATABASE=off" \
     -e "KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml" \
     -e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
     -e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
     -e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
     -e "KONG_ADMIN_LISTEN=0.0.0.0:8001, 0.0.0.0:8444 ssl" \
     -p 8000:8000 \
     -p 8443:8443 \
     -p 127.0.0.1:8001:8001 \
     -p 127.0.0.1:8444:8444 \
     kong:3.2.1
   

   説明:

   • --name と --network: 作成するコンテナーの名前とそのコンテナーが通信する Docker ネットワークです。
   • -v $(pwd):/path/to/target/: ローカル ファイルシステムの現在のディレクトリを Docker コンテナーのディレクトリにマウントします。これにより、Docker コンテナーから kong.yml ファイルが見えるようになります。
   • KONG_DATABASE: データベースを off に設定し、Kong がバッキング データベースに設定を保存しないように指示します。
   • KONG_DECLARATIVE_CONFIG: コンテナー内の宣言型設定ファイルのパスです。このパスは、-v でマッピングするターゲット パスと一致する必要があります。
   • すべての _LOG パラメーター: 出力するログのファイルパスを設定するか、例の値を使用してメッセージを stdout に、エラーを stderr に出力します。
   • KONG_ADMIN_LISTEN: Kong Admin API がリクエストを listen するポートです。
   • KONG_ADMIN_GUI_URL: (Enterprise のみ) Kong Manager にアクセスするための URL です。先頭にプロトコル (例: http://) が付きます。
   • KONG_LICENSE_DATA: (Enterprise のみ) 環境変数として保存したライセンス ファイルがある場合、このパラメーターは環境からライセンスを取得します。

3. Kong Gateway が起動していることを確認します。

   curl -i http://localhost:8001

   エンドポイントをテストします。たとえば、サービスのリストを取得します。

    curl -i http://localhost:8001/services

Kong Gateway の使用

Kong Gateway インスタンスが動作したら、Kong の「導入ガイド」を参考にして、最初のサービスのセットアップと拡張を行います。

このガイドの kong.yml の例を使用すると、Service と Route がすでに設定されています。以下も確認しておきましょう。

• プラグインの設定
• 認証によるサービスの保護
• ターゲット間のトラフィックのロード バランス

コンテナーのクリーンアップ

Kong Gateway のテストが完了し、コンテナーが不要になった場合は、以下のコマンドを使用してコンテナーをクリーンアップできます。

docker kill kong-dbless
docker container rm kong-dbless
docker network rm kong-net

トラブルシューティング

ライセンスに関する問題のトラブルシューティングは、以下を参照してください。

• ライセンスのデプロイ オプション
• /licenses API リファレンス
• /licenses API の例

200 OK ステータス コードを受信しなかった場合、またはセットアップの完了にサポートが必要な場合は、サポート担当者に連絡するか、サポート ポータルにアクセスしてください。