Kong API Gateway インストール手順【Helm 版】

Kong を Helm で Kubernetes にインストールする手順について

Helm を使って Kong を Kubernetes クラスターにインストール方法を解説します。

対象読者

Helm を使った Kong のインストールが始めての方、手元の Kubernetes クラスターに小規模な Kong 環境を Helm で用意したい方に適した内容です。商用向けの内容ではないのでご注意ください。

前提条件

kubernetes クラスター構築済み（この記事では minikube を使用）
kubernetes クラスターは v1.19 または以降のバージョン
kubectl 導入済み
kubectl は v1.19 または以降のバージョン
helm のバージョンは v3
当該手順は Kong 社の公式情報ではないため商用環境を想定した動作やセキュリティは無保証

解説する手順は Kong 公式ドキュメントの手順をベースとしていますが、独自の解説やシナリオを加えています。商用環境利用の場合は、Kong 社の最新版ドキュメントの手順を参照ください。

Kubernetes クラスターに Namespace を作成

Kubernetes クラスター上に Namespace（名前空間）を作成します。

kubectl create namespace kong

Helm のセットアップ

kong の helm chart をリポジトリに追加します。

helm repo add kong https://charts.konghq.com

最新の kong chart を使ってインストールをするため、リポジトリを最新にしておきます。

helm repo update

これで kong の最新 helm chart がレポジトリに加わりました。

$ helm repo list
NAME    URL
kong    https://charts.konghq.com
$

余談ですが、kong などの各アプリケーション helm chart はプロジェクトに依りますが日々アップデートされています。参考：https://github.com/Kong/charts

values.yaml ファイルの作成

helm の醍醐味である values.yaml という設定ファイルを作成します。kong の values.yaml ファイルで設定可能なパラメーター内容は、https://github.com/Kong/charts/blob/main/charts/kong/README.md のドキュメントに解説があります。kong に任意の設定をする場合は、当該ドキュメントを注意深く読んで kong ならではの values.yaml で使うパラメーターや注意点などを理解する必要があります。この記事では helm を用いた kong のインストール手順に焦点を当てているため values.yaml のパラメーター定義に関する解説は割愛します。

簡単な構成例として、下記 URL にある minimal-kong-standalone.yaml ファイル（Ingress コントローラー無しで Open source 版の Kong と PostgreSQL をインストールする基本的な設定）を利用してインストールします。なお、helm では、このような yaml ファイルを values.yaml （もしくは values ファイル）と呼びます。

https://github.com/Kong/charts/blob/main/charts/kong/example-values/minimal-kong-standalone.yaml

ここでは wget コマンドを使用して手元に minimal-kong-standalone.yaml ファイルをダウンロードする手順を示します。ここで使用している URL は、上記 github の URL で Raw というボタンを押し、画面遷移後に表示された URL を指定しています。wget コマンドを使わない、使えない場合は minimal-kong-standalone.yaml という名前の空ファイルを作成し、上記 URL にあるファイルの中身をコピー＆ペーストしてファイルを用意してください。

wget https://raw.githubusercontent.com/Kong/charts/main/charts/kong/example-values/minimal-kong-controller.yaml

helm install で Kong をデプロイ

helm install コマンドで Kong をデプロイします。実行するコマンド引数の説明ですが、minimal-release は helm のリリース名、kong/kong は helm install で使用するチャート名、—namespace はインストール先 kubernetes クラスターの名前空間、—values で install で使用する values.yaml （ここでは minimal-kong-controller.yaml というファイル）を指定する内容となっています。

helm install minimal-release kong/kong --namespace kong --values ./minimal-kong-standalone.yaml

次のような出力が得られると思います。

$ helm install minimal-release kong/kong --namespace kong --values ./minimal-kong-standalone.yaml 
NAME: minimal-release
LAST DEPLOYED: Thu Jan 13 17:27:43 2022
NAMESPACE: kong
STATUS: deployed
REVISION: 1
NOTES:
To connect to Kong, please execute the following commands:

HOST=$(kubectl get svc --namespace kong minimal-release-kong-proxy -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
PORT=$(kubectl get svc --namespace kong minimal-release-kong-proxy -o jsonpath='{.spec.ports[0].port}')
export PROXY_IP=${HOST}:${PORT}
curl $PROXY_IP

Once installed, please follow along the getting started guide to start using
Kong: <https://docs.konghq.com/kubernetes-ingress-controller/latest/guides/getting-started/>
$

デプロイされたポッドを確認

デプロイされたポッドを確認します。ここの例では、「 minimal-release-kong-6bfcccc96-rp9l4 」がクライアントリクエストを proxy する kong gateway の pod です。「 minimal-release-postgresql-0 」は、kong の設定情報などを保持しておく PostgreSQL データベースの pod です。

$ kubectl get pods -n kong 
NAME                                            READY   STATUS      RESTARTS   AGE  
minimal-release-kong-6bfcccc96-rp9l4            1/1     Running     0          3m13s
minimal-release-kong-init-migrations--1-wrjfc   0/1     Completed   0          3m13s
minimal-release-postgresql-0                    1/1     Running     0          3m13s
$

kubectl describe でポッドの詳細情報を確認します。出力内容が多いため、コマンド例では head コマンドを使用していますが、実際の操作においては head コマンドは不要です。

$ kubectl describe pods minimal-release-kong-6bfcccc96-rp9l4 -n kong | head
Name:         minimal-release-kong-6bfcccc96-rp9l4
Namespace:    kong
Priority:     0
Node:         minikube/192.168.49.2
Start Time:   Thu, 13 Jan 2022 17:27:43 +0900
Labels:       app=minimal-release-kong
              app.kubernetes.io/component=app
              app.kubernetes.io/instance=minimal-release
              app.kubernetes.io/managed-by=Helm
              app.kubernetes.io/name=kong
$

Kong の proxy コンテナにアクセス

kubectl get pods -n kong で確認できる kong proxy のコンテナにアクセスして bash を利用してみます。コマンド例では、kong exec コマンドで該当コンテナの bash を利用し、kong version というコマンドを実行して bash のプロセスを終了する内容です。

$ kubectl get pods -n kong
NAME                                            READY   STATUS      RESTARTS   AGE
minimal-release-kong-6bfcccc96-rp9l4            1/1     Running     0          9m30s
minimal-release-kong-init-migrations--1-wrjfc   0/1     Completed   0          9m30s
minimal-release-postgresql-0                    1/1     Running     0          9m30s
$ kubectl exec -it minimal-release-kong-6bfcccc96-rp9l4 -n kong -- bash
Defaulted container "proxy" out of: proxy, clear-stale-pid (init), wait-for-db (init)
bash-5.1$ kong version
2.7.0
bash-5.1$ exit
exit
$

Kong の Admin API で少し操作してみる

この例で使用している kong helm chart のデプロイメントでは、[helm release 名]-kong-admin というサービスが利用できるようになっているため、Kong の Admin API を利用することができます。

$ kubectl get services -n kong
NAME                                  TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                         AGE
minimal-release-kong-admin            NodePort       10.105.226.96    <none>        8001:31751/TCP,8444:32598/TCP   11m
minimal-release-kong-proxy            LoadBalancer   10.96.156.37     <pending>     80:30437/TCP,443:30855/TCP      11m
minimal-release-postgresql            ClusterIP      10.102.178.152   <none>        5432/TCP                        11m
minimal-release-postgresql-headless   ClusterIP      None             <none>        5432/TCP                        11m
$

ただし、Ingress コントローラーを用意していないため、外部アドレスからサービスにアクセスすることができません。ここでは手短に minimal-release-kong-admin というサービスにアクセスするため、ポートフォワーディングを利用します。コマンドは以下のとおりです。

kubectl -n kong port-forward svc/minimal-release-kong-admin 8001:8001 &

補足説明ですが、「&」を付けてポートフォワーディングをしたため、以下のようにプロセスがバックグラウンドで動作します。これを停止したい場合は ps コマンドで該当する PID（プロセス ID）を確認し、kill コマンドで該当 PID にシグナルを送ってください。

$ ps aux | grep [f]orward
admin      47330  0.2  0.1 753368 43976 pts/0    Sl   17:50   0:00 kubectl -n kong port-forward svc/minimal-release-kong-admin 8001:8001
$ kill 47330
$ ps aux | grep [f]orward
[1]+  Terminated              kubectl -n kong port-forward svc/minimal-release-kong-admin 8001:8001
$

上述した手順でポートフォワーディングを動作させていれば、端末を操作している localhost から Admin API で kong の設定や管理をすることができます。次のコマンド例では、/status というエンドポイントに kong の Admin API でアクセスしています。なお、以下の実行例にある jq や head コマンドは出力を適当にする目的での使用であるため、実際の実行では必須ではありません。

$ curl -s http://localhost:8001/status | jq | head
Handling connection for 8001
{
  "database": {
    "reachable": true
  },
  "memory": {
    "lua_shared_dicts": {
      "kong": {
        "allocated_slabs": "0.04 MiB",        
        "capacity": "5.00 MiB"
      },
$

簡単なプロキシ設定を Admin API で試してみる

ここでは適当なレスポンスを返してくれる http://httpbin.org/anything をマイクロサービスに見立て、Kong に service と route を AdminAPI で登録してみます。はじめに service を以下のコマンドで登録します。実行結果で HTTP/1.1 201 Created のレスポンスが返ってくれば service が Kong に登録された目安となります。

curl -i -X POST --url http://localhost:8001/services --data 'name=example-service' --data 'url=http://httpbin.org/anything'

次に、上記で作った service に対して route を設定します。これも同様に POST メソッドでデータを登録し、HTTP/1.1 201 Created のレスポンスが返ってくることを確認します。

curl -i -X POST --url http://localhost:8001/services/example-service/routes --data "name=example-service-route" --data "paths[]=/any"

Kong に登録した service や route のオブジェクトを AdminAPI で確認するには、それぞれ以下のエンドポイントに対して GET メソッドでアクセスすることで確認できます。

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

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

Kong の proxy 動作確認

kubernetes クラスターの外にあるクライアントから Kong にアクセスして proxy の動作を確認してみます。kubernetes クラスターの外から Kong にアクセスするには、kubernetes クラスターに Ingress コントローラーとリソースを用意する必要があります。

この記事では minikube を使った内容となりますが、Ingress コントローラーとリソースを作成する手順は下記の記事に別途まとめてありますので必要に応じて参照ください。SaaS の kubernetes を利用している人は、各環境の手順にしたがって Ingress コントローラーやリソースを作成し、Kong の proxy サービス（この記事の例では minimal-release-kong-proxy）にリクエストが転送されるように Ingress を設定してください。

helm uninstall で kong のデプロイメントを削除

helm install でデプロイした Kong の関連 pod は helm uninstall コマンドで簡単に削除することができます。

helm list –namespace kong でリリース名を確認し、helm unistall コマンドで操作対象のリリース名を指定してデプロイメントを削除します。なお、helm コマンドの –namespace オプションは、-n と省略できるため、以下のコマンド例では省略形で実行しています。

helm list -n kong

helm uninstall minimal-release -n kong

参考までに実際の動作の様子を掲載しておきます。なお、pod が削除されるまで多少の時間が掛かります。pod の削除に掛かる時間は、利用している kubernetes クラスターの環境によって異なります。

$ helm list -n kong
NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART       APP VERSION
minimal-release kong            1               2022-01-13 17:27:43.144077842 +0900 JST deployed        kong-2.6.4  2.7        
$ kubectl get pods -n kong
NAME                                            READY   STATUS      RESTARTS       AGE  
minimal-release-kong-6bfcccc96-rp9l4            1/1     Running     2 (112m ago)   5d18h
minimal-release-kong-init-migrations--1-wrjfc   0/1     Completed   0              5d18h
minimal-release-postgresql-0                    1/1     Running     2 (112m ago)   5d18h
$ helm uninstall minimal-release -n kong
release "minimal-release" uninstalled
$ kubectl get pods -n kong
NAME                                   READY   STATUS        RESTARTS       AGE  
minimal-release-kong-6bfcccc96-rp9l4   1/1     Terminating   2 (116m ago)   5d18h
minimal-release-postgresql-0           1/1     Terminating   2 (116m ago)   5d18h
$ kubectl get pods -n kong
No resources found in kong namespace.
$

おまけ

この記事では予め用意されている Kong の sample helm chart (minimal-kong-standalone.yaml ) を利用しましたが、Kong の設定パラメーターを任意に変更したい場合は、以下の情報ソースなどを参考に設定ください。

https://github.com/Kong/charts/blob/main/charts/kong/README.md
https://artifacthub.io/packages/helm/kong/kong
$ helm show values kong/kong