前提条件と環境要件
Kong Gateway を Kubernetes に導入するにあたって、まずはクラスタのバージョンや利用ツールが互換性を満たしているか確認する必要があります。適切なバージョンでないと CRD のロードや API 呼び出しが失敗し、デプロイ全体が止まるリスクがあります。本セクションでは、必須となるコンポーネントとチェックポイントを整理します。
推奨されるツールチェーン
以下は 2026 年時点で安定して利用できる組み合わせです。実際に構築する環境のリリースノートを確認し、同等かそれ以上のバージョンが提供されていることを目安にしてください。
| ツール | 推奨バージョン (例) | 確認ポイント |
|---|---|---|
| Kubernetes 本体 | 1.27 系以上（公式ドキュメントで networking.k8s.io/v1 が利用可能か） |
kubectl api-versions に networking.k8s.io/v1 が含まれる |
| kubectl | 1.27 系以上 | kubectl version --short で確認 |
| Helm | 3.12 系以上 | helm version --short で確認 |
ポイント：Kubernetes のマイナーバージョンは半年ごとにリリースされます。新しいバージョンが登場したら、公式チャートの対応状況を必ずチェックしましょう。
環境チェックコマンド例
|
1 2 3 4 5 6 7 8 9 |
# Kubernetes バージョン確認 kubectl version --short # Helm バージョン確認 helm version --short # 必要な API が有効か確認 kubectl api-versions | grep networking.k8s.io/v1 |
公式 Helm チャートでのデプロイ手順
Helm を利用すると、Kong のインストール・アップグレードが一貫した操作で完了します。このセクションでは、リポジトリ追加からカスタム values.yaml 作成までの流れを具体的に示し、設定項目の意味とベストプラクティスも併せて解説します。
values.yaml の主要設定項目
以下の表は、実運用で頻繁に調整されるパラメータです。デフォルト値はチャート側で定義されていますが、要件に合わせて上書きしてください。
| 項目 | 用途 | 典型的な設定例 |
|---|---|---|
replicaCount |
Kong Pod の複製数。可用性とスループットを左右します。 | 3（本番） |
service.type |
Service の公開方式。外部から直接アクセスさせるか内部限定にするか選択します。 | "LoadBalancer"（外部向け） |
env.kong_database |
DB-less と PostgreSQL モードの切り替えフラグです。 | "off"（DB-less） / "postgres" |
ingressController.enabled |
Kong Ingress Controller の有効化スイッチです。 | true |
env.kong_admin_listen |
Admin API のリッスンアドレスとポートです。セキュリティ要件に合わせて変更します。 | "127.0.0.1:8001"（本番） |
注記：
values.yamlはチャートリポジトリにサンプルが同梱されています。実際に上書きする項目だけを抜粋して作成すると管理が楽です。
DB-less モード用 values.yaml の例
|
1 2 3 4 5 6 7 8 9 |
replicaCount: 2 service: type: LoadBalancer env: kong_database: "off" kong_admin_listen: "127.0.0.1:8001" ingressController: enabled: true |
PostgreSQL モード用 values.yaml の例
|
1 2 3 4 5 6 7 8 9 10 11 12 |
replicaCount: 3 service: type: LoadBalancer env: kong_database: "postgres" pg_user: "kong" pg_password: "YOUR_SECURE_PASSWORD" pg_host: "postgresql.kong.svc.cluster.local" pg_port: "5432" ingressController: enabled: true |
DB-less と PostgreSQL の比較
| 項目 | DB-less | PostgreSQL |
|---|---|---|
| 導入コスト | 外部 DB が不要なため最小限で済む | データベースクラスターの構築・管理が必要 |
| スケーラビリティ | ConfigMap 更新で即時反映、水平スケールは Pod 増加で対応 | DB のレプリカを増やすことで大規模トラフィックに耐える |
| 永続性 | ConfigMap のサイズ制限（1 MiB 前後）あり | 永続ストレージ上のデータベースに完全保存 |
| 運用負荷 | 設定ファイル管理だけで済む | バックアップ・監視・パラメータチューニングが必須 |
| 推奨シーン | PoC、開発環境、トラフィックが数百 req/s 以下の小規模サービス | 本番環境、大規模マイクロサービス構成、長期運用が前提 |
まとめ：短期間の検証や軽量 API ゲートウェイとしては DB-less が手軽です。一方で高可用性・データ永続性が求められる本番環境では PostgreSQL モードを選択してください。
Helm によるインストールコマンド
-
公式リポジトリの追加
bash
helm repo add kong https://charts.konghq.com
helm repo update -
カスタム values ファイル（例：
kong-values.yaml）を作成
（上記の DB-less か PostgreSQL 用テンプレートをベースに編集） -
インストール実行
bash
helm install kong kong/kong -n kong --create-namespace -f kong-values.yaml -
リリース状態の確認
bash
helm status kong -n kong
ポイント：
helm install時に--wait --timeout 5mを付与すると、Pod が正常起動するまでコマンドがブロックされ、スクリプトでの自動化が容易になります。
マニフェスト方式によるデプロイ
Helm を使わずに Kubernetes のネイティブリソースだけで Kong を構築したい場合は、CRD（Custom Resource Definition）を直接適用します。この方法は CI/CD パイプラインへの組み込みがシンプルになるほか、細かなリソース制御が可能です。
手順概要
以下の流れに沿ってマニフェストを作成・適用してください。各ステップで必要となる設定例も併せて示します。
- CRD の登録
Kong が提供する Ingress 用 CRD をクラスタに追加します。 - Namespace と ServiceAccount、RBAC の定義
- ConfigMap（DB-less）または Secret（PostgreSQL）を作成
- Kong Deployment と Service のマニフェストを書き込む
- Ingress Controller 用 Deployment を用意
- 全リソースを順次
kubectl applyで適用
CRD 登録コマンド
|
1 2 |
kubectl apply -f https://download.konghq.com/gateway-2.x/kubernetes/kong-ingress-crd.yaml |
注意：CRD のバージョンは Kong のリリースに合わせて更新してください。古い CRD が残っていると
apiVersionの不一致エラーが発生します。
ConfigMap と Secret の作成例
DB-less 用 ConfigMap（設定を宣言的に管理）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
apiVersion: v1 kind: ConfigMap metadata: name: kong-config namespace: kong data: kong.yml: | _format_version: "2.1" services: - name: example-service url: http://example.com routes: - name: example-route paths: - /example |
PostgreSQL 用 Secret（機密情報を暗号化）
|
1 2 3 4 5 6 7 8 9 10 |
apiVersion: v1 kind: Secret metadata: name: kong-pg-secret namespace: kong type: Opaque data: pg_user: a29uZw== # base64 エンコードされた "kong" pg_password: c2VjdXJlUGFzcw== # "securePass" |
Kong Deployment のポイント
envFromを使って ConfigMap/Secret をマウントすると、環境変数の管理が楽になります。- Pod のリソース要求 (
resources.requests) と上限 (resources.limits) は必ず設定し、ノードの過負荷を防止してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
apiVersion: apps/v1 kind: Deployment metadata: name: kong-deployment namespace: kong spec: replicas: 3 selector: matchLabels: app: kong template: metadata: labels: app: kong spec: serviceAccountName: kong-sa containers: - name: kong image: kong/kong:2.9 envFrom: - configMapRef: name: kong-config # DB-less の場合 - secretRef: name: kong-pg-secret # PostgreSQL の場合 ports: - containerPort: 8000 # Proxy - containerPort: 8443 # Proxy (TLS) - containerPort: 8001 # Admin API resources: requests: cpu: "250m" memory: "256Mi" limits: cpu: "500m" memory: "512Mi" |
まとめ：CRD 登録 → RBAC/Namespace 設定 → ConfigMap/Secret 作成 → Deployment 適用 の順に実行すれば、Helm に依存しないシンプルな Kong 環境が構築できます。
デプロイ後の検証・運用フロー
Kong が正常に稼働したかどうかは、Pod の状態、Admin API の応答、Ingress 経由でのリクエスト成功率など複数観点から確認します。ここでは手動チェックと自動化の両方を紹介し、障害時の切り分け手順もまとめます。
基本的な検証項目
| 手順 | コマンド例 | 期待される結果 |
|---|---|---|
| Pod の状態確認 | kubectl get pods -n kong |
全て Running、READY が 1/1 以上 |
| Admin API アクセス | curl http://<LB_IP>:8001/status |
JSON で Kong のバージョン・ノード情報が返る |
| Ingress 動作テスト | curl -H "Host: example.com" http://<LB_IP>/example |
バックエンド（例：http://example.com）からのレスポンスが取得できる |
| メトリクス確認（Prometheus が有効な場合） | kubectl port-forward svc/kong-prometheus 9090:9090 -n kong → ブラウザで /metrics |
kong_http_requests_total 等の指標が収集されている |
自動化スクリプト例（簡易ヘルスチェック）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
#!/usr/bin/env bash set -euo pipefail LB_IP=$(kubectl get svc kong-proxy -n kong -o jsonpath='{.status.loadBalancer.ingress[0].ip}') # 1. Pod がすべて Ready になるまで待つ kubectl wait --for=condition=Ready pod -l app=kong -n kong --timeout=180s # 2. Admin API のステータス取得 if curl -s "http://$LB_IP:8001/status" | grep -q '"version":"2.'; then echo "✅ Admin API 正常" else echo "❌ Admin API が応答しません" exit 1 fi # 3. Ingress 経由のリクエストテスト if curl -s -H "Host: example.com" "http://$LB_IP/example" | grep -q 'Hello'; then echo "✅ Ingress 正常" else echo "❌ Ingress が期待通りに動作していません" exit 1 fi |
ポイント：CI パイプラインの
post-deployステップで上記スクリプトを走らせれば、デプロイ失敗時に即座にロールバックが可能です。
Helm のアップグレードとロールバック
| 操作 | コマンド例 | 補足 |
|---|---|---|
| アップグレード | helm upgrade kong kong/kong -n kong -f kong-values.yaml --reuse-values |
--wait を付けると完了まで待機します |
| リビジョン確認 | helm history kong -n kong |
各リリースの状態が一覧化されます |
| ロールバック | helm rollback kong <revision> -n kong |
失敗したバージョンへ即座に復帰できます |
トラブルシューティングの主なシナリオ
| 症状 | 想定原因 | 推奨対処法 |
|---|---|---|
Helm リリースが失敗する (Release "kong" failed) |
values.yaml の構文エラー、CRD が未登録 |
helm template でテンプレートをローカル検証し、kubectl get crd で CRD 存在確認 |
Pod が CrashLoopBackOff |
環境変数不足、DB 接続情報誤り、リソース上限超過 | kubectl logs <pod> -n kong でエラーログを取得し、Secret/ConfigMap を再チェック |
| Admin API がタイムアウト | Service が ClusterIP のままで外部からアクセス不可 |
Service タイプを LoadBalancer または Ingress 経由に変更し、ネットワークポリシーを確認 |
まとめ：Pod と Admin API の正常性を自動テストで確保した上で、Helm のバージョン管理機能（upgrade / rollback）を活用すれば、運用中の障害対応が格段にスピーディになります。
セキュリティベストプラクティスと次のアクション
本番環境で Kong を安全に稼働させるためには、TLS の自動取得・更新、最小権限の RBAC 設定、ネットワークレベルでの通信制御が不可欠です。この章では、実装例と導入手順を具体的に示します。
TLS 証明書の自動管理
cert‑manager と連携すれば、Ingress に tls: セクションとアノテーションを追加するだけで Let’s Encrypt の証明書が自動発行・更新されます。以下は最小構成例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: kong-ingress namespace: kong annotations: cert-manager.io/cluster-issuer: letsencrypt-prod # Issuer 名は事前作成済み spec: tls: - hosts: - api.example.com secretName: api-tls rules: - host: api.example.com http: paths: - path: / pathType: Prefix backend: service: name: kong-proxy port: number: 80 |
導入手順：
1.cert-managerの公式マニフェストを適用（CRD 登録含む）
2. ClusterIssuer（Let’s Encrypt 用）を作成
3. 上記 Ingress をデプロイし、Secret が自動生成されることを確認
RBAC ポリシーの最小化
Kong の管理に必要な権限だけを付与することで、万が一コンテナが侵害された場合でも被害範囲を限定できます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: kong-admin namespace: kong rules: - apiGroups: [""] resources: ["pods", "services"] verbs: ["get","list","watch"] - apiGroups: ["configuration.konghq.com"] resources: ["kongplugins","kongconsumers","kongroutes","kongservices"] verbs: ["create","update","delete","get","list"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: kong-admin-binding namespace: kong subjects: - kind: ServiceAccount name: kong-sa namespace: kong roleRef: kind: Role name: kong-admin apiGroup: rbac.authorization.k8s.io |
ポイント：
ClusterRoleは使用せず、必ず Namespace スコープで限定してください。
NetworkPolicy による通信制限
Kong Pod への直接アクセスを防ぎ、Ingress Controller 経由だけを許可することで外部からの不正リクエストを遮断します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: kong-ingress-restrict namespace: kong spec: podSelector: matchLabels: app: kong policyTypes: - Ingress ingress: - from: - podSelector: matchLabels: role: gateway # 同一 Namespace 内の Ingress Controller Pod のみ許可 |
補足：クラウドプロバイダーが提供する L7 ロードバランサーと併用する場合は、ロードバランサーからのトラフィックも
fromに追加してください。
次に取るべきアクション
- cert‑manager のデプロイ
bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.3/cert-manager.yaml - ClusterIssuer（Let’s Encrypt）を作成
（メールアドレスや環境に合わせて設定） - 最小権限の Role と RoleBinding を適用
- NetworkPolicy で外部からの直接アクセスを遮断
これらを順次実装すれば、Kong Gateway が TLS による暗号化と RBAC・ネットワークレベルの防御で保護された状態になります。
最終まとめ：Kubernetes 上に Kong を構築する際は、まず互換性のあるツールチェーンを整備し、Helm かマニフェスト方式のどちらかでデプロイします。デプロイ後は自動化テストと Helm のリビジョン管理で運用安定性を確保し、TLS・RBAC・NetworkPolicy によるセキュリティ対策を施すことで、本番環境でも安全に API ゲートウェイとして活用できます。