Contents
前提条件と環境設定
このセクションでは、Kong Gateway（KIC）を Helm 経由でインストールし、GitOps ツールが正しく動作するために最低限必要な環境をまとめます。対象は Kubernetes 1.24 以上 のクラスターで、ローカルに kubectl と helm v3 がインストールされていることが前提です。
- kubectl
bash
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl - helm
bash
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash - Kubernetes バージョン確認
bash
kubectl version --short # Client & Server が 1.24 以上かチェック - Git リポジトリの用意
GitHub（例:github.com/your-org/kong-gateway-demo）にcharts/とmanifests/ディレクトリを作成し、Argo CD または Flux が参照できるようにしておきます。
参考：Qiita の「OSS版Kong Gatewayをk8sで動かしてみる」でも同様の前提条件が示されています【[Qiita]】(https://qiita.com/tmatsu200/items/4c1b5be984ec8db7ee51)。
Kong Ingress Controller と Operator の選択ガイド
Kong を Kubernetes 上で運用する際は、主に Kong Ingress Controller (KIC) と Kong Gateway Operator のどちらかを選びます。ここでは機能比較とユースケース別の推奨を示し、導入判断の材料を提供します。
機能比較表
以下は公式ドキュメントに基づく主要項目の比較です。Gateway Discovery に関しては、Operator では 現在未実装（2024 年時点）であることが公式リファレンスで確認されています【[Kong Operator Docs]】(https://docs.konghq.com/operator/latest/reference/gateway-discovery/)。
| 項目 | Kong Ingress Controller (KIC) | Kong Gateway Operator |
|---|---|---|
| 管理単位 | Ingress と Service を中心に宣言的管理 |
KongGateway, KongPlugin など CRD で CP/DP を直接制御 |
| デプロイ方法 | Helm Chart の一括インストールが主流 | Operator が CRD を監視し Pod/Service を自動生成 |
| カスタマイズ性 | values.yaml と KongPlugin による細粒度設定 |
CRD フィールドで DP スケーリングや CP ログレベルなどを直接指定 |
| 運用負荷 | Helm だけで完結し GitOps と相性が良好 | Operator 常駐に伴うバージョンアップ時のマイグレーションが必要 |
| Gateway Discovery 対応 | ✅ 標準対応 (gatewayDiscovery.enabled: true) |
❌ 未実装。手動で Service ↔︎ DP の紐付けが必須 |
推奨シナリオ
- 迅速な API プロキシ構築
KIC + Helm を選択し、Gateway Discovery による自動エンドポイント登録を活用します。 - Control/Data Plane を明示的に分離したハイブリッド構成
Operator が提供する CP/DP 分離機能が有利ですが、Gateway Discovery が使えない点は留意してください。
結論：自動化とシンプルさを重視するなら KIC、マルチクラスタやハイブリッド構成で CP/DP の分離が必要な場合は Operator を検討します。
Helm Chart で KIC をインストールし Gateway Discovery を有効化
このセクションでは、KIC 用の values.yaml の重要ポイントと実際のインストール手順を示します。Helm によるデプロイは GitOps パイプラインでもそのまま利用できます。
values.yaml のポイント
以下は最小構成で Gateway Discovery と DB-less モードを有効にした例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# charts/kong/values.yaml image: repository: kong/kong-gateway tag: "3.5" # 必要に応じて最新タグへ更新 gatewayDiscovery: enabled: true # Service が自動的に Kong に登録される mode: dns # DNS 名解決でマルチクラスタでも一貫 env: database: "off" # DB-less（Declarative Config）モード plugins: "bundled,oidc" ingressController: enabled: true installCRDs: true proxy: type: LoadBalancer # 本番は Ingress 経由に置き換え可 |
gatewayDiscovery.enabled: trueが唯一の設定で、Service の作成だけで Kong にルートが自動反映されます。mode: dnsは内部 DNS を利用するため、マルチクラスタ環境でも名前解決が安定します。
インストール手順
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# 1. Helm リポジトリを追加・更新 helm repo add kong https://charts.konghq.com helm repo update # 2. カスタム values.yaml を作成（上記参照） # 3. デプロイ実行 helm install kong-gateway kong/kong \ -n kong --create-namespace \ -f ./values.yaml # 4. デプロイ結果確認 kubectl -n kong get pods -l app.kubernetes.io/name=kong kubectl -n kong get svc proxy-service |
ベストプラクティス：公式リポジトリは常に最新 CRD と互換性が保たれるため、
helm repo updateを定期的に実行し、再デプロイ時に最新版を取得してください【[Kong Helm Chart]】(https://github.com/kong/charts) 。
Service・Ingress・KongPlugin のマニフェスト例
この章では、Git リポジトリで管理する典型的な Kubernetes マニフェストを示します。Gateway Discovery が有効になっているため、Service を作成すれば自動的に Kong にエンドポイントが登録されます。
Service と Ingress の基本形
|
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 |
# manifests/bookinfo-service.yaml apiVersion: v1 kind: Service metadata: name: bookinfo labels: app: bookinfo spec: ports: - port: 80 targetPort: 8080 selector: app: bookinfo --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: bookinfo-ingress annotations: konghq.com/strip-path: "true" spec: rules: - host: bookinfo.example.com http: paths: - path: / pathType: Prefix backend: service: name: bookinfo port: number: 80 |
Serviceが作成されると、Gateway Discovery により自動的に Kong のルーティングテーブルへ反映されます。konghq.com/strip-path等のアノテーションでリクエストパスの調整が可能です。
プラグイン適用例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# manifests/bookinfo-plugin.yaml apiVersion: configuration.konghq.com/v1 kind: KongPlugin metadata: name: rate-limit config: minute: 60 plugin: rate-limiting --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: bookinfo-ingress annotations: konghq.com/plugins: rate-limit # カンマ区切りで複数プラグイン可 spec: ... |
KongPluginは名前空間単位で宣言し、対象 Ingress のannotations.konghq.com/pluginsに列記するだけで適用できます。- 認証・OAuth2・OIDC 等も同様に CRD として管理でき、GitOps の差分検知がそのままプラグイン設定の変更につながります。
GitOps による自動デプロイ
ここでは代表的な GitOps ツール Argo CD と Flux v2 を用いたデプロイフローを紹介します。どちらも KIC の Helm Chart と上記マニフェストをリポジトリから同期可能です。
Argo CD での Application 定義
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: kong-gateway namespace: argocd spec: project: default source: repoURL: https://github.com/your-org/kong-gateway-demo.git path: manifests # KIC の values.yaml とマニフェストが格納されたディレクトリ targetRevision: HEAD destination: server: https://kubernetes.default.svc namespace: kong syncPolicy: automated: prune: true selfHeal: true |
- 自動同期：Git にプッシュされるたびに Argo CD が差分を検出し、
helm upgrade --installと同等の操作でクラスターを更新します。 - selfHeal：手動で削除されたリソースは自動的に復元されます。
Argo CD と Flux の比較
| 項目 | Argo CD | Flux v2 |
|---|---|---|
| UI/ダッシュボード | Web コンソールが充実し、リアルタイムで状態可視化可能 | 主に CLI と GitHub Checks が中心 |
| 同期方式 | Pull & Push（プラグインで拡張） | Pull‑only がデフォルト |
| カスタマイズ性 | resourceHooks で柔軟なフック実装が容易 |
kustomize-controller の拡張が必要 |
Argo CD は運用者向けの可視化が優れており、Flux は CI/CD パイプラインとの統合がシンプルです。どちらも KIC + Gateway Discovery の Manifest を Git で一元管理できる点は共通しています【[Argo CD Docs]】(https://argo-cd.readthedocs.io) / 【[Flux Docs]】(https://fluxcd.io/docs/)。
本番環境ベストプラクティス（Hybrid・マルチクラスタ構成）
本章では、可用性とスケーラビリティを高めるためのハイブリッドモードや TLS/ RBAC の設定例を示します。実装例は公式ガイドに準拠しています【[Kong Hybrid Guide]】(https://docs.konghq.com/gateway/latest/hybrid-mode/)。
Hybrid モード構成例
- Control Plane (CP)
- Namespace
kong-cpに Operator または KIC をデプロイし、Admin API は外部から遮断。 - Data Plane (DP)
- 別クラスターまたは同一クラスターの
kong-dpに DP 用 Deployment を配置し、gatewayDiscovery.enabled: trueのみ有効化。 - 名前解決
- CP の Service 名
cp.kong.svc.cluster.localを DNS で公開し、DP が直接参照できるようにします。
この構成では CP の障害時に DP が継続稼働するため、サービス停止時間を最小化できます。
TLS と cert-manager の連携
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: name: letsencrypt-prod spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: admin@example.com privateKeySecretRef: name: letsencrypt-key solvers: - http01: ingress: class: kong |
- 上記
ClusterIssuerを作成後、Ingress のtls:セクションにsecretNameを指定すれば自動的に証明書が発行・更新されます。
RBAC とログ・ヘルスチェック
|
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: rbac.authorization.k8s.io/v1 kind: Role metadata: namespace: kong name: kong-admin rules: - apiGroups: ["configuration.konghq.com"] resources: ["*"] verbs: ["get","list","watch","create","update","patch","delete"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: kong-admin-binding namespace: kong subjects: - kind: ServiceAccount name: kong-admin-sa namespace: kong roleRef: kind: Role name: kong-admin apiGroup: rbac.authorization.k8s.io |
- Admin API へのアクセスは
kong-adminロールに限定し、最小権限の ServiceAccount にだけ付与します。 - ポッドの稼働状態は次のコマンドで確認できます。
bash
kubectl -n kong get pod -l app=kong -o jsonpath="{.items[*].status.containerStatuses[0].ready}" - Prometheus の
kong_proxy_upstream_latency_ms等をダッシュボードに組み込むと、トラフィックの遅延やエラー率も可視化できます。
デプロイ後の検証手順
本節では、Kong が正しく Service を認識し、Ingress ルーティングが機能しているかを確認する具体的なコマンド例を示します。すべてのチェックが成功したら GitOps リポジトリへマージし、Argo CD / Flux が継続的に状態を保守できることを最終確認してください。
- Admin API で Service 一覧取得
bash
curl -s http://<proxy-service-ip>:8001/services | jq . - ヘルスチェックエンドポイント
bash
curl -s http://<proxy-service-ip>:8001/status | jq . - ログにエラーが無いか確認
bash
kubectl logs -n kong -l app=kong --tail=100 | grep -i error - 実際のリクエストテスト（Bookinfo アプリ）
bash
curl -i http://bookinfo.example.com/
期待したステータスコードとレスポンスが返れば、Gateway Discovery と Ingress 設定は正常に機能しています。
まとめ
- KIC + Helm が最もシンプルで自動化しやすく、Gateway Discovery による Service の即時登録が可能です。
- Operator は CP/DP 分離や高度なカスタマイズが必要なハイブリッド構成に適していますが、Gateway Discovery は未実装です（公式ドキュメント参照）。
- GitOps ツールは Argo CD と Flux v2 のどちらでも対応でき、Manifest を一元管理することで変更履歴と可視性を確保できます。
- 本番環境では Hybrid モード＋ cert-manager + RBAC を組み合わせ、Prometheus でメトリクス監視を行うことが推奨されます。
以上の手順とベストプラクティスに沿って構築すれば、Kong Gateway の導入から運用までを安全かつ効率的に実現できます。