はじめに
Kubernetes にサービスを載せると、すぐに直面する問いがあります。外部トラフィックをどう受け取り、どこへ流すのか、という問いです。最も標準的な答えが Ingress リソースであり、その実装として最も広く使われてきたのが ingress-nginx です。ところが実際のサービスを運用していると、単に「パスベースでトラフィックをルーティングする」だけでは足りなくなる瞬間が訪れます。
たとえば次のような要件が積み重なっていきます。特定の API には毎分 100 回のレートリミットをかける必要があり、パートナー企業の呼び出しには API キー認証を適用する必要があり、レガシーバックエンドへのリクエストにはヘッダーを変換して付与する必要があり、すべてのリクエストを OpenTelemetry でトレースして Prometheus メトリクスとして公開する必要があります。ここまで来ると、私たちが必要としているのは単なるリバースプロキシではなく API Gateway です。
Kong Ingress Controller(以下 KIC)は、まさにこの地点を狙います。KIC は Ingress コントローラーの外観をしていますが、その背後にはフルスタックの API Gateway である Kong Gateway が控えています。つまり Kubernetes ネイティブな方式(Ingress リソース、Gateway API、カスタムリソース)で宣言すると、その宣言が Kong Gateway の強力なプラグインパイプラインに変換されて動作するのです。
本記事では KIC を単なるインストールガイドとしてではなく、「なぜこのように設計され、運用観点で何を知っておくべきか」という視点から深く扱います。アーキテクチャと動作モード、中核となる CRD、代表的なプラグイン、Helm によるデプロイ、declarative config、そして Gateway API との関係とトラブルシューティングまで、コード中心で整理していきます。基準バージョンは 2026 年前半時点の Kong Gateway 3.x 系、KIC 3.x 系、Kubernetes v1.32 系です。
2026 年の Ingress 地形 — なぜ今 Kong を見るのか
まず全体像を整理しておきましょう。2026 年現在、Kubernetes のイングレスエコシステムは重要な転換点を通過しています。
第一に、Ingress API は事実上凍結(frozen)されました。Kubernetes の `networking.k8s.io/v1` Ingress は安定化されましたが、もはや新しい機能は追加されません。TLS 終端や host/path ベースのルーティング程度の標準機能だけが仕様に入っており、それ以外のすべての高度な機能(ヘッダールーティング、トラフィック分割、認証、レートリミット)は各コントローラーのアノテーションという非標準の領域に押し出されています。
第二に、その後継として Gateway API が標準の座を引き継ぎました。Gateway API は役割分離(インフラ運用者とアプリケーション開発者)、表現力のあるルーティング、移植可能な仕様を目標に設計された次世代標準であり、2026 年時点ではコアリソースが GA に到達し、プロダクションで使える段階に入っています。
第三に、最も広く使われてきた ingress-nginx はメンテナンスモード的な性格へ転換する流れがはっきりしています。新機能開発よりもセキュリティ問題対応を中心に運用されており、アノテーションによる任意設定の注入に関連するセキュリティ脆弱性が繰り返し報告されたことで、各組織は代替手段を真剣に検討し始めました。
この三つの流れが交わる地点で、Kong が魅力的な選択肢として浮上します。Kong は Ingress と Gateway API を同時にサポートしながら、ingress-nginx のアノテーション地獄を CRD ベースの構造化された設定で置き換え、何より API Gateway 級の機能をプラグインとして提供するからです。
| 項目 | ingress-nginx | Kong Ingress Controller | 純粋な Gateway API 実装 |
| --- | --- | --- | --- |
| 基盤データプレーン | NGINX | Kong Gateway(NGINX + Lua/OpenResty) | 実装ごとに異なる |
| 標準インターフェース | Ingress | Ingress + Gateway API | Gateway API |
| 高度機能の設定方式 | アノテーション/ConfigMap | CRD(KongPlugin など) + アノテーション | ポリシー CRD/フィルター |
| 認証・レートリミット | 限定的 | プラグイン豊富 | 実装依存 |
| オブザーバビリティ | 基本メトリクス | Prometheus/OTel プラグイン | 実装依存 |
| プロジェクト状態 | メンテナンス中心 | 活発 | 活発 |
表が示すとおり、Kong の差別化点は「API Gateway 機能を Kubernetes ネイティブに宣言的に使える」点にあります。それでは、その構造を一つずつ解きほぐしていきましょう。
Kong Gateway と KIC — 二つのレイヤーを理解する
まず明確にすべきは、「Kong Gateway」と「Kong Ingress Controller」が別個のコンポーネントであるという事実です。多くの初心者がこの二つを混同しますが、両者の役割を分けて理解すれば、その後のすべての概念が容易にほどけます。
Kong Gateway は、実際にトラフィックを処理するデータプレーンです。NGINX と OpenResty(LuaJIT)の上に構築されており、入ってくるリクエストをルート(route)とサービス(service)にマッチさせ、その間でプラグインパイプラインを実行します。これが認証、レートリミット、変換、ロギングを担うエンジンです。
Kong Ingress Controller はコントロールプレーンの役割です。Kubernetes API サーバーを監視(watch)し、Ingress・Gateway API・Kong CRD といったリソースが作成・変更されると、それを Kong Gateway が理解できる設定に翻訳して注入します。つまり KIC は「Kubernetes の宣言 → Kong の設定」を変換する翻訳機であり同期ループです。
+-----------------------------------------------------------------------+
| Kubernetes クラスター |
| |
| [コントロールプレーン] [データプレーン] |
| Kong Ingress Controller ──設定注入──▶ Kong Gateway (プロキシ) |
| | ^ |
| | watch | 実トラフィック処理|
| v | |
| kube-apiserver | |
| |- Ingress / HTTPRoute | |
| |- KongPlugin / KongConsumer | |
| |- Service / Endpoints <───────エンドポイント照会┘ |
| |
+-----------------------------------------------------------------------+
^ |
| kubectl apply v
運用者/開発者 外部クライアントのリクエスト
この分離構造のおかげで、運用者は二つのデプロイパターンのどちらかを選べます。一つはコントローラーとゲートウェイを同じ Pod 内のサイドカーとして束ね、シンプルに運用する方式です。もう一つはコントロールプレーンとデータプレーンを別々のデプロイメントに分離し、データプレーンを独立して水平スケールさせる方式です。トラフィック規模が大きくなると、後者が一般的です。
DB-less モード vs DB モード — 最も重要な選択
KIC を導入するとき、最初に、そして最も重要に決めるべきなのがデータプレーンの動作モードです。Kong Gateway は設定を保管する方式によって二つのモードで動作します。
DB-less モードでは、Kong は外部データベースを持たず、すべての設定をメモリに載せた declarative 設定で動作します。KIC が Kubernetes リソースを読み取って declarative 設定(JSON/YAML)を生成し、それを Kong の Admin API を通じてメモリへ一括適用します。Kubernetes 環境で推奨される標準パターンです。
DB モードでは、Kong は PostgreSQL をバックエンドに置いて設定を永続化します。Admin API で個別エンティティを直接 CRUD できるため柔軟ですが、Kubernetes の上にさらに状態ストアを運用し、マイグレーションジョブを管理する負担が生じます。
| 比較項目 | DB-less モード | DB モード(PostgreSQL) |
| --- | --- | --- |
| 設定ストア | メモリ(declarative) | PostgreSQL |
| 単一の信頼できる情報源 | Kubernetes リソース | データベース |
| 運用の複雑さ | 低い | 高い(DB 運用・マイグレーション) |
| 水平スケール | データプレーンがステートレスで容易 | DB ボトルネックの可能性 |
| Admin API 書き込み | 無効(読み取り専用的) | 有効 |
| GitOps 適合性 | 非常に高い | 普通 |
| 推奨環境 | 一般的な Kubernetes | 一部のエンタープライズ機能が必要な場合 |
中核となる原則を一行で要約するとこうです。Kubernetes の上で KIC を使うなら、特別な理由がない限り DB-less モードをデフォルトにするのがよいでしょう。Kubernetes リソース自体が単一の信頼できる情報源となって GitOps と自然に噛み合い、状態ストアを運用しないことで障害面が減るからです。
次は DB-less モードで KIC が生成する declarative 設定の形を示す例です。運用者が直接書くことはまれですが、トラブルシューティングの際に Kong が実際に何を見ているかを理解するには、この形を知っておくとよいでしょう。
_format_version: "3.0"
services:
- name: example-service.default.80
host: example-service.default.svc
port: 80
protocol: http
routes:
- name: example-route
paths:
- /api
strip_path: true
plugins:
- name: rate-limiting
config:
minute: 100
policy: local
consumers:
- username: partner-a
keyauth_credentials:
- key: secret-api-key-value
中核となる CRD — KongPlugin、KongConsumer、KongIngress
KIC の真の力はカスタムリソースから生まれます。標準 Ingress が表現できないすべてを、Kong は CRD できれいに表現します。最もよく使う三つを見ていきましょう。
KongPlugin と KongClusterPlugin
KongPlugin は KIC を使う理由そのものだと言っても過言ではありません。プラグインを一つ宣言し、それを Ingress・Service・HTTPRoute・Consumer といった対象にアノテーションで付けると、そのトラフィック経路にプラグインが適用されます。
次はレートリミットプラグインを宣言する例です。
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: rl-by-minute
namespace: default
config:
minute: 100
policy: local
plugin: rate-limiting
このように宣言したプラグインを特定の Ingress に適用するには、Ingress 側にアノテーションを付けます。複数のプラグインをカンマで並べて同時に適用することもできます。
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-ingress
namespace: default
annotations:
konghq.com/plugins: rl-by-minute,key-auth-plugin
konghq.com/strip-path: "true"
spec:
ingressClassName: kong
rules:
- host: api.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: example-service
port:
number: 80
KongPlugin は名前空間スコープであり、同じ役割をクラスター全体に適用したいときは KongClusterPlugin を使います。すべてのワークロードに共通でかけるセキュリティヘッダーやグローバルロギングプラグインに適しています。
KongConsumer と認証
KongConsumer は Kong の世界における「呼び出し主体」を表現します。パートナー企業、内部サービス、特定のクライアントなどを Consumer として登録し、そこに認証クレデンシャル(API キー、JWT など)を結び付けます。こうすることで「誰が呼び出したか」を識別でき、Consumer ごとに異なるレートリミットや権限を適用できます。
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
name: partner-a
namespace: default
annotations:
kubernetes.io/ingress.class: kong
username: partner-a
credentials:
- partner-a-apikey
クレデンシャルは一般にシークレットとして分離して管理します。次は key-auth 用の API キーをシークレットとして定義した例です。
apiVersion: v1
kind: Secret
metadata:
name: partner-a-apikey
namespace: default
labels:
konghq.com/credential: key-auth
type: Opaque
stringData:
key: super-secret-partner-a-key
KongIngress と新型 CRD の流れ
KongIngress は、ルートとサービスの細かな動作(プロトコル、タイムアウト、リトライ、パス処理方式など)を調整するための伝統的な CRD でした。ただし 2026 年時点では、この役割が KongUpstreamPolicy、そして Service アノテーションと Gateway API ポリシーへと徐々に分化していく流れです。新規に始めるプロジェクトなら、KongIngress 一つにすべての設定を詰め込むより、アップストリームの動作は KongUpstreamPolicy で、プラグインは KongPlugin で分けて表現する方式が推奨されます。
次はアップストリームのヘルスチェックとロードバランシングアルゴリズムを KongUpstreamPolicy で定義した例です。
apiVersion: configuration.konghq.com/v1beta1
kind: KongUpstreamPolicy
metadata:
name: example-upstream-policy
namespace: default
spec:
algorithm: least-connections
healthchecks:
active:
type: http
httpPath: /healthz
healthy:
interval: 5
successes: 1
unhealthy:
interval: 5
httpFailures: 3
このポリシーを適用するには、対象の Service にアノテーションで結び付けます。
apiVersion: v1
kind: Service
metadata:
name: example-service
namespace: default
annotations:
konghq.com/upstream-policy: example-upstream-policy
spec:
selector:
app: example
ports:
- port: 80
targetPort: 8080
中核プラグインエコシステムを巡る
Kong の真の価値はプラグインエコシステムです。数十種類の公式プラグインとコミュニティプラグインがあり、大きく五つの系統に分けて理解すると便利です。
| 分類 | 代表プラグイン | 行うこと |
| --- | --- | --- |
| 認証 | key-auth, jwt, oauth2, basic-auth, ldap-auth, openid-connect | 呼び出し主体の識別と認証 |
| トラフィック制御 | rate-limiting, request-termination, proxy-cache, request-size-limiting | 流量制御と保護 |
| 変換 | request-transformer, response-transformer, correlation-id | ヘッダー・ボディ・クエリの操作 |
| オブザーバビリティ | prometheus, opentelemetry, http-log, file-log, datadog | メトリクス・トレース・ログ |
| セキュリティ | cors, ip-restriction, bot-detection, acl | アクセス制御と防御 |
各分類を代表例を中心に見ていきましょう。
認証 — key-auth と OIDC
最もシンプルな認証は key-auth です。先ほど見たように Consumer に API キーを結び付け、ルートに key-auth プラグインをかけると、ヘッダーやクエリで渡されたキーを検証して Consumer を識別します。
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: key-auth-plugin
namespace: default
config:
key_names:
- apikey
key_in_header: true
key_in_query: false
plugin: key-auth
エンタープライズ環境では、openid-connect プラグインで Keycloak や社内 IdP と連携し、OIDC ベースの認証を適用するケースが多くあります。この場合、ゲートウェイ側でトークン検証を処理するため、バックエンドサービスは認証ロジックから解放されます。
トラフィック制御 — rate-limiting
レートリミットは最もよく使うプラグインです。分・時・日単位の上限を設定でき、上限計算ポリシーとしてローカル・クラスター・Redis を選べます。複数のデータプレーン Pod 間で上限を共有するには Redis ポリシーが正確です。ローカルポリシーは速いものの、Pod ごとに上限が別々に計算される点を覚えておく必要があります。
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: rl-redis
namespace: default
config:
minute: 100
hour: 2000
policy: redis
redis:
host: redis-master.default.svc
port: 6379
plugin: rate-limiting
変換 — request-transformer
レガシーバックエンドと通信するとき、リクエストヘッダーを追加・削除・変更する必要がよくあります。request-transformer はこうした作業をゲートウェイ側で処理します。
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: add-legacy-headers
namespace: default
config:
add:
headers:
- "X-Gateway: kong"
- "X-Forwarded-Prefix: /api"
remove:
headers:
- "X-Internal-Token"
plugin: request-transformer
オブザーバビリティ — prometheus と opentelemetry
運用の核は可視性です。prometheus プラグインをグローバルにかけると、リクエスト数、レイテンシ、ステータスコード、アップストリームのヘルスといったメトリクスを Prometheus 形式で公開します。opentelemetry プラグインは分散トレースを OTLP でエクスポートし、ゲートウェイを通るリクエストの流れを追跡できるようにします。
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: prometheus
annotations:
kubernetes.io/ingress.class: kong
labels:
global: "true"
config:
status_code_metrics: true
latency_metrics: true
bandwidth_metrics: true
plugin: prometheus
`global: "true"` ラベルが付いた KongClusterPlugin は、すべてのルートに自動で適用されます。オブザーバビリティプラグインはこうしたグローバル適用方式と特に相性が良いです。
リクエストが流れる全経路
ここまで見たコンポーネントが実際のリクエストでどう噛み合うかを一枚の図に整理すると、次のようになります。
外部クライアント
| GET https://api.example.com/api/orders (apikey ヘッダー含む)
v
[ロードバランサー / Service type=LoadBalancer]
|
v
[Kong Gateway データプレーン Pod]
|
|- 1. ルートマッチ: host=api.example.com, path=/api --> example-service
|
|- 2. プラグインパイプライン(リクエスト段階)
| |- cors (プリフライト処理)
| |- key-auth (apikey 検証 -> Consumer=partner-a 識別)
| |- acl (partner-a が許可グループか確認)
| |- rate-limiting (partner-a の分単位上限確認)
| |- request-transformer (ヘッダー加工)
|
|- 3. アップストリーム選択(KongUpstreamPolicy: least-connections + healthcheck)
|
v
[example-service -> Pod エンドポイント]
|
v レスポンス
[Kong Gateway データプレーン]
|
|- 4. プラグインパイプライン(レスポンス段階)
| |- response-transformer
| |- prometheus / opentelemetry (メトリクス・トレース記録)
|
v
外部クライアントへレスポンス返却
この流れで重要なのは、プラグインが段階と優先度に従って順に実行される点です。たとえば認証(key-auth)はレートリミット(rate-limiting)より先に実行されなければ「誰の上限か」が分かりません。Kong は各プラグインに既定の優先度を設けてこの順序を保証し、必要なら運用者が優先度を調整することもできます。
Ingress と Gateway API の同時サポート
先に触れたとおり、2026 年の核心テーマは Gateway API です。KIC の大きな利点は、伝統的な Ingress と新標準の Gateway API の両方をサポートする点です。おかげで既存の Ingress 資産を維持しながら、段階的に Gateway API へ移行できます。
Gateway API では役割が分離されます。インフラ運用者は GatewayClass と Gateway でリスナーとインフラを定義し、アプリケーション開発者は HTTPRoute でルーティングルールを宣言します。KIC はこれらのリソースをすべて処理します。
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
name: kong
spec:
controllerName: konghq.com/kic-gateway-controller
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: kong-gateway
namespace: default
spec:
gatewayClassName: kong
listeners:
- name: http
protocol: HTTP
port: 80
HTTPRoute は host と path だけでなく、ヘッダー、メソッド、クエリパラメータベースのマッチングを標準で表現できます。これは Ingress がついに標準化できなかった領域でした。
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: orders-route
namespace: default
spec:
parentRefs:
- name: kong-gateway
hostnames:
- api.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /api/orders
headers:
- name: X-Api-Version
value: v2
backendRefs:
- name: orders-service
port: 80
プラグインは Gateway API 環境でも同様に適用されます。HTTPRoute に KongPlugin アノテーションを付けるか、Gateway API 標準のポリシー付与メカニズムを通じて結び付けます。つまり標準インターフェースは Gateway API へ持っていきつつ、Kong の豊富なプラグインエコシステムはそのまま享受できます。
実務的に推奨される経路はこうです。新規クラスターなら最初から Gateway API で始め、既存の Ingress ベースのクラスターなら KIC に統一したうえで Ingress と Gateway API を併行運用し、HTTPRoute で段階的に移行することです。二つの標準が同じコントローラーの下で共存できる点が KIC の大きな強みです。
Helm でデプロイする
それでは実際のデプロイに移ります。KIC の標準的なデプロイ方式は Helm チャートであり、単一のチャートでコントローラーとゲートウェイをともに導入できます。まず Helm リポジトリを追加します。
helm repo add kong https://charts.konghq.com
helm repo update
kubectl create namespace kong
次は DB-less モードでデプロイするための values ファイルの例です。コントローラーを有効化し、ゲートウェイを LoadBalancer で公開し、プロキシと Admin API の設定を明示します。
ingressController:
enabled: true
installCRDs: false
ingressClass: kong
env:
database: "off"
router_flavor: expressions
proxy:
enabled: true
type: LoadBalancer
http:
enabled: true
servicePort: 80
tls:
enabled: true
servicePort: 443
admin:
enabled: true
type: ClusterIP
http:
enabled: true
resources:
requests:
cpu: 500m
memory: 512Mi
limits:
cpu: "2"
memory: 1Gi
replicaCount: 2
CRD は別途、先にインストールするほうが安全です。チャートに CRD のインストールを任せるとアップグレード時に衝突しうるので、CRD は明示的に管理するほうが運用上きれいです。
kubectl apply -f https://github.com/Kong/kubernetes-ingress-controller/releases/latest/download/all-in-one-dbless.yaml
values ファイルが用意できたらインストールします。
helm install kong kong/ingress \
--namespace kong \
--values values-dbless.yaml
インストールが終わったら、ゲートウェイサービスの外部 IP とコントローラーの状態を確認します。
kubectl get pods -n kong
kubectl get svc -n kong
kubectl get ingressclass
IngressClass に `kong` が見え、ゲートウェイサービスに EXTERNAL-IP が割り当てられていれば、トラフィックを受ける準備が整ったということです。その後は、先に見た Ingress・HTTPRoute・KongPlugin リソースを適用してルーティングとポリシーを構成すればよいでしょう。
Declarative config と GitOps
DB-less モードの最大の魅力は、すべての設定が Kubernetes リソースとして表現され、そのまま Git に収まる点です。これは GitOps と自然に噛み合います。Argo CD や Flux でマニフェストを同期すれば、ゲートウェイ設定の変更履歴とロールバックが、そのまま Git ワークフローの中で管理されます。
Kubernetes の外で Kong も併用する組織なら、decK というツールも知っておく価値があります。decK は Kong の declarative 設定をコードとして管理し、現在の状態と望む状態の差分(diff)を示し、同期する CLI です。KIC が生成した設定をエクスポート(dump)して検証したり、環境間で設定を比較したりするのに便利です。
deck gateway dump --kong-addr http://localhost:8001 -o kong-state.yaml
deck gateway diff kong-state.yaml --kong-addr http://localhost:8001
ただし KIC と decK を同時に同じゲートウェイに使うときは注意が必要です。DB-less モードでは単一の信頼できる情報源が Kubernetes リソースであるべきなので、decK はエクスポートと検証用途に限定し、設定変更は Kubernetes リソースを通じてのみ行う規律を守ることが衝突を防ぐ道です。
運用とチューニング
プロダクションで KIC を安定して運用するには、いくつかの核心ポイントを押さえる必要があります。
第一に、データプレーンの水平スケールです。DB-less モードのゲートウェイはほぼステートレスなので、replica を増やすだけでスループットを伸ばせます。ただし rate-limiting のローカルポリシーは Pod ごとに上限を別々に計算するため、正確なグローバル上限が必要なら Redis ポリシーに変える必要があります。
第二に、ヘルスチェックとプローブです。Kong はステータスエンドポイントを提供するので、それを readiness と liveness プローブに結び付け、不健全な Pod を素早く隔離すべきです。また、アップストリームのヘルスチェック(active/passive)を KongUpstreamPolicy で設定し、死んだバックエンド Pod へトラフィックが行かないようにします。
第三に、リソースとワーカーのチューニングです。NGINX ワーカープロセス数、コネクション上限、タイムアウトといった値はトラフィック特性に合わせて調整すべきです。特にアップストリームの keepalive コネクションプールを適切に大きくすると、リクエストごとにバックエンドと新しいコネクションを張るコストを減らせます。
第四に、TLS と証明書の管理です。cert-manager と連携して証明書の発行と更新を自動化するのが標準です。Ingress の TLS セクションや Gateway のリスナーに証明書シークレットを結び付け、cert-manager が Let's Encrypt などで自動更新するように構成します。
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: api-example-com-tls
namespace: default
spec:
secretName: api-example-com-tls
dnsNames:
- api.example.com
issuerRef:
name: letsencrypt-prod
kind: ClusterIssuer
第五に、セキュリティ境界です。Admin API は絶対に外部へ公開してはいけません。ClusterIP に留めるかネットワークポリシーでアクセスを制限し、DB-less モードでは Admin API を読み取り専用に近い形で運用するのが安全です。ingress-nginx で繰り返し問題になった「任意設定の注入」の類の脆弱性を避けるには、プラグイン設定を信頼できるソース(Git、レビュー済みマニフェスト)からのみ管理すべきです。
よく出会う落とし穴とトラブルシューティング
運用中によく直面する問題を、原因とともに整理しました。
第一に、IngressClass の欠落です。Ingress に `ingressClassName: kong` を指定しないと、KIC はその Ingress を無視します。ルーティングがまったく動かないのにログも静かなら、まずこれを疑うべきです。Gateway API では、GatewayClass の `controllerName` が KIC のコントローラー名と正確に一致しているか確認します。
第二に、プラグインアノテーションの誤記です。`konghq.com/plugins` アノテーションに書いた名前が実際の KongPlugin リソース名と異なる、あるいは名前空間がずれていると、プラグインが適用されません。プラグインがかからないように見えるときは、KongPlugin リソースの名前と名前空間、そしてアノテーション文字列を突き合わせます。
第三に、strip_path の混乱です。`konghq.com/strip-path` を true にすると、マッチしたパス接頭辞が削除されてバックエンドへ転送されます。バックエンドが受け取るパスが想定と異なるなら、この設定を確認します。`/api` で入ってきたリクエストがバックエンドに `/` で届くのか、`/api` で届くのかがここで分かれます。
第四に、設定反映の遅延です。KIC は変更を検知してゲートウェイに同期しますが、大量変更や大規模クラスターでは多少の遅延がありえます。変更が反映されていないように見えるときは、コントローラーログで同期の成否と最後の同期時刻を確認します。
第五に、declarative config の検証失敗です。KIC が生成した declarative 設定に誤りがあると(例: 不正なプラグイン config スキーマ)、ゲートウェイは新しい設定を拒否して最後の正常な設定を維持します。つまり「不正な変更を適用したのに何も起きなかった」ように見えることがあります。このときはコントローラーログで検証エラーメッセージを探すのが鍵です。
診断に役立つコマンドをまとめておくと次のとおりです。
kubectl logs -n kong deploy/kong-controller -c ingress-controller --tail=200
kubectl describe ingress api-ingress -n default
kubectl get kongplugin -A
kubectl get kongconsumer -A
kubectl port-forward -n kong svc/kong-admin 8001:8001
最後のコマンドで Admin API にポートフォワードしたうえで、ゲートウェイが実際に保持しているルート・サービス・プラグインの状態を直接照会すれば、Kubernetes の宣言と実際の適用との差を最も素早く縮められます。
第六に、検証 Webhook(admission webhook)の拒否です。KIC は検証 Webhook で不正なプラグイン設定や重複クレデンシャルを事前に防げます。`kubectl apply` が拒否されたら、Webhook のメッセージをそのまま読むのが最速の解決策です。Webhook は不正な設定がゲートウェイまで届く前に止めてくれる安全網なので、無効化するよりメッセージを解釈して直すほうが望ましいです。
おわりに
KIC は単なる Ingress コントローラーではなく、Kubernetes ネイティブな宣言をフルスタックの API Gateway につなぐ橋です。Ingress API が凍結され Gateway API が標準の座を引き継いだ 2026 年の地形において、KIC は二つの標準をともにサポートしながら、プラグインエコシステムという強力な差別化点を提供します。
導入を検討するなら、次の順序を推奨します。まず DB-less モードをデフォルトにして運用の複雑さを下げ、設定はすべて Kubernetes リソースとして表現して GitOps に乗せます。認証・レートリミット・オブザーバビリティといった核心機能は最初からプラグインとしてきれいに分離し、バックエンドを軽く保ちます。新規ルーティングは Gateway API の HTTPRoute で表現しつつ、既存の Ingress 資産は同じコントローラーの下で併行運用し、段階的に移行します。
何より重要なのは、「アノテーションにすべてを詰め込んでいた時代」から「構造化された CRD と標準 Gateway API でポリシーを表現する時代」へ移っていく流れを理解することです。Kong はその転換を比較的滑らかに踏んでいけるツールであり、API Gateway が必要な組織なら真剣に検討する価値が十分にあります。
参考資料
- Kong Ingress Controller 公式ドキュメント: https://docs.konghq.com/kubernetes-ingress-controller/
- Kong Gateway 公式ドキュメント: https://docs.konghq.com/gateway/
- Kong プラグインハブ: https://docs.konghq.com/hub/
- Kong KIC GitHub リポジトリ: https://github.com/Kong/kubernetes-ingress-controller
- Kubernetes Ingress コンセプトドキュメント: https://kubernetes.io/docs/concepts/services-networking/ingress/
- Gateway API 公式ドキュメント: https://gateway-api.sigs.k8s.io/
- ingress-nginx ドキュメント: https://kubernetes.github.io/ingress-nginx/
- cert-manager 公式ドキュメント: https://cert-manager.io/docs/
- decK ドキュメント: https://docs.konghq.com/deck/
- Kong Helm チャートリポジトリ: https://github.com/Kong/charts
현재 단락 (1/400)
Kubernetes にサービスを載せると、すぐに直面する問いがあります。外部トラフィックをどう受け取り、どこへ流すのか、という問いです。最も標準的な答えが Ingress リソースであり、その実装と...