Contents
KrakenD の基本概念とバージョン情報
KrakenD は API アグリゲーター兼ゲートウェイ として、複数のバックエンドサービスを単一エンドポイントに統合し、認証・レートリミット・キャッシュなどの横断的機能を提供します。マイクロサービス環境で API の入口を一本化できるため、クライアント実装がシンプルになるだけでなく、セキュリティポリシーやログ収集の集中管理 が可能です。本節では KrakenD の概要と、公式ドキュメント上で確認できる最新安定版情報について解説します。
**※ バージョン情報は執筆時点の公式 GitHub リリースページ（https://github.com/devopsfaith/krakend/releases）をご参照ください。特定バージョンを記載する場合は、必ず公式情報と照らし合わせた上で更新してください。
前提条件とインストール方法
このセクションでは、ローカル環境に KrakenD を導入するために必要な前提条件と、バイナリ版・Docker 版それぞれの取得手順を具体的に示します。どちらの方式でも krakend version が期待通りに表示されればインストールは完了です。
必要な OS とツールチェーン
KrakenD は Linux（Ubuntu 22.04 以降）と macOS（12.0 以上）で公式にサポートされています。Windows 環境では WSL2 の利用が推奨されます。また、プラグイン開発やカスタムビルドを行う場合は Go 言語（go1.22 以降）が必要です。
| ツール | 必要性 | 推奨バージョン |
|---|---|---|
| Docker | 任意（コンテナ実行） | 24.x 以上 |
| curl | バイナリ取得に必須 | 最新版 |
| git | ソース取得・バージョン管理 | 2.40 以上 |
バイナリ取得とローカルインストール
- GitHub の Release ページから対象バイナリ（例:
krakend_2.4.0_linux_amd64.tar.gz）をダウンロードします。 - 解凍後、実行可能ファイルをシステムの
$PATHが通ったディレクトリへ配置します。
|
1 2 3 4 |
curl -L https://github.com/devopsfaith/krakend/releases/download/v2.4.0/krakend_2.4.0_linux_amd64.tar.gz | tar xz sudo mv krakend /usr/local/bin/ krakend version # 例: 2.4.0 |
注意：
hostやportをハードコーディングしたまま実行すると、環境間で設定ミスが起きやすくなります。後述の 環境変数置換 を活用し、設定ファイル中に直接数値を書かないようにしてください。
Docker イメージの取得とタグ確認
Docker がインストールされている環境では、公式イメージを利用すると依存関係の管理が不要です。
|
1 2 3 |
docker pull devopsfaith/krakend:2.4.0 docker images | grep krakend # タグが 2.4.0 であることを確認 |
取得したイメージは devopsfaith/krakend:2.4.0 として利用できます。Docker Compose での起動例は次節で紹介します。
krakend.json の構造と主要設定項目
KrakenD の挙動はすべて krakend.json に記述されます。本章ではトップレベルキーからエンドポイント、バックエンド、ミドルウェアまでを順に解説し、実運用で注意したいポイントを併せて紹介します。
エンドポイント定義とバックエンドマッピング
endpoints 配列の各要素が外部へ公開する API パスとなります。以下は GET /v1/users/{id} を内部サービス user-svc に転送し、レスポンスフィールドを整形する最小構成です。
|
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 |
{ "version": 3, "name": "company-api-gateway", "endpoints": [ { "endpoint": "/v1/users/{id}", "method": "GET", "output_encoding": "json", "backend": [ { "url_pattern": "/users/{id}", "host": ["http://{{ .Env.BACKEND_HOST }}:{{ .Env.BACKEND_PORT }}"], "encoding": "json" } ], "extra_config": { "github.com/devopsfaith/krakend-cors": { "allow_origins": ["*"], "allow_methods": ["GET"] } } } ] } |
ポイント
-hostに直接 IP アドレスやポート番号を書かず、{{ .Env.VAR }}形式で環境変数置換を行うと、開発・ステージング・本番間の差分管理が容易になります。
- Docker Compose のサービス名は DNS エイリアスとして自動的に解決されるため、user-svcと名前付けすればhostで同名を使用でき、ハードコーディングを回避できます。
ミドルウェア設定（JWT・レートリミット・CORS）
KrakenD のプラグインは extra_config にキー名で追加します。代表的なものを以下に示します。全て環境変数による動的置換が可能です。
JWT 認証
|
1 2 3 4 5 6 7 8 9 |
{ "github.com/devopsfaith/krakend-jwt": { "alg": "HS256", "secret": "{{ .Env.JWT_SECRET }}", "disable_jwk_security": true, "propagation_field_name": "Authorization" } } |
Redis ベースのレートリミット
|
1 2 3 4 5 6 7 8 |
{ "github.com/devopsfaith/krakend-ratelimit/redis": { "max_rate": 100, "capacity": 200, "redis_url": "redis://{{ .Env.REDIS_HOST }}:6379/0" } } |
CORS（エンドポイント例に組み込み済み）
|
1 2 3 4 5 6 7 |
{ "github.com/devopsfaith/krakend-cors": { "allow_origins": ["https://example.com"], "allow_methods": ["GET", "POST"] } } |
環境別設定のための変数置換
KrakenD は {{ .Env.VAR_NAME }} 形式のテンプレートエンジンを提供しています。.env.development、.env.production といったファイルに環境ごとの値を書き、Docker Compose の env_file: オプションで読み込むだけで設定が切り替わります。
|
1 2 3 4 5 6 |
# .env.production BACKEND_HOST=user-svc BACKEND_PORT=8080 JWT_SECRET=xxxxxxxxxxxxxx REDIS_HOST=redis |
この方式を採用すれば、コードベースにハードコーディングされたホスト名やポート番号が残らず、設定ミスのリスクを大幅に低減できます。
Docker / docker‑compose での本格デプロイ手順
実務で最も採用されているパターンは Docker Compose によるマルチコンテナ構成です。ここでは KrakenD とサンプルバックエンド API（user-svc）を同一ネットワーク上に配置する例を示します。
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 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
version: "3.9" services: krakend: image: devopsfaith/krakend:2.4.0 container_name: krakend-gw restart: unless-stopped ports: - "8443:8443" # TLS 用ポート（後述の設定を参照） volumes: - ./config:/etc/krakend # 設定ファイルをマウント env_file: - .env.production # 環境変数注入 command: ["run", "-c", "/etc/krakend/krakend.json"] networks: - api-net user-svc: image: myorg/user-service:1.4.0 container_name: user-svc restart: unless-stopped ports: - "8081:8080" # コンテナ内部は 8080、外部は任意にマッピング可 networks: - api-net redis: image: redis:7-alpine container_name: redis restart: unless-stopped ports: - "6379:6379" networks: - api-net networks: api-net: driver: bridge |
設定ポイントの解説
volumesによる設定ファイルマウントは、変更を即座にコンテナへ反映できるため開発サイクルが高速になります。env_fileを利用すれば、.env.productionのキーが自動的に環境変数として注入され、前節で紹介した{{ .Env.VAR }}が正しく展開されます。- TLS 用ポート 8443 は後述の セキュリティと TLS 設定ベストプラクティス に従い証明書をマウントして有効化します。
コンテナ間エイリアスとネットワーク設定
Docker のブリッジネットワークは内部 DNS を提供し、service-name がそのまま名前解決できるため追加設定は不要です。上記例では user-svc と redis がそれぞれのコンテナ名で DNS エイリアスとなります。
Kubernetes への移行ポイント（オプション）
Kubernetes 環境へ展開する際は、Docker Compose とは概念が異なる点に注意が必要です。以下では主要な差分と、公式マニュアルを踏まえた設定例を示します。
Deployment と Service の基本構成
|
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 |
apiVersion: apps/v1 kind: Deployment metadata: name: krakend-gw spec: replicas: 2 selector: matchLabels: app: krakend template: metadata: labels: app: krakend spec: containers: - name: krakend image: devopsfaith/krakend:2.4.0 args: ["run", "-c", "/etc/krakend/krakend.json"] ports: - containerPort: 8443 volumeMounts: - name: config mountPath: /etc/krakend - name: tls mountPath: /certs envFrom: - secretRef: name: krakend-env # Secret に格納した環境変数を一括取り込み volumes: - name: config configMap: name: krakend-config - name: tls secret: secretName: krakend-tls --- apiVersion: v1 kind: Service metadata: name: krakend-svc spec: selector: app: krakend ports: - protocol: TCP port: 443 targetPort: 8443 type: LoadBalancer |
設定上の注意点
| 項目 | Docker Compose | Kubernetes |
|---|---|---|
| 環境変数管理 | .env ファイル |
Secret / ConfigMap の envFrom が推奨 |
| 設定ファイルマウント | ボリュームで直接マウント | ConfigMap → VolumeMount |
| TLS 証明書 | ホスト側ボリュームをマウント | Secret に格納し、Pod へマウント |
| 水平スケール | restart: unless-stopped のみ |
Deployment.replicas で容易に調整可能 |
重要：Kubernetes 用 Helm チャートは公式リポジトリ（https://github.com/devopsfaith/krakend/tree/master/charts）を参照し、バージョンごとの
values.yaml内容を必ず確認してください。未検証のextraEnvFromなどの機能は、実際にチャートに記載があるかどうかで使用可否を判断します。
セキュリティと TLS 設定ベストプラクティス
外部からの通信は 必ず HTTPS とし、内部サービス間でも必要に応じて mTLS を有効化することで、盗聴・改ざんリスクを低減できます。本節では具体的な設定手順と推奨パラメータを紹介します。
1. 証明書の取得と配置
(a) Let’s Encrypt + cert‑manager（Kubernetes 向け）
|
1 2 3 4 5 6 7 8 9 10 11 12 |
apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: krakend-tls spec: secretName: krakend-tls # 生成された Secret が TLS 用に利用される dnsNames: - api.example.com issuerRef: name: letsencrypt-prod kind: ClusterIssuer |
(b) 手動で作成した自己署名証明書（Docker Compose 向け）
|
1 2 3 4 5 |
# 秘密鍵と証明書を作成 openssl req -newkey rsa:2048 -nodes -keyout krakend.key -x509 -days 365 -out krakend.crt -subj "/CN=api.local" # 証明書をコンテナにマウントするディレクトリへコピー mkdir -p ./certs && cp krakend.{key,crt} ./certs/ |
docker‑compose.yml に以下のようにボリュームを追加します。
|
1 2 3 4 5 6 |
krakend: # 省略... volumes: - ./config:/etc/krakend - ./certs:/certs:ro # 読み取り専用でマウント |
2. KrakenD 側の TLS 設定
krakend.json に tls セクションを追加します。
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "port": 8443, "tls": { "cert_file": "/certs/krakend.crt", "key_file": "/certs/krakend.key", "client_auth_type": "NoClientCert", // 必要なら "RequireAndVerifyClientCert" "ca_cert_file": "" // mTLS 用 CA 証明書（省略可） }, /* 既存設定はそのまま */ } |
3. 推奨する TLS パラメータ
| 項目 | 推奨値 | 理由 |
|---|---|---|
| プロトコル | TLS 1.2 以上 | 古いバージョンは脆弱性が残存 |
| 暗号スイート | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 系列 |
前方秘匿性と高速性の両立 |
| 証明書有効期間 | 90 日以内（Let’s Encrypt のデフォルト） | 短い有効期限で鍵漏洩リスクを低減 |
| HTTP Strict Transport Security (HSTS) | max-age=31536000; includeSubDomains |
ブラウザに HTTPS 強制を指示 |
4. ログとメトリクスの暗号化
- アクセスログ：標準出力へ JSON 形式で出力し、ELK/Loki 側で TLS 経由で転送。
- Prometheus メトリクス：
/metricsエンドポイントはtls_configを付与し、https://api.example.com/metricsとして取得。
テスト・本番移行チェックリスクと対策
設定が完了したら、本番投入前に 自動テスト と 運用監視項目 を網羅的に確認します。以下は実務で推奨する手順です。
ローカル/ステージングでの動作検証フロー
- 設定スキーマバリデーション
bash
krakend check -c config/krakend.json - HTTPS エンドポイントへのヘルスチェック
bash
curl -k https://localhost:8443/__health | jq . - 機能別 API 呼び出しテスト（curl）
bash
curl -k https://localhost:8443/v1/users/123 \
-H "Authorization: Bearer $TOKEN" - ユニットテスト（Go）
github.com/devopsfaith/krakend-testライブラリを利用し、バックエンドモックで期待応答を検証。
本番環境向けチェックリスト
- JSON スキーマバリデーションが成功しているか (
krakend check) - ヘルスチェックエンドポイント
/__healthが 200 を返すか - TLS 設定が正しく反映され、証明書チェーンが検証できるか（
openssl s_client -connect api.example.com:443） - ログ出力先が ELK/Loki に届き、JSON パースエラーがないか
- Prometheus メトリクス
/metricsが HTTPS 経由で取得可能か - レートリミットや JWT の設定が期待通りに機能し、誤検知が発生していないか（テストユーザーで負荷シミュレーション）
- 水平スケール時のロードバランサー挙動：ReplicaSet が 3 以上の場合でもリクエスト分散が均等に行われるか
よくあるエラーと対処例
| エラー | 主な原因 | 推奨対策 |
|---|---|---|
Invalid JSON: schema validation failed |
krakend.json の構文ミスや必須フィールド欠如 |
krakend check -c … でエラーメッセージを確認し、キー名・型を修正 |
Backend request failed: connection refused |
コンテナ名解決失敗／ポート不一致 | Docker Compose の networks: と host: が一致しているか再確認。環境変数置換が正しく展開されているかもチェック |
TLS handshake error |
証明書パス誤り、期限切れ、CA 不在 | openssl s_client -connect …:8443 -servername … で詳細を取得し、証明書ファイルとチェーンを見直す |
JWT verification error: token expired |
トークン有効期限切れ、サーバ時刻ずれ | NTP 同期を徹底し、exp クレームのデフォルト有効期間を適切に設定 |
Rate limit exceeded が過剰に発生 |
キーがグローバル化されている | propagation_field_name をエンドポイント単位で分離し、Redis のキー命名規則を調整 |
上記対策は公式プラグインドキュメント（https://www.krakend.io/docs/plugins/）でも詳述されています。
まとめと次のアクション
- KrakenD は API アグリゲーション・認証・レートリミットを一元管理できる本格的なゲートウェイです。最新安定版は公式リリースページで随時確認し、未検証情報を書き込まないように注意してください。
- 前提条件（OS、Docker、Go） を整えたら、バイナリまたは公式 Docker イメージでインストールし、
krakend versionが期待通り表示されることを確認します。 - 設定ファイルは環境変数置換とテンプレートエンジンを活用し、ハードコーディングされたホスト名・ポート番号を排除することで、環境間の差異による障害リスクを低減できます。
- Docker Compose でコンテナ間エイリアスとネットワークを構築すればローカルからステージング、本番へシームレスにデプロイ可能です。Kubernetes 移行時は ConfigMap・Secret と Deployment の組み合わせで同等の構成が実現できます。
- TLS/HTTPS を必須化し、証明書管理と暗号スイート設定をベストプラクティス通りに行うことで、外部通信の安全性を確保します。内部サービス間でも mTLS が必要な場合は
tls.client_auth_typeを適切に設定してください。 - 本番リリース前には
krakend check、ヘルスチェック、Prometheus/Grafana 連携、水平スケール検証を必ず実施し、典型的なエラーはログとメトリクスで早期に検知できる体制を整えます。
これらの手順を踏めば、KrakenD を用いた API ゲートウェイ基盤が安定して運用でき、マイクロサービス全体の可観測性とセキュリティも向上します。ぜひサンプル krakend.json と Docker‑Compose ファイルを自プロジェクトに取り込み、実際の API フローで試行錯誤しながら最適化してください。