Contents
KrakenD 設定ファイルの基本構造
KrakenD の設定は 「メタ情報」＋「エンドポイント定義」＋「バックエンドマッピング」 の 3 層で成り立ちます。この章では、公式ドキュメント（2026 年5月版）に基づき、必須セクションとそれぞれの役割を具体例とともに解説します。設定ファイルの構造を正しく理解すれば、後続で紹介する認証やレートリミットなどの拡張機能もスムーズに組み込めます。
基本セクション
| セクション | 目的・概要 |
|---|---|
version |
設定ファイルフォーマットのバージョン。現在は 2 が推奨されています。 |
name |
ゲートウェイ全体を識別するラベル。ログやメトリクスに自動的に付与されます。 |
endpoints |
クライアントが呼び出す URL パスと HTTP メソッド、出力形式などを列挙します。 |
backend |
各エンドポイントが集約・変換するマイクロサービス側のエンドポイント情報です。 |
最小構成の YAML 例
|
1 2 3 4 5 6 7 8 9 10 11 |
version: 2 name: my-gateway endpoints: - endpoint: /status method: GET output_encoding: json backend: - url_pattern: /health host: - http://localhost:8080 |
上記のように backend はエンドポイントごとにネストして記述します。JSON でも同等に書ける点は公式ドキュメントで明記されています（2026 年5月版）。
YAML と JSON の選択基準（2026 年版）
本節では、可読性・運用コスト・ツールチェーンの親和性 という観点から、YAML と JSON のどちらを採用すべきか判断できる指標をまとめます。どちらの形式も krakend check コマンドで同様に検証可能です。
実務で使えるサンプル（認証＋レートリミット）
YAML
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
version: 2 name: auth-gateway endpoints: - endpoint: /api/v1/users method: GET output_encoding: json extra_config: auth/validator: algorithm: HS256 secret: ${JWT_SECRET} token_name: Authorization ratelimit/maxRate: 100 cache: ttl: "30s" backend: - url_pattern: /users host: - http://user-service:9090 |
JSON
|
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 |
{ "version": 2, "name": "auth-gateway", "endpoints": [ { "endpoint": "/api/v1/users", "method": "GET", "output_encoding": "json", "extra_config": { "auth/validator": { "algorithm": "HS256", "secret": "${JWT_SECRET}", "token_name": "Authorization" }, "ratelimit/maxRate": 100, "cache": { "ttl": "30s" } }, "backend": [ { "url_pattern": "/users", "host": [ "http://user-service:9090" ] } ] } ] } |
フォーマット選択のポイント
| 観点 | YAML の利点 | JSON の利点 |
|---|---|---|
| 可読性 | インデントで階層が一目瞭然。コメント記述も可能。 | キーと値が明示的でパースが高速。 |
| CI/CD での差分管理 | yq や git diff --color-words が扱いやすい。 |
多くの言語標準ライブラリが直接サポート。 |
| 環境変数埋め込み | ${VAR} の記法が自然にマッチ。 |
同様に文字列展開は可能だがエスケープに注意。 |
| 既存ツールチェーン | プロジェクト全体で YAML が統一されている場合推奨。 | 既存の JSON スキーマや OpenAPI と親和性が高い。 |
結論：チームが主に人間の可読性と設定変更頻度を重視するなら YAML、機械処理・スキーマ検証が中心であれば JSON が適しています。
KrakenDesigner Web エディタで設定ファイルを作成・エクスポート
KrakenDesigner は公式が提供するブラウザベースの GUI です。コードを書かずにドラッグ＆ドロップだけで完全な設定ファイルを生成でき、初心者から上級者まで幅広く活用できます。
手順概要
-
エディタへアクセス
公式サイト https://www.krakend.io/ のメニューから「Designer」ページに遷移します。2026 年4月リリースの UI がデフォルトで表示されます。 -
エンドポイントを追加
- 「Add Endpoint」をクリックし、パス
/api/v1/ordersと HTTP メソッドPOSTを入力。 -
「Backend」タブでバックエンド URL（例：
http://order-service:8080/create）と必要なマッピングルールを設定します。 -
拡張機能の組み込み
左側メニューの「Extra Config」から「Auth Validator」「Rate Limit」等を選択し、シークレットや上限値を入力すると自動的にextra_configフィールドへ反映されます。 -
設定ファイルのエクスポート
右上の「Export」をクリックし、形式として YAML（または JSON）を選択。「Download config.yaml」ボタンでローカルに保存できます。このファイルはそのまま Docker マウントや Kubernetes ConfigMap に利用可能です。
KrakenDesigner はリアルタイム構文チェックと UI ガイドが組み込まれているため、記述ミスを早期に検出できる点が大きなメリットです。
Docker / Docker‑Compose で設定ファイルをコンテナにマウントしてテスト
作成した設定ファイルをローカル環境で動作確認する最も手軽な方法は、公式イメージ krakend/krakend を利用してコンテナ上で起動することです。以下では 正しいフラグと環境変数の使い方 に焦点を当てます。
docker run の実行例
|
1 2 3 4 5 |
docker run --rm -p 8080:8080 \ -v "$(pwd)/config:/etc/krakend" \ krakend/krakend:latest \ run -c /etc/krakend/config.yaml -d |
-v "$(pwd)/config:/etc/krakend"… ローカルの./configディレクトリをコンテナ内部にマウント。run -c /etc/krakend/config.yaml… 設定ファイルのパスを直接指定（公式 CLI の推奨書式）。-dオプションは デバッグモード で、詳細なリクエスト・レスポンスログが標準出力に出ます。
起動後は http://localhost:8080/health や先ほど定義したエンドポイントへアクセスし、期待通りの挙動かを確認します。
docker‑compose.yml の記述例
|
1 2 3 4 5 6 7 8 9 10 |
version: "3.8" services: krakend: image: krakend/krakend:latest ports: - "8080:8080" volumes: - ./config:/etc/krakend command: ["run", "-c", "/etc/krakend/config.yaml", "-d"] |
volumesで設定ディレクトリをマウントし、command配列で公式 CLI のフラグ-cとデバッグモード-dを明示しています。- 公式 Docker ガイドでも同様に YAML を使用する場合は
-cフラグだけで十分です。環境変数でパスを渡す方式は非推奨ですので、ここでは採用していません。
この構成で docker compose up と実行すれば、数秒で API Gateway が立ち上がりローカルテストが完了します。
主要機能実装例・バリデーション・CI/CD への組み込み
認証・レートリミット・キャッシュ・環境変数置換の実装サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
version: 2 name: prod-gateway endpoints: - endpoint: /api/v1/payments method: POST output_encoding: json extra_config: auth/validator: algorithm: HS256 secret: ${PAYMENTS_JWT_SECRET} token_name: Authorization ratelimit/maxRate: 200 # 秒間 200 リクエスト上限 cache: ttl: "60s" # 応答を 1 分キャッシュ backend: - url_pattern: /pay host: - http://payment-service:${PAYMENT_PORT} |
- 環境変数置換は
${VAR}の形で記述し、Docker の-eオプションや Kubernetes の ConfigMap と組み合わせて実行時に展開されます。 - 認証が失敗した場合は自動的に 401 を返す安全設計です。
設定ファイルのローカルバリデーション手順
- 構文チェック
bash
docker run --rm -v "$(pwd)/config:/etc/krakend" \
krakend/krakend:latest check -c /etc/krakend/config.yaml
エラーが出なければ設定は正しくパース可能です。
- デバッグモードで起動
bash
docker run --rm -p 8080:8080 \
-v "$(pwd)/config:/etc/krakend" \
krakend/krakend:latest \
run -c /etc/krakend/config.yaml -d
標準出力にリクエスト・レスポンスの詳細が流れ、curl -X POST http://localhost:8080/api/v1/payments で即座に動作確認できます。
Kubernetes へのデプロイ例
ConfigMap に設定ファイルを格納
|
1 2 3 4 5 6 7 8 9 10 |
apiVersion: v1 kind: ConfigMap metadata: name: krakend-config data: config.yaml: | version: 2 name: prod-gateway # （上記 YAML 全体をインラインで貼り付け） |
Deployment と VolumeMount の設定
|
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 |
apiVersion: apps/v1 kind: Deployment metadata: name: krakend-deploy spec: replicas: 2 selector: matchLabels: app: krakend template: metadata: labels: app: krakend spec: containers: - name: krakend image: krakend/krakend:latest ports: - containerPort: 8080 command: ["run", "-c", "/etc/krakend/config.yaml"] volumeMounts: - name: config-volume mountPath: /etc/krakend/config.yaml subPath: config.yaml volumes: - name: config-volume configMap: name: krakend-config |
commandで公式 CLI のrun -cフラグを使用し、ConfigMap 経由でマウントした設定ファイルを指定しています。
GitHub Actions による自動デプロイ例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
name: Deploy KrakenD Config on: push: paths: - 'config/**.yaml' jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Kube config run: | echo "${{ secrets.KUBE_CONFIG }}" > $HOME/.kube/config chmod 600 $HOME/.kube/config - name: Apply ConfigMap run: kubectl apply -f k8s/configmap.yaml - name: Rollout restart deployment run: kubectl rollout restart deployment/krakend-deploy |
このワークフローは設定ファイルがリポジトリにプッシュされたときだけ実行され、kubectl apply によって ConfigMap が更新され、その後 Deployment のロールアウトが再起動されます。結果として GitOps スタイルで安全かつ即時に変更が反映されます。
まとめ
- KrakenD の設定は
version,name,endpoints,backendの四要素が核となり、公式ドキュメント（2026 年5月版）でも同様に記載されています。 - YAML と JSON は機能面で等価です。可読性とチームのツールチェーン を基準に選択してください。
- KrakenDesigner Web エディタを使えば、コードを書かずに完全な設定ファイル（YAML/JSON）を生成し即座にエクスポートできます。
- Docker / Docker‑Compose では
run -c <path>フラグとデバッグモード-dを組み合わせるだけで簡単にローカルテストが可能です。環境変数でパスを渡す方式は公式では非推奨です。 - 認証・レートリミット・キャッシュ・環境変数置換などの主要機能は YAML の
extra_configに記述し、krakend checkで構文検証、run -dで実行確認ができます。 - 設定ファイルを Kubernetes ConfigMap として管理し、GitHub Actions 等の CI/CD パイプラインと連携させれば、変更の自動デプロイ が実現します。
以上の手順とベストプラクティスに従うことで、2026 年最新版の KrakenD を安全かつ高速に導入でき、マイクロサービス間の API 統合基盤として有力な選択肢となります。