Contents
前提条件と環境設定
このセクションでは、Kong OSS を Docker 上で安全に動作させるための最低限のソフトウェア要件とネットワーク構成を確認します。前提が揃っていないとコンテナ起動時にエラーやポート競合が頻発し、トラブルシューティングに余計な工数がかかります。ここで示す項目は Docker Engine ≥ 20.10 と Compose v2 系 を前提とした構成です。
Docker Engine のバージョン要件 (≥20.10)
Docker Engine が古いとブリッジネットワークやボリュームの機能が制限され、Kong の公式イメージが期待通りに動作しません。
- 推奨: 20.10 以上（実際には最新の安定版を使用）
- 確認方法:
|
1 2 |
docker version --format '{{.Server.Version}}' |
バージョン文字列が 20.10 以降であれば要件は満たしています。もし古い場合は公式インストールガイド（https://docs.docker.com/engine/install/）に従ってアップデートしてください。
docker‑compose (v2 系) のインストール方法
Compose は Docker CLI のプラグインとして提供される v2 系を使用します。プラグイン方式は単一バイナリで管理でき、docker compose コマンドがそのまま利用可能です。
- インストール手順（Linux/macOS 共通）:
|
1 2 3 4 5 6 7 8 9 |
DOCKER_CONFIG=${HOME}/.docker mkdir -p $DOCKER_CONFIG/cli-plugins curl -SL https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-linux-x86_64 \ -o $DOCKER_CONFIG/cli-plugins/docker-compose chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose # バージョン確認 docker compose version # => Docker Compose v2.27.0 |
インストールが完了したら、以降は docker compose up 形式でスタックを起動できます。
推奨 OS とポート設定
Kong のデフォルトリスニングポートは 8000 (HTTP)、8443 (HTTPS)、そして管理用の 8001 (HTTP) / 8444 (HTTPS) です。これらのポートが外部から到達可能であることを確認してください。
- 推奨 OS: Ubuntu 22.04 LTS、Debian 12、または macOS の最新リリース（いずれも Docker Desktop / Engine が公式にサポートされています）。
- ファイアウォール例 (Ubuntu ufw):
|
1 2 3 4 5 6 |
sudo ufw allow 8000/tcp # Proxy HTTP sudo ufw allow 8443/tcp # Proxy HTTPS sudo ufw allow 8001/tcp # Admin API (HTTP) sudo ufw allow 8444/tcp # Admin API (HTTPS, 任意) sudo ufw reload |
ポート 8002 はデフォルトでは使用しないため、本稿の構成では記載せず、必要に応じて別途追加してください。
公式イメージ取得と Docker ネットワーク構築
この章では Kong の公式 Docker イメージを取得し、サービス間通信を安定させるカスタムブリッジネットワーク kong-net を作成する手順を示します。公式イメージは常に最新の安定版（Kong 3.x 系）を提供しているため、タグ名だけでバージョン管理が可能です。
stable タグの取得とバージョン確認
kong:stable は Kong の長期サポート（LTS）向けイメージであり、毎月セキュリティパッチが適用されます。
- 取得コマンド:
|
1 2 |
docker pull kong:stable |
- 内部バージョンの確認方法（実行時に
kong versionを呼び出す）:
|
1 2 3 |
docker run --rm kong:stable kong version # 例: Kong 3.4.0 (compatible; PostgreSQL, DB-less) |
この方式なら、イメージのタグは固定で CI/CD パイプラインにロックでき、実際のバージョン番号はコンテナ内部で確認できます。
カスタムネットワーク kong-net の作成
Compose が自動生成するブリッジネットワークでも動作しますが、明示的に名前を付けることで他プロジェクトとの衝突を防ぎ、docker network inspect による可視化が容易になります。
- 作成手順:
|
1 2 3 |
docker network create kong-net docker network ls | grep kong-net # 作成確認 |
Compose ファイル内では次のように参照します。
|
1 2 3 4 |
networks: kong-net: external: true |
この設定により、Kong とデータベースが同一ネットワーク上で名前解決できるようになります。
PostgreSQL と Kong の DB 使用モード
本セクションでは、永続化データベースとして PostgreSQL を利用する標準的な構成を紹介します。DB 連携モードはスケールアウトや統計情報の保持が必要な本番環境で推奨されます。
PostgreSQL コンテナ設定
PostgreSQL の公式イメージは POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB の 3 つだけを設定すれば初期化が完了します。
- docker‑compose.yml（抜粋）:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
services: kong-database: image: postgres:15-alpine environment: POSTGRES_USER: kong POSTGRES_PASSWORD: kong_secret POSTGRES_DB: kong volumes: - pgdata:/var/lib/postgresql/data networks: - kong-net healthcheck: test: ["CMD-SHELL", "pg_isready -U kong"] interval: 10s timeout: 5s retries: 5 |
healthcheck を追加することで、Kong コンテナが DB の起動完了を待機できるようになります。
Kong コンテナ設定（DB 連携）
Kong 側ではデータベース接続情報とリスニングポートを環境変数で明示します。KONG_ADMIN_GUI_AUTH は Admin GUI に Basic 認証を付与するオプションですが、必須ではない点に留意してください（公式ドキュメント参照: https://docs.konghq.com/gateway/latest/admin-api/#authentication）。
- docker‑compose.yml（続き）:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
kong: image: kong:stable depends_on: kong-database: condition: service_healthy environment: KONG_DATABASE: postgres KONG_PG_HOST: kong-database KONG_PG_USER: kong KONG_PG_PASSWORD: kong_secret KONG_PG_DATABASE: kong # Admin API は HTTP と HTTPS の両方で待ち受ける例 KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl ports: - "8000:8000" # Proxy HTTP - "8443:8443" # Proxy HTTPS - "8001:8001" # Admin API (HTTP) - "8444:8444" # Admin API (HTTPS, 任意) networks: - kong-net |
depends_on に condition: service_healthy を入れることで、PostgreSQL が起動していることが確認できるまで Kong の起動を遅延させます。
マイグレーション手順とヘルスチェック
DB スキーマはコンテナ初回起動時に手動でマイグレーションする必要があります。以下のコマンドは docker compose up -d 後に実行します。
- マイグレーション:
|
1 2 3 4 5 6 |
# 初回（テーブル作成等） docker exec -it $(docker ps -qf "name=kong") kong migrations bootstrap # 以降のバージョンアップ時 docker exec -it $(docker ps -qf "name=kong") kong migrations up |
マイグレーションが成功するとコンテナログに Migrations successful が出力されます。続いて Admin API のヘルスチェックを行い、Kong が正常に起動したことを確認します。
|
1 2 3 |
curl -i http://localhost:8001/ # HTTP/1.1 200 OK が返れば成功 |
DB-less モードでのデプロイ
DB-less（宣言的）モードは永続化データベースが不要な軽量構成です。設定は YAML ファイルにすべて記述し、起動時にマウントするだけで完結します。
declarative config (kong.yml) の作成例
kong.yml は Kong 3.x 系の Declarative Config スキーマに準拠した YAML です。最小構成として Service と Route を定義します。
- ファイル例（プロジェクトルートに配置）:
|
1 2 3 4 5 6 7 8 9 10 |
_format_version: "3.0" services: - name: httpbin-service url: https://httpbin.org routes: - name: httpbin-route paths: - /httpbin methods: ["GET", "POST"] |
このファイルをマウントすれば、Kong 起動時に自動的に Service と Route がロードされます。
Compose 定義でのボリュームマウントと環境変数
DB-less モードを有効化するには KONG_DATABASE=off と KONG_DECLARATIVE_CONFIG を設定します。TLS 終端や Admin API の認証は別途オプションで付与できます。
- docker‑compose.yml（DB-less 用）:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
services: kong-db-less: image: kong:stable environment: KONG_DATABASE: off # DB-less モード有効化 KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml KONG_ADMIN_LISTEN: 0.0.0.0:8001, 0.0.0.0:8444 ssl ports: - "8000:8000" - "8443:8443" - "8001:8001" - "8444:8444" volumes: - ./kong.yml:/etc/kong/kong.yml:ro networks: - kong-net |
-ro オプションで読み取り専用マウントにし、誤ってコンテナ内部から書き換えられないようにしています。
単体 docker run での起動例
開発環境や CI のステップだけを手早く検証したい場合は、Compose を使わずに docker run コマンドでも同等の構成が作れます。
- 実行コマンド:
|
1 2 3 4 5 6 7 8 9 |
docker run -d --name kong-db-less \ --network=kong-net \ -p 8000:8000 -p 8443:8443 -p 8001:8001 -p 8444:8444 \ -v $(pwd)/kong.yml:/etc/kong/kong.yml:ro \ -e KONG_DATABASE=off \ -e KONG_DECLARATIVE_CONFIG=/etc/kong/kong.yml \ -e KONG_ADMIN_LISTEN="0.0.0.0:8001, 0.0.0.0:8444 ssl" \ kong:stable |
起動後に curl http://localhost:8001/services とアクセスすれば、先ほど定義した Service が JSON で返ることが確認できます。
運用・トラブルシューティングとベストプラクティス
本章では実運用で直面しやすい課題を整理し、永続化・バックアップ・セキュリティの観点から安全に運用するための指針を示します。
永続化ボリュームとバックアップ戦略
PostgreSQL のデータは名前付きボリューム pgdata に格納し、Kong のプラグインやカスタム証明書は別途永続化ボリューム kong-data として管理します。定期的なスナップショット取得と外部ストレージへの転送が障害復旧の鍵です。
- docker‑compose.yml（volumes 定義）:
|
1 2 3 4 5 6 |
volumes: pgdata: driver: local kong-data: driver: local |
- バックアップ例（PostgreSQL ダンプ）:
|
1 2 3 4 5 6 7 8 |
# コンテナ内部でダンプを作成 docker exec -t $(docker ps -qf "name=kong-database") \ pg_dump -U kong -F c -b -v -f /tmp/kong_backup.dump kong # ホスト側にコピーして外部保存（例: S3、NAS） docker cp $(docker ps -qf "name=kong-database"): /tmp/kong_backup.dump ./backup/ # 以降 rsync/awslocal s3 sync 等で転送 |
Kong 自体の設定ファイルは kong.yml（DB-less）やデータベーススキーマが永続化対象になるため、バックアップ対象に含めることを忘れないでください。
よくあるエラーと対処法
| エラーシナリオ | 主な原因 | 確認ポイント | 推奨対策 |
|---|---|---|---|
address already in use（ポート 8000） |
ホスト上で同ポートが既に使用中 | lsof -i :8000 または netstat -tulpn |
競合サービスを停止、または Compose の ports マッピングを別ポートに変更 |
環境変数のスペルミス（例: KONG_DATABSE） |
キー名が誤っている | docker compose config で展開結果を確認 |
正しいキー名 KONG_DATABASE に修正し、再デプロイ |
マイグレーション失敗：role "kong" does not exist |
PostgreSQL が起動前に Kong がマイグレートを試行 | コンテナログの healthcheck 状態 |
depends_on の condition: service_healthy を設定し、DB 起動完了を待機 |
| DB-less モードで Service がロードされない | KONG_DECLARATIVE_CONFIG パスが不正 |
docker exec <kong> ls /etc/kong/ でファイル有無確認 |
マウントパスと環境変数の一致を再チェック |
エラーメッセージは必ずコンテナログ（docker logs <container>）で取得し、上表の項目に当てはめながら原因究明してください。
本番向けセキュリティベストプラクティス（Admin API 認証・TLS 終端）
Admin API の認証化
デフォルトでは Admin API が無認証で HTTP/HTTPS 両方に公開されます。実運用では Basic Auth か JWT による保護を必ず設定し、さらにファイアウォールで内部ネットワークからのみアクセスできるよう制限します。
- Compose への追加例（Basic Auth）:
|
1 2 3 4 5 |
environment: KONG_ADMIN_GUI_AUTH: basic-auth # Admin GUI に Basic 認証を適用 KONG_ADMIN_GUI_SESSION_CONF: '{"secret":"${ADMIN_GUI_SECRET}"}' KONG_ADMIN_LISTEN: 0.0.0.0:8001 ssl # HTTPS のみ公開（HTTP は省略可） |
KONG_ADMIN_GUI_AUTH は公式ドキュメントに記載されているオプションで、basic-auth を指定すると Authorization: Basic <base64> ヘッダーが必須になります。
TLS 終端の設定
外部からの通信はすべて TLS で保護し、証明書と鍵を安全にマウントします。
- 必要な環境変数:
|
1 2 3 4 5 6 |
environment: KONG_PROXY_LISTEN: 0.0.0.0:8000, 0.0.0.0:8443 ssl KONG_ADMIN_LISTEN: 0.0.0.0:8001 ssl KONG_PROXY_TLS_CERT: /etc/kong/ssl/proxy.crt KONG_PROXY_TLS_CERT_KEY: /etc/kong/ssl/proxy.key |
- ボリュームマウント例:
|
1 2 3 4 5 6 |
volumes: - ./certs/proxy.crt:/etc/kong/ssl/proxy.crt:ro - ./certs/proxy.key:/etc/kong/ssl/proxy.key:ro - ./certs/admin.crt:/etc/kong/ssl/admin.crt:ro - ./certs/admin.key:/etc/kong/ssl/admin.key:ro |
証明書は Let’s Encrypt など自動更新が可能なものを使用し、キー管理は Vault や AWS KMS と連携させるとさらに安全です。
ネットワーク制限
ufw やクラウドベンダーのセキュリティグループで Admin API のポート（8001/8444）を内部サブネットに限定し、インターネットから直接到達できないようにします。
まとめ
| 項目 | 主なポイント |
|---|---|
| 前提条件 | Docker Engine ≥ 20.10、Compose v2、ポート 8000/8443/8001(＋8444) の開放 |
| 公式イメージ取得 | docker pull kong:stable → コンテナ内部で kong version 確認 |
| カスタムネットワーク | kong-net を作成し、DB と Kong が同一ブリッジ上で通信 |
| DB 使用モード | PostgreSQL の環境変数設定、ヘルスチェック、マイグレーション実行、Admin API ヘルスチェック |
| DB-less モード | kong.yml に Service/Route を宣言、KONG_DATABASE=off とボリュームマウントで起動 |
| 運用ベストプラクティス | 永続化ボリュームとバックアップ、エラー対処表、Admin API の認証・TLS 終端、ネットワーク制限 |
上記手順に沿って構築すれば、Kong OSS を Docker Compose 1 ファイルで DB 連携モード と DB-less モード の両方を安全かつ再現性の高い形でデプロイできます。さらに、永続化・バックアップ・認証・TLS といった本番向け要件も網羅しているため、開発環境から本番環境への移行がスムーズに行えるでしょう。
参考リンク
- Kong Docker インストールガイド: https://docs.konghq.com/gateway/latest/install/docker/
- Kong Admin API 認証方式: https://docs.konghq.com/gateway/latest/admin-api/#authentication
- Docker Engine インストール手順: https://docs.docker.com/engine/install/
- Docker Compose プラグインの公式リリースページ: https://github.com/docker/compose/releases
これらの公式ドキュメントは随時更新されるため、実装前に最新情報を確認してください。