Contents
公式 Docker イメージとタグの選び方
KrakenD が提供する公式イメージ krakend/krakend は Docker Hub のリポジトリで管理されており、latest タグは常に最新ビルドを指します。実務環境では 再現性 と 予期せぬ破壊的変更の回避 が重要になるため、SemVer（例: 2.1.0）で明示したタグを利用することが推奨されます。
latest と特定バージョンの比較
| 項目 | latest タグ |
特定バージョンタグ |
|---|---|---|
| 安定性 | 新機能やパッチが自動的に反映されるが、突如変更が入るリスクあり | ビルド時点のコードに固定でき、本番環境で差分が出にくい |
| 更新頻度 | 公式 CI が毎日または数日に一度自動プッシュ（※Docker Hub のタグ一覧をご参照） | 必要なバージョンだけを選択し、アップデート計画を明示的に立てられる |
| 運用コスト | バージョン管理が不要で手軽だがテスト漏れリスク増大 | CI/CD パイプラインで固定でき、ロールバックも容易 |
結論：開発・検証環境では
latestが便利ですが、本番デプロイは必ず特定バージョンを指定してください。
イメージサイズと更新頻度の実情（出典付き）
公式イメージは主に以下の 2 種類が提供されています。サイズは執筆時点（2024 年 11 月）で測定した概算値です。リポジトリやベース OS のバージョン更新に伴い変動する可能性があるため、常に Docker Hub の 「Layers」 タブか docker manifest inspect コマンドで最新情報を確認してください。
| イメージ | ベース OS | 想定サイズ* |
|---|---|---|
krakend/krakend:2.1.0-alpine |
Alpine Linux 3.20 | 約 30 MB |
krakend/krakend:2.1.0-bullseye |
Debian Bullseye | 約 120 MB |
*サイズは compressed のレイヤー合計で、実行時に展開されると多少増加します。
注意：公式イメージのサイズや更新頻度はリポジトリ管理者が随時変更できるため、最新のタグ情報は Docker Hub（Tags ページ）で必ず確認してください。
ローカル設定ファイルの作成とコンテナへのボリュームマウント
KrakenD の挙動は 設定ファイル（JSON または YAML）一つ で決まります。本節ではローカルに設定ファイルを用意し、Docker コンテナへ安全にマウントする手順を解説します。
設定フォーマットの概要
以下は最小構成の JSON と YAML のサンプルです。どちらでも krakend check が成功すれば問題ありません。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
// config/krakend.json { "version": 2, "port": 8080, "endpoint": [ { "endpoint": "/hello", "method": "GET", "output_encoding": "json", "backend": [ { "url_pattern": "/api/hello", "host": ["http://mock-backend:9090"] } ] } ] } |
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# config/krakend.yml version: 2 port: 8080 endpoint: - endpoint: /hello method: GET output_encoding: json backend: - url_pattern: /api/hello host: - http://mock-backend:9090 |
ディレクトリ構成例
|
1 2 3 4 5 |
project-root/ ├─ config/ │ └─ krakend.json # または krakend.yml └─ docker-compose.yml |
config/ ディレクトリをそのままコンテナの /etc/krakend/ にマウントすることで、ローカルでファイルを編集すれば即座に反映できます。
Docker Run でのマウント手順
|
1 2 3 4 5 6 7 |
docker run -d \ --name krakend-gw \ -p 8080:8080 \ -e KRKEND_CONFIG=/etc/krakend/krakend.json \ -v "$(pwd)/config:/etc/krakend" \ krakend/krakend:2.1.0 |
-vオプションでローカルのconfigディレクトリをコンテナ内部にバインドマウント- 環境変数
KRKEND_CONFIGが設定ファイルへのパスを指示
ポイント：設定ファイル変更後はコンテナ再起動だけで新設定が有効になります。
Docker Run による基本起動とヘルスチェック
本節では最小構成で KrakenD を立ち上げ、Docker の HEALTHCHECK 機能を利用した稼働監視の実装方法を示します。ヘルスチェック用エンドポイントはバージョンによって変更されることがあるため、常に公式ドキュメント（Healthcheck セクション）で最新パスを確認してください。
ポート公開・環境変数設定例
|
1 2 3 4 5 6 7 8 |
docker run -d \ --name krakend-gw \ -p 8080:8080 \ # ホスト側 8080 → コンテナ側 8080 -e KRKEND_CONFIG=/etc/krakend/krakend.yml \ -v "$(pwd)/config:/etc/krakend" \ --restart unless-stopped \ # 本番推奨の再起動ポリシー krakend/krakend:2.1.0 |
--restart unless-stoppedにより、コンテナが異常終了した際に自動復旧します。- 必要に応じてホスト側ポートを変更（例：
-p 8081:8080）すれば競合回避できます。
ヘルスチェックの実装例
Dockerfile に直接書くか、docker run --health-cmd オプションで指定します。公式が推奨する krakend check を利用し、設定ファイルの妥当性を検証します。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
docker run -d \ --name krakend-gw \ -p 8080:8080 \ -e KRKEND_CONFIG=/etc/krakend/krakend.json \ -v "$(pwd)/config:/etc/krakend" \ --restart unless-stopped \ --health-cmd="krakend check -c /etc/krakend/krakend.json" \ --health-interval=30s \ --health-timeout=5s \ --health-retries=3 \ krakend/krakend:2.1.0 |
ヘルスチェックが失敗するとコンテナは unhealthy 状態となり、Swarm や Kubernetes の再起動ポリシーが自動でトリガーされます。
重要：エンドポイントパス（例
/__health）はバージョンごとに変わることがあります。最新情報は必ず公式ドキュメントで確認してください。
docker‑compose で本格的にデプロイする手順
複数サービスや永続ボリュームが必要になるケースでは docker‑compose が便利です。本節では、前述の設定ファイルとヘルスチェックを組み込んだ docker-compose.yml の最小構成を示します。
docker‑compose.yml の主要セクション
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
version: "3.9" services: krakend-gw: image: krakend/krakend:2.1.0 # 明示的にバージョン指定 container_name: krakend-gateway ports: - "8080:8080" environment: KRKEND_CONFIG: /etc/krakend/krakend.yml volumes: - ./config:/etc/krakend # 設定ファイルのマウント restart: unless-stopped healthcheck: test: ["CMD", "krakend", "check", "-c", "/etc/krakend/krakend.yml"] interval: 30s timeout: 5s retries: 3 networks: default: driver: bridge |
- services：本番環境ではバックエンドモックや DB コンテナを同一ファイルに追加可能です。
- volumes：ローカルの
config/ディレクトリが永続化され、編集即反映できます。 - healthcheck：
docker compose up後も自動でkrakend checkが走り、コンテナの状態を監視します。
起動・確認コマンド
|
1 2 3 4 5 |
docker compose up -d # バックグラウンド起動 docker compose ps # コンテナ一覧とヘルスステータス確認 docker compose exec krakend-gw krakend version # バージョン表示 docker compose exec krakend-gw krakend check -c /etc/krakend/krakend.yml |
ベストプラクティス：
docker compose configで最終的な設定を検証し、CI パイプラインでも同様にdocker-compose -f <file> config --quietを走らせることで構文ミスを防止します。
カスタムプラグイン・ミドルウェアの Dockerfile 拡張
KrakenD は Go 製プラグイン（.so）をロードでき、認証やロギングなど独自機能を追加できます。公式イメージに組み込む際は マルチステージビルド を用いて最終イメージのサイズを抑えることが推奨されます。
プラグインビルド用 Dockerfile の例
|
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 |
# ---------- Build stage ---------- FROM golang:1.22-alpine AS builder WORKDIR /src # Go モジュール取得 COPY go.mod go.sum ./ RUN go mod download # カスタムプラグインコードをコピー COPY ./plugin/ ./plugin/ # プラグインを共有ライブラリとしてビルド RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \ go build -buildmode=plugin -o /out/custom_auth.so ./plugin/auth/main.go # ---------- Runtime stage ---------- FROM krakend/krakend:2.1.0-alpine # 公式イメージの Alpine バリアント LABEL maintainer="yourname@example.com" # ビルド成果物をコピー COPY --from=builder /out/custom_auth.so /etc/krakend/plugins/ # プラグイン検索パスを環境変数で設定（任意） ENV KRKEND_PLUGIN_DIR=/etc/krakend/plugins ENTRYPOINT ["krakend"] CMD ["run", "-c", "/etc/krakend/krakend.json"] |
- マルチステージ により最終イメージは 30 MB 前後に抑えられます。
KRKEND_PLUGIN_DIRが設定されていれば、krakend run時に自動でプラグインがロードされます。
本番環境でのスケーリング戦略（概要）
| プラットフォーム | 推奨ポイント |
|---|---|
| Docker Swarm | docker service create --replicas 3 ... で水平スケール。内部 DNS と overlay network が自動ロードバランシングを提供。 |
| Kubernetes | Deployment + Service に加え、livenessProbe/readinessProbe に krakend check を設定し、Pod のヘルス判定を正確に行う。 |
| シークレット管理 | API キーや証明書は Kubernetes Secret / Swarm secret としてマウントし、イメージ内に平文を書かない。 |
注記：プラグインが
glibcに依存する場合は Alpine ではなく Debian 系ベース（krakend/krakend:2.1.0-bullseye）を選択してください。
デプロイ後の動作確認とトラブルシューティング
デプロイが完了したら、エンドポイントの挙動とログ出力を必ず確認し、想定通りにリクエストが転送されているか検証します。
エンドポイントテスト例（curl）
|
1 2 3 4 5 6 |
# 正常系：/hello が JSON を返すか確認 curl -s http://localhost:8080/hello | jq . # ヘルスチェック用エンドポイント（デフォルトは /__health、バージョンにより変更可） curl -I http://localhost:8080/__health |
200 OKとContent-Type: application/jsonが返れば稼働中です。jqが無い環境では生の出力を目視で確認してください。
よくあるエラーと対処法
| 質問 | 主な原因 | 推奨解決策 |
|---|---|---|
| ポート競合が起きる | ホスト側で 8080 が別プロセスに使用中 | docker run -p 8081:8080 に変更、または該当プロセスを停止 |
設定ファイルのパースエラー (krakend check が失敗) |
JSON/YAML の構文ミスや必須フィールド欠如 | python -m json.tool < file.json で整形確認、ローカルでも krakend check -c … を実行 |
| プラグインロード失敗 | .so が見つからない・ABI 不一致 |
Dockerfile の COPY --from=builder /out/*.so /etc/krakend/plugins/ パスを再確認、ldd で依存関係をチェック |
| コンテナが Unhealthy | ヘルスチェックコマンドが失敗 | docker logs <container> でエラーログ取得、設定パスや権限の誤りを修正 |
デバッグ手順：
docker inspect --format='{{json .State.Health}}' <container>でヘルスステータスと直近のログが確認できます。Kubernetes 環境ではkubectl describe pod <pod>とkubectl logs <pod>が同等です。
次のステップ
- 本ガイドに沿って サンプルリポジトリ（例：
github.com/yourorg/krakend-sample）をクローンし、ローカルで動作確認。 - CI/CD パイプラインに
docker compose build && docker compose up -dと ヘルスチェック を組み込み、PR ごとに自動テストを走らせる。 - 実運用環境では 特定バージョンタグ のロック、脆弱性スキャン（Trivy 等）、シークレット管理 を必ず実装し、セキュリティ基準に合致させる。
以上の手順をすべて実行したら、独自の KrakenD API ゲートウェイが本番レベルで稼働できるはずです。ぜひ体験レポートや改善点をご共有ください！