pjt222 APIゲートウェイの設定
集中型APIトラフィック管理とポリシー強制のためのAPIゲートウェイをデプロイして設定します。
使用タイミング
- 複数のバックエンドサービスに一貫したポリシーを持つ統一APIエンドポイントが必要
- APIアクセスへの集中型認証/認可が必要
- API全体でレート制限とクォータ管理が必要
- バックエンドサービスを変更せずにリクエスト/レスポンスを変換したい
- APIバージョニングと廃止予定の戦略を実装
- 詳細なAPI分析とモニタリングが必要
- マイクロサービスのサービスディスカバリとロードバランシングが必要
入力
- 必須: KubernetesクラスターまたはDocker環境
- 必須: APIゲートウェイの選択（KongまたはTraefik）
- 必須: プロキシするバックエンドサービスエンドポイント
- 任意: 認証プロバイダー（OAuth2、OIDC、APIキー）
- 任意: レート制限要件（分/時間あたりのリクエスト数）
- 任意: カスタムミドルウェアまたはプラグイン設定
- 任意: HTTPSエンドポイント用のTLS証明書
手順
完全な設定ファイルとテンプレートについては拡張例を参照してください。
ステップ1: APIゲートウェイのインストール
データベース付き（Kong）またはファイルベース設定（Traefik）でAPIゲートウェイをデプロイします。
KongとPostgreSQLの場合：
# kong-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
name: kong
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: kong
namespace: kong
spec:
replicas: 2
# ... (PostgreSQL, migrations, services - see EXAMPLES.md)
Traefikの場合：
# traefik-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
name: traefik
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: traefik
namespace: traefik
spec:
replicas: 2
# ... (RBAC, ConfigMap, services - see EXAMPLES.md)
完全なデプロイマニフェストはEXAMPLES.mdを参照
デプロイ：
kubectl apply -f kong-deployment.yaml # OR traefik-deployment.yaml
kubectl wait --for=condition=ready pod -l app=kong -n kong --timeout=300s
kubectl get svc -n kong kong-proxy # Get load balancer IP
期待結果： ゲートウェイのPodが2レプリカで稼働中。LoadBalancerサービスに外部IPが割り当て済み。管理APIにアクセス可能（Kong：ポート8001、Traefik：ダッシュボードポート8080）。ヘルスチェックが合格。
失敗時：
- Podのログを確認：
kubectl logs -n kong -l app=kong - データベース接続を確認（Kong）：
kubectl logs -n kong kong-migrations-<hash> - サービスアカウントのパーミッションを確認（Traefik）：
kubectl get clusterrolebinding traefik -o yaml - ポートがすでに使用中でないか確認：
kubectl get svc --all-namespaces | grep 8000
ステップ2: バックエンドサービスとルートの設定
上流サービスを定義してAPIを公開するルートを作成します。
Kongの場合（宣言的設定にdeCKを使用）：
# Install decK CLI
curl -sL https://github.com/Kong/deck/releases/download/v1.28.0/deck_1.28.0_linux_amd64.tar.gz | tar -xz
sudo mv deck /usr/local/bin/
# Create kong.yaml with services, routes, upstreams
# (see EXAMPLES.md for complete configuration)
deck sync --kong-addr http://localhost:8001 -s kong.yaml
curl -i http://localhost:8001/routes # Verify routes
Traefikの場合（IngressRoute CRDを使用）：
# traefik-routes.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: user-api-route
spec:
entryPoints: [websecure]
routes:
- match: Host(`api.example.com`) && PathPrefix(`/api/users`)
# ... (see EXAMPLES.md for full configuration)
ルートを適用：
kubectl apply -f traefik-routes.yaml
curl -H "Host: api.example.com" https://GATEWAY_IP/api/users
完全なルーティング設定はEXAMPLES.mdを参照
期待結果： ルートがトラフィックをバックエンドサービスに正しくプロキシ。重み付きルーティングが設定に従ってトラフィックを分散。ヘルスチェックがバックエンドサービスの健全性を監視。
失敗時：
- バックエンドサービスが稼働中か確認：
kubectl get svc -n default - DNS解決を確認：
kubectl run test --rm -it --image=busybox -- nslookup user-service.default.svc.cluster.local - ゲートウェイのログを確認：
kubectl logs -n kong -l app=kong --tail=50 - 設定を検証：
deck validate -s kong.yaml
ステップ3: 認証と認可の実装
APIセキュリティのための認証プラグイン/ミドルウェアを設定します。
Kongの場合（APIキーとJWT認証）：
# kong-auth-config.yaml (excerpt)
consumers:
- username: mobile-app
custom_id: app-001
keyauth_credentials:
- consumer: mobile-app
key: mobile-secret-key-123
plugins:
- name: key-auth
service: user-api
# ... (see EXAMPLES.md for full configuration)
deck sync --kong-addr http://localhost:8001 -s kong-auth-config.yaml
curl -i -H "apikey: mobile-secret-key-123" http://GATEWAY_IP/api/users
Traefikの場合（BasicAuthとForwardAuthミドルウェア）：
# traefik-auth-middleware.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: basic-auth-middleware
spec:
basicAuth:
secret: basic-auth
removeHeader: true
# ... (see EXAMPLES.md for OAuth2, rate limiting)
kubectl apply -f traefik-auth-middleware.yaml
curl -u user1:password https://GATEWAY_IP/api/protected
完全な認証設定はEXAMPLES.mdを参照
期待結果： 未認証リクエストが401を返す。有効なクレデンシャルでアクセスが許可。レート制限が閾値を超えた後429を返す。JWTトークンが正しく検証される。ACLがグループのパーミッションを強制。
失敗時：
- コンシューマーの作成を確認：
curl http://localhost:8001/consumers - プラグインが有効か確認：
curl http://localhost:8001/plugins | jq . - verbose付きでテスト：
curl -vでレスポンスヘッダーを確認 - JWTを検証：jwt.ioでトークンをデコード
ステップ4: リクエスト/レスポンス変換の設定
リクエストとレスポンスを変換するミドルウェアを追加します。
Kongの場合：
# kong-transformations.yaml (excerpt)
plugins:
- name: request-transformer
service: user-api
config:
add:
headers: [X-Gateway-Version:1.0, X-Request-ID:$(uuid)]
remove:
headers: [X-Internal-Token]
- name: correlation-id
# ... (see EXAMPLES.md for full configuration)
deck sync --kong-addr http://localhost:8001 -s kong-transformations.yaml
Traefikの場合：
# traefik-transformations.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: add-headers
spec:
headers:
customRequestHeaders:
X-Gateway-Version: "1.0"
# ... (see EXAMPLES.md for circuit breaker, retry, chain)
kubectl apply -f traefik-transformations.yaml
curl -v https://GATEWAY_IP/api/users | grep X-Gateway
完全な変換設定はEXAMPLES.mdを参照
期待結果： リクエストヘッダーが設定通りに追加/削除される。レスポンスヘッダーにゲートウェイメタデータが含まれる。大きなリクエストが413で拒否される。サーキットブレーカーが繰り返しの失敗でトリップ。一時的なエラーにリトライが発生。
失敗時：
- チェーン内のミドルウェアの順序を確認
- バックエンドサービスとのヘッダー競合を確認
- チェーン化する前に変換を個別にテスト
- 変換エラーのログを確認
ステップ5: モニタリングと分析の有効化
API可視性のためのメトリクス、ログ、ダッシュボードを設定します。
Kongのモニタリングセットアップ：
# kong-monitoring.yaml (excerpt)
plugins:
- name: prometheus
config:
per_consumer: true
- name: http-log
service: user-api
# ... (see EXAMPLES.md for Datadog, file-log configuration)
deck sync --kong-addr http://localhost:8001 -s kong-monitoring.yaml
# Deploy ServiceMonitor (see EXAMPLES.md)
kubectl apply -f kong-servicemonitor.yaml
curl http://localhost:8100/metrics
Traefikのモニタリング（組み込み）：
# ServiceMonitor (excerpt - see EXAMPLES.md for Grafana dashboard)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: traefik-metrics
spec:
endpoints:
- port: metrics
path: /metrics
interval: 30s
kubectl port-forward -n traefik svc/traefik-dashboard 8080:8080
# Open http://localhost:8080/dashboard/
完全なモニタリング設定はEXAMPLES.mdを参照
期待結果： Prometheusがゲートウェイメトリクスをスクレーピング成功。ダッシュボードがリクエスト率、レイテンシパーセンタイル、エラー率を表示。ログが集約システムに転送。メトリクスがサービス、ルート、コンシューマー別に分割。
失敗時：
- ServiceMonitorを確認：
kubectl get servicemonitor -A - UIでPrometheusターゲットを確認
- メトリクスポートがアクセス可能か確認：
kubectl port-forward -n kong svc/kong-metrics 8100:8100 - ログエンドポイントの到達可能性を検証
ステップ6: APIバージョニングと廃止予定の実装
バージョン管理と優雅なAPI廃止予定を設定します。
Kongのバージョニング戦略：
# kong-versioning.yaml (excerpt)
services:
- name: user-api-v1
url: http://user-service-v1.default.svc.cluster.local:8080
routes:
- name: user-v1-route
paths: [/api/v1/users]
plugins:
- name: response-transformer
config:
add:
headers:
- X-Deprecation-Notice:"API v1 deprecated on 2024-12-31"
- Sunset:"Wed, 31 Dec 2024 23:59:59 GMT"
# ... (see EXAMPLES.md for v2, default routing, rate limits)
Traefikのバージョニング：
# traefik-versioning.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: v1-deprecation-headers
spec:
headers:
customResponseHeaders:
X-Deprecation-Notice: "API v1 deprecated on 2024-12-31"
# ... (see EXAMPLES.md for complete IngressRoutes)
バージョニングをテスト：
curl -i https://api.example.com/api/v1/users # Deprecated
curl -i https://api.example.com/api/v2/users # Current
curl -i https://api.example.com/api/users # Routes to v2
完全なバージョニング設定はEXAMPLES.mdを参照
期待結果： 異なるバージョンが適切なバックエンドサービスにルーティング。v1レスポンスに廃止予定ヘッダーが存在。廃止予定バージョンはレート制限が厳しい。デフォルトパスが最新バージョンにルーティング。メトリクスがAPIバージョン別に分割。
失敗時：
- パス優先度/プライオリティ設定を確認（優先度が高い = 最初に評価される）
- 重複するパスパターンを確認
- 各バージョンのルートを独立してテスト
- ルーティングのログでパスマッチングを確認
- 各バージョンのバックエンドサービスが稼働中か確認
バリデーション
- APIゲートウェイのPodがHA用の複数レプリカで稼働中
- LoadBalancerサービスに外部IPが割り当て済み
- ルートがトラフィックをバックエンドサービスに正しくプロキシ
- 認証/認可がアクセス制御を強制（401/403レスポンス）
- レート制限がクォータ超過後に429を返す
- リクエスト/レスポンス変換がヘッダーを正しく追加/削除
- サーキットブレーカーがバックエンドの繰り返し失敗でトリップ
- メトリクスが公開されPrometheusにスクレーピングされている
- ダッシュボードがリクエスト率、レイテンシ、エラーを表示
- APIバージョニングがリクエストを正しいバックエンドバージョンにルーティング
- 古いAPIバージョンのレスポンスに廃止予定ヘッダーが存在
- ヘルスチェックがバックエンドサービスの可用性を監視
よくある落とし穴
データベース依存（Kong）: データベースを持つKongはPostgreSQL/Cassandraが必要。DBレスモードは利用可能だが一部の機能が制限される（実行時の設定変更）。複数のゲートウェイインスタンスを持つ本番ではDBモードを使用する。
パスマッチングの順序: ルート/IngressRouteが特定の順序で評価される。より具体的なパスは優先度を高くすべき。重複するパスは予測不可能なルーティングを引き起こす。
curl -vで実際にヒットしたルートを確認する。認証バイパス: 全ルートに認証プラグインが適用されていることを確認する。認証なしにルートを追加しやすい。サービスレベルでデフォルトプラグインを使用し、必要に応じてルート単位でオーバーライドする。
レート制限のスコープ: レート制限の
policy: localはゲートウェイのPod単位でカウントする。レプリカ間で一貫した制限には集中型ポリシー（Redis）またはスティッキーセッションを使用する。CORS設定: APIゲートウェイがCORSを処理すべきで、個々のサービスではない。ブラウザのプリフライト失敗を避けるために早い段階でCORSプラグイン/ミドルウェアを追加する。
SSL/TLSターミネーション: ゲートウェイは通常SSLを終端する。証明書が有効で自動更新が設定されていることを確認する。Kubernetes証明書管理にcert-managerを使用する。
上流のヘルスチェック: バックエンドの失敗を素早く検出するためにアクティブなヘルスチェックを設定する。パッシブチェックはリアルトラフィックに依存し、問題の検出が遅い場合がある。
プラグイン/ミドルウェアの実行順序: 順序が重要。レート制限より先に認証（無効なリクエストでレート制限スロットを無駄にしない）。ログより先に変換（変換された値をログに記録する）。
リソース制限: ゲートウェイのPodは負荷がかかると大量のCPUを消費する可能性がある。適切なリソースリクエスト/制限を設定する。本番でのCPUスロットリングを監視する。
移行戦略: 全プラグインを一度に有効にしない。段階的にロールアウトする：ルーティング → 認証 → レート制限 → 変換 → 高度な機能。
関連スキル
configure-ingress-networking- APIゲートウェイを補完するIngressコントローラーのセットアップsetup-service-mesh- サービスメッシュが補完的な東西トラフィック管理を提供manage-kubernetes-secrets- ゲートウェイの証明書とクレデンシャル管理setup-prometheus-monitoring- ゲートウェイメトリクスのモニタリング統合enforce-policy-as-code- ゲートウェイ認可を補完するポリシー強制