Kong Gatewayとは？UpstreamとService/Routeで理解するAPIゲートウェイの設定

Kong Gatewayは、OpenResty（nginx＋LuaJIT）上で動作するオープンソースのAPIゲートウェイです。マイクロサービスの入口でリクエストを受け、認証・レート制限・負荷分散をプラグインで付与します。この記事では、負荷分散の中核であるUpstreamとターゲットの設定を軸に、ServiceとRouteによるAPI公開、decKによる宣言型管理、NGINX・Traefikとの違いまでを、Admin APIの実際のコマンドで解説します。バージョンは最新の3.15系（2026年7月時点）を前提とします。

まとめ：Kong Gatewayの設定の全体像

Kong Gatewayは4つのエンティティで構成されます。Serviceがバックエンドの宛先、Routeがクライアントからの入口条件、Upstreamが複数サーバーへ振り分ける仮想ホスト、Targetが実際のサーバーです。単一サーバーならServiceに直接URLを書けば足り、複数サーバーへ負荷分散するときだけUpstreamを挟みます。負荷分散アルゴリズムは既定のround-robinのほか、セッション維持向けのsticky-sessions／consistent-hashing、混雑回避向けのleast-connections／latencyを選べます。運用では設定をkong.yamlに宣言してdecKでGitOps管理するのが定石です。以下、各エンティティの役割と実際の設定手順を順に見ていきます。

Kong Gatewayの位置づけとエディション（OSS/Free/Enterprise）

Kong Gatewayは、APIリクエストをバックエンドへ中継するリバースプロキシに、認証・レート制限・ログ・監視などをプラグインとして載せられる製品です。APIゲートウェイの役割とリバースプロキシ・サービスメッシュとの違いを押さえると、Kongがどの層を担うのか理解しやすくなります。マイクロサービスの前段に置き、各サービスへの共通処理を一箇所に集約する用途が中心です。

DBありモードとDB-lessモードの違い

Kong Gatewayは設定の保存方法で2モードに分かれます。DBありモードはPostgreSQLに設定を保存し、Admin APIで動的に変更できます。DB-lessモードはデータベースを持たず、kong.yamlという宣言ファイルをメモリに読み込んで動作します。DB-lessは構成をコードで固定できるためコンテナ環境やGitOpsに向き、DBありは実行中の頻繁な設定変更や大規模なコンシューマー管理に向きます。判断基準は「設定を実行時に変えるか、デプロイ時に固定するか」です。

OSS版・Freeティア・Enterprise版の違い

Kongのエディションは2026年時点で整理が進み、注意が必要です。OSS版（Apache 2.0）はkong/kongイメージで配布されてきましたが、公式のプレビルドコンテナは3.9系が最後で、3.10以降はプレビルド提供がなく、利用にはソースからのビルドが必要です。3.10以降のGatewayディストリビューション（kong/kong-gateway）では、ライセンス無しで無償稼働する従来のfree modeが廃止され、無償利用はKong Managerを同梱するKong Gateway Freeティアに集約されました。Enterprise版はこれにRBAC・シークレット管理・OpenID Connect・mTLS・商用サポートを追加します。プロキシ・負荷分散・ヘルスチェックといった中核機能はいずれでも使えるため、まず検証するならFreeティア（または最終プレビルドのOSS 3.9系）、組織横断のガバナンスが要る段階でEnterpriseという順序になります。

ServiceとRouteによるAPI公開

APIの公開は、バックエンドを表すServiceと、入口条件を表すRouteの2つで成立します。ServiceにはバックエンドのURL（プロトコル・ホスト・ポート・パス）を登録し、RouteにはそのServiceへ振り向けるパス・ホスト名・HTTPメソッドの条件を設定します。1つのServiceに複数のRouteを紐付けられるため、同じバックエンドを異なる入口で公開できます。

Admin APIでのService／Route作成

Admin API（既定でポート8001）へPOSTすれば、ServiceとRouteを作成できます。次はexample-serviceを作り、/apiで始まるパスを紐付ける例です。

# Service を作成（バックエンド example.com:8080 を登録）
curl -i -X POST http://localhost:8001/services \
  --data name=example-service \
  --data url=http://example.com:8080

# その Service に Route を追加（/api で始まるパスを受ける）
curl -i -X POST http://localhost:8001/services/example-service/routes \
  --data name=example-route \
  --data paths[]=/api

設定後は、プロキシポート（既定8000）に/api宛のリクエストを送ると、example-service経由でバックエンドへ中継されます。

複数Routeが一致したときの優先順位

1つのリクエストに複数のRouteが一致する場合、Kongは優先順位で1つを選びます。従来型ルーター（traditional）では、より限定的な条件（長いパス・正規表現の有無）が優先され、正規表現パスはregex_priorityの大きいものから評価されます。式ルーター（expressions）では、Routeごとのpriorityフィールドで評価順を明示できます。意図しないRouteにリクエストが吸われる事故を避けるには、広いパス（/など）を持つRouteのpriorityを下げ、限定的なRouteを先に評価させるのが基本です。

Upstreamとターゲットによる負荷分散

複数のバックエンドサーバーへ振り分けるときにUpstreamを使います。Upstreamは負荷分散の宛先を束ねる仮想ホストで、その配下に実サーバーをTargetとして登録します。ServiceのURLのホスト部分にUpstream名を指定すると、リクエストはUpstreamのアルゴリズムに従って各Targetへ分散されます。単一サーバーならUpstreamは不要で、Serviceに直接URLを書けば足ります。

負荷分散アルゴリズムの選択基準

Upstreamのalgorithmフィールドで振り分け方式を選びます。用途別の目安は次のとおりです。

consistent-hashingを選んだ場合は、ハッシュの入力をhash_onで指定します。値はconsumer・cookie・header・ip・path・query_arg・uri_captureと、ハッシュを使わないnone（既定）です。たとえば同一クライアントを常に同じTargetへ固定したいならip、ヘッダー値で振り分けるならheaderを使います。

Admin APIでのUpstream・Target設定

Upstreamを作成し、Targetを重み付きで登録します。weightの既定値は100で、大きいほど多くのリクエストを受けます。weightを0にするとそのTargetは振り分け対象から外れます。

# Upstream を作成（アルゴリズムは least-connections を指定）
curl -i -X POST http://localhost:8001/upstreams \
  --data name=example-upstream \
  --data algorithm=least-connections

# Target を2台登録（weight で配分比を調整）
curl -i -X POST http://localhost:8001/upstreams/example-upstream/targets \
  --data target=10.0.0.1:8080 --data weight=100
curl -i -X POST http://localhost:8001/upstreams/example-upstream/targets \
  --data target=10.0.0.2:8080 --data weight=50

あとはServiceのhostにUpstream名（example-upstream）を指定すれば、そのServiceへのリクエストが2台のTargetへ100対50の比で分散されます。

ヘルスチェックとサーキットブレーカー

異常なTargetを自動で切り離すのがヘルスチェックです。アクティブは定期的にプローブを送って生死を判定し、パッシブは実トラフィックの応答を監視して異常を検知します（サーキットブレーカー相当）。パッシブは実際の通信を見るだけなので追加負荷がなく、まず有効化しやすい方式です。

# パッシブヘルスチェック: 5xx を3回返した Target を切り離す
curl -i -X PATCH http://localhost:8001/upstreams/example-upstream \
  --data healthchecks.passive.unhealthy.http_statuses[]=500 \
  --data healthchecks.passive.unhealthy.http_statuses[]=503 \
  --data healthchecks.passive.unhealthy.http_failures=3

アクティブ側はhealthchecks.active.http_path（既定は/）やinterval、復帰条件のhealthy.successesを設定します。Upstream全体を健全と見なす最小の重み割合はthreshold（0〜100）で決められ、健全なTargetの合計重みがこの割合を下回るとUpstream自体を異常とみなします。切り離しの閾値を厳しくしすぎると一時的なスパイクで全台が落ちる事故につながるため、http_failuresは実際のエラー率を見て調整します。

宣言型設定とdecKによるGitOps

Admin APIでの逐次設定は手軽ですが、本番運用では設定をファイルで管理し、Gitで変更履歴を残す方式が主流です。KongはこれをDB-lessモードとdecKで実現します。モノリスからマイクロサービスへ移行してサービス数が増えるほど、設定をコード化して差分管理する効果が大きくなります。

kong.yamlでの宣言的設定

DB-lessモードでは、全エンティティを1つのkong.yamlに書きます。先頭に_format_versionを宣言し、Service・Route・Upstream・Targetをネストして記述します。

_format_version: "3.0"
services:
  - name: example-service
    url: http://example-upstream
    routes:
      - name: example-route
        paths:
          - /api
upstreams:
  - name: example-upstream
    algorithm: least-connections
    targets:
      - target: 10.0.0.1:8080
        weight: 100
      - target: 10.0.0.2:8080
        weight: 50

decKでの設定同期

decKは、稼働中のKongと宣言ファイルの差分を取り、片方向に同期するCLIツールです。現行の設定を書き出すdeck gateway dumpと、ファイルの内容をKongへ反映するdeck gateway syncを使います。CI/CDでsyncを実行すれば、Gitにマージされた設定がそのまま本番へ反映される仕組みを作れます。

# 現在の設定を kong.yaml に書き出す
deck gateway dump -o kong.yaml

# kong.yaml の内容を Kong に反映（差分のみ適用）
deck gateway sync kong.yaml

syncは差分だけを適用するため、手動でAdmin APIを叩いて生じた設定ドリフトも、ファイルを正としてまとめて是正できます。

Docker・KubernetesでのKong Gateway実行

Kong Gatewayは配置環境を問わず動きます。検証はDocker、本番のマイクロサービス基盤ではKubernetesが典型です。

DockerでのKong Gateway起動

ライセンス不要で最短に検証するなら、公式プレビルドのOSSイメージ（kong/kong）の最終版である3.9系を、DB-lessモードで起動します。データベースの準備が不要なため、kong.yamlをマウントすればコンテナ1つで動きます。

docker run -d --name kong \
  -v "$(pwd):/kong/declarative" \
  -e "KONG_DATABASE=off" \
  -e "KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yaml" \
  -p 8000:8000 -p 8001:8001 \
  kong/kong:3.9

3.10以降を使う場合はkong/kong-gatewayイメージ（Kong Gateway Freeティア）を用います。free mode廃止により、ライセンス無しでの稼働挙動が変わった点に注意してください。

Kubernetes Ingress Controllerでの運用

Kubernetesでは、Kong Ingress Controller（KIC）がIngressリソースを監視してKongの設定を自動生成します。導入はHelmチャートとhelm repo addなどのコマンドで行うのが標準です。負荷分散のアルゴリズムやヘルスチェックは、Admin APIの代わりにKongUpstreamPolicyというカスタムリソースで宣言し、Serviceに紐付けて制御します。KubernetesのService単位でLB方式を切り替えられるため、マニフェストだけで負荷分散を管理できます。

NGINX・Traefikとの違いと使い分け

KongはOpenResty（nginx）上に構築されているため、素のNGINXと二者択一ではなく「NGINXにAPI管理層を足したもの」と捉えると選定を誤りません。純粋なリバースプロキシやロードバランサーで足りるならNGINX単体で十分で、認証・レート制限・APIキー管理・監視を設定ではなくプラグインで統一運用したいときにKongが効きます。

Traefikはコンテナのラベルから設定を自動検出する手軽さが強みで、Kubernetes単体構成では選ばれやすい一方、Kongはオンプレ・クラウド・Kubernetesを横断して同じプラグインエコシステムで運用を統一できる点で分があります。マネージド型を含めて比較したいなら、Azure API Managementの料金プランとできることやAWSでのCloudFront・API Gateway・Lambdaの連携も併せて検討すると、自前運用とマネージドの境界が見えてきます。

認証・セキュリティプラグインの構成と保護対象

Kongのセキュリティは、Serviceやルート単位でプラグインを有効化して構成します。APIキー認証のkey-auth、トークン発行のoauth2、レート制限のrate-limiting、IP制御のip-restrictionが基本です。OpenID ConnectやmTLSといった高度な認証はEnterprise版のプラグインで提供されます。注意点として、Admin API（ポート8001）は設定を丸ごと操作できる管理面なので、外部に露出させず、ネットワーク制限や認証で必ず保護します。ここが漏れると、プロキシ側をいくら固めても設定ごと乗っ取られます。

よくある質問

Kong Gatewayとは何ですか？

OpenResty（nginx＋LuaJIT）上で動くオープンソースのAPIゲートウェイです。マイクロサービスの前段でリクエストを受け、ルーティング・負荷分散・認証・レート制限をプラグインで付与します。最新は3.15系です。

KongとNGINXの違いは何ですか？

KongはNGINX（OpenResty）を基盤にしており、対立する製品ではありません。NGINXは汎用のリバースプロキシ／Webサーバー、KongはそこにAPI管理（認証・レート制限・APIキー・監視）をプラグインで載せた上位層です。API管理が不要ならNGINX単体で足ります。

UpstreamとServiceの違いは何ですか？

Serviceはバックエンドの宛先定義、Upstreamは複数サーバーへ負荷分散するための仮想ホストです。単一サーバーならServiceにURLを直接書き、複数サーバーへ振り分けるときだけServiceのhostにUpstream名を指定してTargetを束ねます。

Kong GatewayはDB-lessモードで使えますか？

使えます。データベースを持たず、kong.yamlに宣言した設定をメモリに読み込んで動作します。設定をコードで固定できるためコンテナやGitOpsに向き、decKでファイルとKongを同期して運用します。

Kong Gatewayは無料で使えますか？

OSS版はApache 2.0ライセンスで無償です。プロキシ・負荷分散・ヘルスチェック・key-auth・OAuth 2.0・レート制限などの基本機能を含みます。管理GUIのKong Manager、RBAC、OpenID Connect、mTLS、サポートはEnterprise版で提供されます。

関連記事

• APIゲートウェイとは？役割・機能とリバースプロキシ／サービスメッシュとの違い・導入判断を解説
• Azure API Managementとは？料金プラン・できること・使い方を解説【2026年版】
• AWS CloudFront、API Gateway、Lambdaの連携とは何か？基本解説
• Helmとは？チャート・リポジトリ・リリースの基本とhelm repo addなど主要コマンド解説
• モノリスとは？マイクロサービス・モノリシックとの違いとメリット・デメリット、モジュラモノリスまで整理