Contents
KrakenD 公式イメージとタグ選択のポイント
Docker Hub に公開されている krakend/krakend イメージは、開発・テストから本番運用まで幅広く利用できます。ここでは latest タグとバージョン固定タグ（例：v2.1.0）の特性を比較し、実務で安全に使うための選定基準を示します。結論としては、再現性が必要な場面では固定版、手軽さを優先するローカル実験やデモでは latest が適しています。
latest と固定版の違い
latest タグは「リポジトリにプッシュされた最新ビルド」を指し、毎回イメージが上書きされます。一方、固定版タグは特定のリリースにロックされ、同一ハッシュのイメージが永続的に提供されます。
| 項目 | latest | 固定版（例：v2.1.0） |
|---|---|---|
| 更新頻度 | Docker Hub の新ビルドごとに変化 | リリース時点で固定 |
| CI/CD 再現性 | ビルド日時によって結果が変わる可能性あり | ハッシュが一定なので再現性が高い |
| デバッグ情報 | 最新のログや機能が含まれる | ドキュメントとコードベースが一致 |
| 利用シーン | ローカルで素早く試す、デモ環境 | 本番・ステージング・CI パイプライン |
タグ選定の実務的な基準
- 安定性を最優先 → 固定版タグ（例：
krakend/krakend:2.1.0）を使用し、イメージハッシュでロックする。 - 機能評価やサンプル実装 →
latestを利用して最新の改善点をすぐに試す。 - 長期運用・LTS が必要 → KrakenD のリリースノート（公式 GitHub）で LTS と明示されたバージョンを固定版として選択する。
- 脆弱性スキャン → 固定版は過去のイメージが残るため、スキャン結果が一貫しやすい。
ポイント：公式ドキュメントと GitHub のリリースページを併せて確認し、タグ選択時に「最新かつ安定」かを判断しましょう。
ローカル開発用設定ディレクトリと krakend.json の作成手順
KrakenD の設定ファイルはコードベースから分離して管理すると、チーム全体で同一の構成を保てます。ここでは VS Code の Dev Container と相性の良いディレクトリ配置例と、最小限の krakend.json サンプルを示します。
ディレクトリ構造のベストプラクティス
プロジェクトルートに .devcontainer/krakend/ を作成し、その中に設定ファイルと補足ドキュメントを置くことで、コンテナ起動時のボリュームマウントがシンプルになります。
|
1 2 3 4 5 6 7 8 9 |
my-project/ ├─ .devcontainer/ │ └─ krakend/ │ ├─ krakend.json # 本番・開発共通設定 │ ├─ krakend.dev.json # 開発向けオーバーライド（任意） │ └─ README.md # 設定ファイルの概要と変更履歴 ├─ src/ └─ docker-compose.yml |
.devcontainerは Docker‑Compose ベースの開発環境で自動的に認識され、VS Code がRemote - Containers拡張から利用できる。- 設定ファイルは バージョン管理下に置く ことで、プルリクエストごとに変更差分が追跡可能になる。
最小構成サンプルと重要ポイント
以下は「/status」エンドポイントだけを提供する最小構成です。開発時には extra_config.dev を使ってデバッグ情報を増やすことができます。
|
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 |
{ "version": 3, "timeout": "3000ms", "output_encoding": "json", "endpoints": [ { "endpoint": "/status", "method": "GET", "extra_config": { "dev": { "debug_endpoint": true } }, "backend": [ { "url_pattern": "/health", "host": ["http://example-backend:8080"] } ] } ], "extra_config": { "github.com/devopsfaith/krakend-healthcheck": { "endpoint": "/__health" } } } |
versionは KrakenD の設定スキーマバージョンで、現在は 3 が推奨。extra_config.github.com/...は公式プラグイン名（正しくはgithub.com/devopsfaith/krakend-healthcheck）で、ヘルスチェックエンドポイントを自動生成する。- 開発モード (
KRAKEN_ENV=development) ではdebug_endpointが有効になり、リクエストログが詳細に出力されます。
ポイント：本番環境向けには
extra_config.devを削除し、必要最小限の設定だけを残すことでパフォーマンスとセキュリティを確保します。
Docker コマンドと docker‑compose でのコンテナ起動・設定マウント
公式イメージはシンプルなフラグで起動できますが、ローカル開発向けにボリュームや環境変数を適切に指定することが重要です。ここでは docker run と docker-compose.yml の両方の記述例と、その意味合いを解説します。
docker run の典型例
以下コマンドは 設定ディレクトリを読み取り専用でマウントし、デバッグモードで起動する例です。イメージタグは固定版に差し替えるだけで CI と同様の再現性が得られます。
|
1 2 3 4 5 6 7 |
docker run -d --name krakend \ -p 8080:8080 \ -v "$(pwd)/.devcontainer/krakend:/etc/krakend:ro" \ -e KRAKEN_ENV=development \ krakend/krakend:latest \ -c /etc/krakend/krakend.json -d |
-d（デタッチ）と-pは必須の基本オプション。-v …:roによりコンテナから設定ファイルを書き換えることを防止。-e KRAKEN_ENV=developmentで内部ロギングが詳細化し、開発者向けデバッグ情報が出力されます。- 最後の
-c … -dは KrakenD 本体へのオプションで、設定ファイルパスとデバッグモードを指定しています。
docker‑compose.yml の記述例
Compose ファイルに同等の設定を書けば、チーム全員が ワンコマンド で環境を立ち上げられます。healthcheck セクションでは start_period を明示的に説明します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
version: "3.9" services: krakend: image: krakend/krakend:latest # CI 用には固定版へ置き換える container_name: krakend ports: - "8080:8080" volumes: - ./.devcontainer/krakend:/etc/krakend:ro environment: KRAKEN_ENV: development command: ["-c", "/etc/krakend/krakend.json", "-d"] healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/__health"] interval: 30s # 健康チェックの実行間隔 timeout: 5s # 応答が無い場合のタイムアウト retries: 3 # 判定を「unhealthy」にするまでの再試行回数 start_period: 10s # コンテナ起動直後の緩衝期間。初期化やネットワーク待ちで失敗しないようにする restart: unless-stopped # 開発中の意図しない停止を防止 |
start_periodは コンテナが起動してから最初のヘルスチェックまで待機させる時間です。アプリが内部的にキャッシュや外部サービスへの接続を行う場合、早すぎるチェックで誤判定（unhealthy）になるリスクを低減します。restart: unless-stoppedにより手動で停止しない限り自動再起動が保証されます。
ヘルスチェックとエンドポイント検証
運用中のサービスが正常に応答しているかは、Docker の HEALTHCHECK ディレクティブ と KrakenD が提供する /__health エンドポイント で確認できます。ここでは設定例と手動・自動テスト手順を示します。
Docker HEALTHCHECK の設定と意味
以下は先ほどの Compose ファイルに組み込んだ healthcheck セクションです。各項目の役割を解説します。
|
1 2 3 4 5 6 7 |
healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8080/__health"] interval: 30s # 30 秒ごとに実行 timeout: 5s # 応答が無い場合は失敗扱い retries: 3 # 連続失敗回数が 3 回になるとコンテナを unhealthy と判定 start_period: 10s # 起動直後の緩衝期間。サービスが完全に立ち上がるまでチェックをスキップ |
curl -fは HTTP ステータスコードが 2xx 系でないとエラー とみなすオプションです。start_periodを設定しない場合、コンテナ開始直後にヘルスチェックが走り、まだリスニングできていなくてもunhealthy判定になることがあります。
ポイント：CI でヘルス状態を取得する際は
docker inspect --format='{{.State.Health.Status}}' <コンテナ名>を使用し、healthyが返ってきたら次のステップへ進めます。
手動・自動テストの実行方法
手動検証（ローカル端末）
|
1 2 3 4 5 6 |
# 1. /status エンドポイントの内容を確認 curl -s http://localhost:8080/status | jq . # 2. ヘルスチェックエンドポイントが期待通りか確認 curl -f http://localhost:8080/__health && echo "HEALTH OK" |
jqがインストールされていれば JSON を整形して見やすくなります。curl -fが成功した場合はステータスコード 2xx、失敗すると非 0 終了コードになるためシェルスクリプトで判定しやすいです。
CI（GitHub Actions）での自動テスト例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
- name: Wait for KrakenD health run: | for i in {1..12}; do # 最大 60 秒待機 STATUS=$(docker inspect --format='{{.State.Health.Status}}' krakend) if [ "$STATUS" = "healthy" ]; then exit 0; fi echo "Waiting... ($i)" sleep 5 done echo "KrakenD did not become healthy" exit 1 - name: Verify /status endpoint run: | curl -f http://localhost:8080/status | jq . |
docker inspectのポーリングでhealthyになるまで待機し、タイムアウトしたらジョブを失敗させます。- エンドポイント検証は
curl -fにより 2xx が返らなければ自動的にエラーとなります。
設定変更時の再起動フローと CI/CD への組み込み
設定ファイルを更新した際にはコンテナ内部で即座に反映させる手順が必要です。ここでは docker-compose の restart と、GitHub Actions を使った自動化パイプラインの具体例を示します。
docker‑compose restart の流れ
- 設定変更
.devcontainer/krakend/krakend.jsonに新しいエンドポイントやバックエンド URL を追記。- 再起動コマンド実行
bash
docker compose restart krakend
- ボリュームはそのままでプロセスだけが再起動するため、変更が即座に反映されます。
- ヘルスチェックで稼働確認
bash
docker inspect --format='{{.State.Health.Status}}' krakend
healthyが返ってきたら次のテストフェーズへ進めます。
ポイント：イメージ自体を再ビルドする必要がないので、開発サイクルが数秒単位で完結します。
GitHub Actions による自動テストパイプライン例
以下ワークフローは push 時に KrakenD の設定変更があれば自動でコンテナを起動し、ヘルスチェックとエンドポイントの検証まで行います。イメージタグは 固定版（例：krakend/krakend:2.1.0）を使用して再現性を担保しています。
|
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 |
name: KrakenD CI on: push: paths: - '.devcontainer/krakend/**' - 'docker-compose.yml' jobs: test: runs-on: ubuntu-latest steps: # ソース取得 - uses: actions/checkout@v3 # Docker Compose 起動（固定版イメージ） - name: Start KrakenD run: | docker compose up -d krakend # コンテナが healthy になるまで最大 60 秒待機 for i in {1..12}; do STATUS=$(docker inspect --format='{{.State.Health.Status}}' krakend) if [ "$STATUS" = "healthy" ]; then break; fi echo "Waiting for health... ($i)" sleep 5 done if [ "$STATUS" != "healthy" ]; then echo "::error::KrakenD failed health check" exit 1 fi # エンドポイント検証（curl + jq） - name: Verify /status endpoint run: | curl -f http://localhost:8080/status | jq . # 後片付け - name: Teardown if: always() run: docker compose down |
- イメージ固定により、CI が毎回同じバイナリと設定で実行されることが保証されます。
docker inspectのポーリングはstart_periodと併せて考慮し、起動直後の誤判定を防ぎます。- テスト失敗時は自動的にプルリクエストがブロックされるので、品質の高い設定のみがマージされます。
ポイント：本番デプロイ前に同様のワークフロー（ステージング環境へのデプロイ）を組み込むと、運用リスクを最小化できます。
まとめ
| 項目 | 推奨設定・手順 |
|---|---|
| イメージタグ | 開発実験は latest、CI/本番は固定版（例：krakend/krakend:2.1.0） |
| 設定ディレクトリ | .devcontainer/krakend/ に配置し、Docker ボリュームで読み取り専用マウント |
| 起動コマンド | docker run … -c /etc/krakend/krakend.json -d または同等の docker-compose.yml 設定 |
| ヘルスチェック | /__health エンドポイント＋ HEALTHCHECK（start_period で起動遅延を緩和） |
| 変更反映 | docker compose restart krakend → ヘルス確認 → 手動/自動テスト |
| CI/CD 自動化 | GitHub Actions で固定版イメージ、ヘルスチェックポーリング、エンドポイント検証を実装 |
上記のベストプラクティスに従えば、Docker 環境下で KrakenD を安全かつ高速に試すことができ、設定変更やバージョンアップ時にも信頼性の高い CI/CD パイプラインを構築できます。ぜひ自プロジェクトに取り入れ、継続的な API ゲートウェイ運用の品質向上に役立ててください。