Contents
1. 前提条件とインフラ要件
Kong をコンテナ化して稼働させる前に、ホスト側の Docker エンジンと Compose のバージョン、ネットワーク構成を整えておく必要があります。これらが推奨レベルに満たない場合、イメージが提供する機能（ヘルスチェックやリソース制限）が正しく動作しないことがあります。
1.1 Docker Engine のバージョン
Docker Engine は 20.10 以降 を推奨します。2026 年現在の最新版は 24.x 系です。以下コマンドでバージョンを確認し、古い場合は公式インストーラかパッケージマネージャで更新してください。
|
1 2 |
docker version |
1.2 Docker Compose のバージョン
Compose v2 系 を必ず使用します。v1 はプラグインやリソース制限の記述が非推奨となっており、将来的にサポートが終了します。
|
1 2 |
docker compose version # 「Docker Compose version v2.x」 が表示されることを確認 |
1.3 ネットワークとポート要件
| 項目 | 推奨設定 |
|---|---|
| Docker ネットワーク | カスタムブリッジネットワーク（例: kong-net）を作成し、すべてのコンテナを同一に接続 |
| 公開ポート | 8000 (HTTP), 8443 (HTTPS), 8001 (Admin API) をホスト側で公開 |
| DB 用ポート | PostgreSQL は内部ネットワークだけで 5432 を利用（外部からは遮断） |
| ファイアウォール | 8001 は管理者 IP のみ許可し、一般クライアントからのアクセスはブロック |
ポイント：上記条件が整っていれば、公式イメージに組み込まれたヘルスチェックやリソース制限をそのまま利用できます。
2. Kong 公式 Docker イメージの取得とタグ選択
Kong の公式イメージは Docker Hub に kong:<version> として公開されています。タグごとの特徴と、本ガイドで推奨するイメージを確認してください。
2.1 推奨タグと取得コマンド
|
1 2 |
docker pull kong:3.4.0 # Debian ベースのフルイメージ（OSS）を取得 |
| タグ | 内容 | 本番での推奨度 |
|---|---|---|
latest |
最新安定版（2026‑06 時点では 3.5 系） | テスト環境専用 |
3.4.0-alpine |
Alpine Linux ベース、サイズ小 | 軽量化が必須でプラグイン依存が少ない場合 |
enterprise-3.4.0 |
Kong Enterprise（有料）機能付き | 商用サポートが必要なケース |
ポイント：OSS の
kong:3.4.0（Debian ベース）は、プラグインのライブラリ依存が少なく、安定性が最も高いと評価されています。
3. DB‑less モードでのデプロイ手順
DB‑less は Declarative Config（宣言的設定）だけで Kong を起動できるシンプル構成です。外部データベースを持たないため、永続化やマイグレーションの管理が不要になります。
3.1 Declarative Config の正しいパス確認
公式イメージでは KONG_DECLARATIVE_CONFIG に指定するファイルはコンテナ内部の任意パスで構いませんが、デフォルト例として /usr/local/kong/declarative/kong.yaml がよく使われます。実際に使用するイメージのバージョンやベース OS により異なる場合があるため、以下コマンドでコンテナ内にファイルを配置した後に確認してください。
|
1 2 |
docker run --rm -it kong:3.4.0 ls /usr/local/kong/declarative |
存在しない場合は KONG_DECLARATIVE_CONFIG に自分がマウントするパス（例：/etc/kong/kong.yaml）を設定すれば問題ありません。
3.2 ヘルスチェック URL の選定
Kong 3.x 系では Admin API のヘルスエンドポイントは /status が非推奨となり、代わりに /health（v1）または /v2/status が提供されています。使用しているバージョンで利用可能なエンドポイントを公式ドキュメントで確認し、Compose ファイルの healthcheck に反映させましょう。
|
1 2 3 |
# 例: Kong 3.4.x の場合は /status がまだ有効だが、将来に備えて /v2/status を併用 test: ["CMD", "curl", "-f", "http://localhost:8001/v2/status"] |
3.3 docker‑compose.yml（DB‑less）
|
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 |
version: "3.9" services: kong: image: kong:3.4.0 container_name: kong-db-less restart: unless-stopped environment: KONG_DATABASE: off # DB‑less モードを明示 # 実際にマウントしたパスを正確に指定（例は公式デフォルト） KONG_DECLARATIVE_CONFIG: /usr/local/kong/declarative/kong.yaml KONG_PROXY_ACCESS_LOG: /dev/stdout KONG_ADMIN_ACCESS_LOG: /dev/stdout KONG_PROXY_ERROR_LOG: /dev/stderr KONG_ADMIN_ERROR_LOG: /dev/stderr ports: - "8000:8000" - "8443:8443" - "8001:8001" volumes: # ホスト上の kong.yaml を read‑only でマウント - ./kong.yaml:/usr/local/kong/declarative/kong.yaml:ro healthcheck: # バージョンに合わせてエンドポイントを選択 test: ["CMD", "curl", "-f", "http://localhost:8001/v2/status"] interval: 30s timeout: 10s retries: 3 |
起動手順と確認
|
1 2 3 4 |
docker compose up -d # バックグラウンドで起動 docker logs -f kong-db-less # ログをリアルタイム監視 curl http://localhost:8001/v2/status # 「Kong is ready」 が返れば成功 |
ポイント：DB‑less は外部 DB を持たないため、リソース制限や read‑only コンテナと相性が良く、本番環境での軽量運用に適しています。
4. PostgreSQL バックエンド（永続化）モード
大規模・長期運用では設定・プラグイン情報を永続化できる PostgreSQL が推奨されます。Compose 内で DB コンテナと Kong を同時に起動し、depends_on とヘルスチェックで起動順序を保証します。
4.1 PostgreSQL のシークレット管理
記事中の平文パスワードは 実運用では絶対に使用しない ことが前提です。Docker Compose が提供する secrets 機能、あるいは外部シークレットストア（HashiCorp Vault, AWS Secrets Manager 等）と組み合わせて安全に供給しましょう。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# docker-compose.yml の例 (Docker secrets を使用) services: postgres: image: postgres:15-alpine container_name: kong-pg restart: unless-stopped environment: POSTGRES_USER: kong POSTGRES_DB: kong secrets: - pg_password # シークレット名を指定 volumes: - pg-data:/var/lib/postgresql/data healthcheck: test: ["CMD", "pg_isready", "-U", "kong"] interval: 30s timeout: 10s retries: 5 secrets: pg_password: file: ./secrets/pg_password.txt # ファイルはホスト側で適切に権限管理 |
4.2 docker‑compose.yml（PostgreSQL）
|
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 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
version: "3.9" services: postgres: image: postgres:15-alpine container_name: kong-pg restart: unless-stopped environment: POSTGRES_USER: kong POSTGRES_DB: kong secrets: - pg_password volumes: - pg-data:/var/lib/postgresql/data healthcheck: test: ["CMD", "pg_isready", "-U", "kong"] interval: 30s timeout: 10s retries: 5 kong: image: kong:3.4.0 container_name: kong-pg-mode restart: unless-stopped depends_on: postgres: condition: service_healthy environment: KONG_DATABASE: postgres KONG_PG_HOST: postgres # Docker ネットワーク上のサービス名 KONG_PG_USER: kong KONG_PG_PASSWORD_FILE: /run/secrets/pg_password # ファイル経由で取得 KONG_PG_DATABASE: kong KONG_DECLARATIVE_CONFIG: /usr/local/kong/declarative/kong.yaml ports: - "8000:8000" - "8443:8443" - "8001:8001" volumes: - ./kong.yaml:/usr/local/kong/declarative/kong.yaml:ro healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8001/v2/status"] interval: 30s timeout: 10s retries: 3 volumes: pg-data: secrets: pg_password: file: ./secrets/pg_password.txt |
起動手順
|
1 2 3 4 |
docker compose up -d # DB と Kong が同時に起動 docker logs -f kong-pg-mode # Kong の起動ログを確認 curl http://localhost:8001/v2/status # 正常応答で完了 |
ポイント：
depends_on+healthcheckにより、PostgreSQL が正常に起動・待機した後に Kong が接続を試みるため、接続失敗による再起動ループを防げます。
5. プラグイン有効化と read‑only コンテナ
Kong の拡張性はプラグインにありますが、デフォルトイメージには bundled（標準搭載）プラグインしか組み込まれていません。追加のサードパーティ・カスタムプラグインを利用する場合は KONG_PLUGINS 環境変数でロード対象を明示します。
5.1 KONG_PLUGINS の役割と例
| 設定例 | 説明 |
|---|---|
KONG_PLUGINS=bundled |
デフォルトの標準プラグインのみ使用（推奨） |
KONG_PLUGINS=bundled,rate-limiting,jwt |
標準に加えて rate‑limiting と jwt を有効化 |
KONG_PLUGINS=custom,my-plugin |
カスタムプラグイン（ローカルビルドイメージ）をロード |
注意：カスタムプラグインはビルド時に Kong のベースイメージへ組み込む必要があります。Dockerfile で
luarocks install <plugin>等の手順を追加してください。
5.2 Declarative Config におけるプラグイン定義
kong.yaml（Declarative Config）にプラグイン情報を書くだけで自動的にロードされます。以下は代表的な設定例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
_format_version: "2.1" services: - name: example-service url: http://example.org routes: - name: example-route paths: - /api plugins: - name: rate-limiting config: minute: 100 policy: local - name: jwt config: uri_param_names: - token claims_to_verify: - exp |
プラグイン変更時のリロード方法
kong.yamlを編集- コンテナ内部で Admin API の
/admin/v1/configにPOSTするか、コンテナを再起動
bash
docker exec kong curl -X POST http://localhost:8001/admin/v1/config
5.3 read‑only コンテナの設定
本番環境では read‑only にしてファイルシステム改ざんリスクを低減します。書き込みが必要なディレクトリは tmpfs またはボリュームで例外化します。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
services: kong: image: kong:3.4.0 read_only: true # コンテナ全体を読み取り専用に tmpfs: - /tmp - /var/run/kong # PID・ソケット等が書き込まれる場所 environment: KONG_PLUGINS: bundled,rate-limiting,jwt # 必要プラグインを列挙 volumes: - ./kong.yaml:/usr/local/kong/declarative/kong.yaml:ro |
ポイント：
read_only: trueにすると/usr/local/kong/への書き込みが禁止されます。Kong が起動時に必要とする一時領域はtmpfs（上記例）で確保してください。
6. 本番環境ベストプラクティスとトラブルシューティング
6.1 ヘルスチェック・リソース制限の正しい扱い
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
services: kong: # 省略... healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8001/v2/status"] interval: 15s timeout: 5s retries: 4 deploy: resources: limits: cpus: '2.0' # 最大 2 CPU コア（Swarm / K8s のみ有効） memory: 1G # 最大 1 GiB メモリ（Swarm / K8s のみ有効） reservations: cpus: '0.5' memory: 256M restart: unless-stopped |
- 注意点：
deploy.resourcesは Docker Swarm や Kubernetes にデプロイした場合にのみ有効です。単体のdocker compose環境では CPU・メモリ制限は適用されません。そのため、ローカルテスト時は OS の cgroup 設定や外部ツールで制御してください。
6.2 TLS 終端とネットワーク分離
- TLS：証明書と鍵を
certs/ディレクトリに置き、環境変数でパスを渡す。
yaml
environment:
KONG_SSL_CERT: /etc/kong/certs/tls.crt
KONG_SSL_CERT_KEY: /etc/kong/certs/tls.key
volumes:- ./certs:/etc/kong/certs:ro
- ./certs:/etc/kong/certs:ro
- ネットワーク分離：本番は
bridgeではなく Overlay（Swarm）や Calico 等の CNI を使用し、API ゲートウェイと DB の通信だけを許可します。
6.3 よくあるエラーと対処法
| エラー | 原因例 | 確認手順 | 推奨解決策 |
|---|---|---|---|
ポート競合 (Error starting userland proxy: listen tcp 0.0.0.0:8000) |
同一ホストで別プロセスが 8000/8443 を使用中 | lsof -i :8000、docker ps のポートマッピング確認 |
該当サービスを停止、または Compose 側のポート番号を変更 |
DB 接続失敗 (could not connect to PostgreSQL) |
環境変数ミスマッチ、DB 起動遅延、シークレット未提供 | docker logs kong-pg-mode、docker exec -it postgres pg_isready -U kong |
depends_on とヘルスチェックを正しく設定し、パスワードは secrets で供給 |
プラグインロード失敗 (failed to load plugin 'rate-limiting') |
KONG_PLUGINS に未列挙、プラグインがイメージに組み込まれていない |
docker exec kong curl http://localhost:8001/plugins で一覧確認 |
KONG_PLUGINS=bundled,rate-limiting を環境変数へ追加、またはカスタムイメージを再ビルド |
read‑only エラー (cannot write to '/usr/local/kong') |
必要な書き込みディレクトリが read_only: true のまま例外化されていない |
起動ログでパスを確認 → /tmp, /var/run/kong がマウントされているか |
tmpfs で対象ディレクトリを追加、またはボリュームで例外化 |
ポイント：エラーが出たらまず コンテナログ と
docker compose ps --services --filter "status=running"の状態を確認し、上表の対処法を順に試すと迅速に復旧できます。
7. 完全版 docker‑compose.yml ダウンロード
以下のファイルは本ガイドで紹介した DB‑less + read‑only + TLS + プラグイン の構成例です。ローカル環境で docker compose up -d すれば、すぐに Kong Gateway が起動します。
|
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 37 |
# docker-compose.yml (最終版) version: "3.9" services: kong: image: kong:3.4.0 container_name: kong-prod restart: unless-stopped read_only: true tmpfs: - /tmp - /var/run/kong environment: KONG_DATABASE: off KONG_DECLARATIVE_CONFIG: /usr/local/kong/declarative/kong.yaml KONG_PROXY_ACCESS_LOG: /dev/stdout KONG_ADMIN_ACCESS_LOG: /dev/stdout KONG_PROXY_ERROR_LOG: /dev/stderr KONG_ADMIN_ERROR_LOG: /dev/stderr KONG_PLUGINS: bundled,rate-limiting,jwt # 必要プラグインを列挙 KONG_SSL_CERT: /etc/kong/certs/tls.crt KONG_SSL_CERT_KEY: /etc/kong/certs/tls.key ports: - "8000:8000" - "8443:8443" - "8001:8001" volumes: - ./kong.yaml:/usr/local/kong/declarative/kong.yaml:ro - ./certs:/etc/kong/certs:ro healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8001/v2/status"] interval: 15s timeout: 5s retries: 4 # 必要に応じて PostgreSQL バックエンドや Swarm/K8s 用の deploy 設定を別ファイルで管理してください。 |
最終的なチェックリスト
- [ ] Docker Engine & Compose が推奨バージョンか確認
- [ ]KONG_DECLARATIVE_CONFIGのパスがコンテナ内に正しく存在することを検証
- [ ] ヘルスチェック URL（/v2/status など）が使用中の Kong バージョンで有効か確認
- [ ] 本番では DB パスワード等機密情報を Docker secrets または外部シークレットストアで供給
- [ ]KONG_PLUGINSに必要なプラグインをすべて列挙し、カスタムプラグインはイメージに組み込む
以上で、安全・安定・拡張性の高い Kong Gateway の本番デプロイ が完了します。ぜひこの構成をベースに、各自の要件に合わせたチューニングを行ってください。