apollo-router

Apollo Router 設定ジェネレーター

Apollo Router は、Apollo Federation 2 のスーパーグラフを実行するための、Rust で書かれた高性能なグラフルーターです。サブグラフの前段に配置され、クエリ計画、実行、レスポンスの合成を処理します。

このスキルは、バージョンに適合した設定を生成します。 Router v1 と v2 では、いくつかの重要なセクション（CORS、JWT 認証、コネクター）の設定スキーマに互換性がありません。設定を生成する前に、必ず対象バージョンを確認してください。

ステップ 1：バージョンの選択

設定を生成する前に、ユーザーに尋ねてください。

Which Apollo Router version are you targeting?

  [1] Router v2.x (recommended — current LTS, required for Connectors)
  [2] Router v1.x (legacy — end-of-support announced, security patches only)
  [3] Not sure — help me decide

ユーザーが [3] を選択した場合は、次を表示します。

Quick guide:

  • Pick v2 if: you're starting fresh, using Apollo Connectors for REST APIs,
    or want backpressure-based overload protection.
  • Pick v1 if: you have an existing deployment and haven't migrated yet.
    Note: Apollo ended active support for v1.x. The v2.10 LTS (Dec 2025)
    is the current baseline. Migration is strongly recommended.

  Tip: If you have an existing router.yaml, you can auto-migrate it:
    router config upgrade router.yaml

選択内容を ROUTER_VERSION=v1|v2 として保存し、以降のすべてのテンプレート生成の判定に使用します。

ステップ 2：環境の選択

本番環境または開発環境を尋ねます。

• 本番環境：セキュリティを強化したデフォルト設定（イントロスペクション無効、サンドボックス無効、ホームページ無効、サブグラフエラー非表示、認証必須、ヘルスチェック有効）
• 開発環境：開放的なデフォルト設定（イントロスペクション有効、サンドボックス有効、エラーを表示、テキストロギング）

適切なベーステンプレートを読み込みます。

• templates/{version}/production.yaml
• templates/{version}/development.yaml

ステップ 3：機能の選択

含める機能を尋ねます。

• JWT 認証
• 宣言的認可（フィールドレベルの @authenticated ／ @requiresScopes ／ @policy ディレクティブ — GraphOS とリクエストクレームが必要）
• CORS（ブラウザクライアントではほぼ常に必要）
• オペレーション制限
• トラフィック制御 ／ レート制限
• テレメトリー（Prometheus、OTLP トレーシング、JSON ロギング）
• APQ（自動永続化クエリ — パフォーマンス／帯域幅のための機能であり、セキュリティ対策ではありません）
• 永続化クエリの許可リスト化（GraphOS PQL のオペレーション許可リスト — セキュリティ対策です。APQ とは異なります）
• コネクター（REST API 統合 — Router v2 のみ。GA キーは connectors、初期の v2 プレビューキーは preview_connectors でした）
• サブスクリプション
• ヘッダーの伝播
• レスポンスキャッシュ（Redis を使用したエンティティおよびルートフィールドのキャッシュ — Router v2 のみ、v2.6.0 以降）

ステップ 4：パラメーターの収集

選択された機能ごとに、必要な値を収集します。

• auth、cors、headers、limits、telemetry、traffic-shaping には、templates/{version}/sections/ のセクションテンプレートを使用します。
• v2 のコネクターには、ソースとして templates/v2/sections/connectors.yaml を使用します。
• APQ とサブスクリプションには、選択したベーステンプレート（templates/{version}/production.yaml または templates/{version}/development.yaml）か、リファレンスからスニペットをコピーします。
• コネクターは ROUTER_VERSION=v2 の場合にのみ提示します。

CORS

• 許可するオリジンの一覧（本番環境では "*" を使用しないでください）

JWT 認証

• JWKS URL
• 発行者（複数可）— 注：v1 では単数形の issuer を使用し、v2 では複数形の issuers 配列を使用します

宣言的な認可（フィールドレベル）

サブグラフのスキーマに適用された @authenticated、@requiresScopes、@policy ディレクティブを介して、ルーター内で強制されるフィールドレベルおよび型レベルのアクセス制御です。グローバルな authorization.require_authentication ゲートでは表現できない層です。これはGraphOS の機能（Enterprise。Developer／Standard プランでは Router v2.6.0+ が必要）であり、GraphOS に接続されたルーターが必要です。ディレクティブはデフォルトで有効であり、設定で行うのは無効化のみです。

これらを推奨する前に、前提条件を確認してください。

• ルーターが GraphOS に接続されていること（Router v1.29.1+。Developer／Standard プランでは v2.6.0+ が必要です）。
• クレームの取得元があること。 ディレクティブは apollo::authentication::jwt_claims コンテキストキーのクレームを評価します。JWT 認証（この機能も設定してください）またはクレームを注入するコプロセッサを介して値を設定します。
• @policy にはさらに Supergraph プラグインが必要です（Rhai スクリプトまたはコプロセッサ）。各ポリシーを評価するためです。ルーターは必要なポリシーを apollo::authorization::required_policies に抽出しますが、独自に判定は行いません。

確認事項：

• 保護が必要なフィールド／型と、そのレベルは何ですか？（@authenticated = 有効な ID があれば可、@requiresScopes = 特定のスコープが必要、@policy = カスタムロジック。）
• スコープ／クレームの取得元はどこですか？（JWT クレームか、コプロセッサによる注入か。）

ディレクティブは router.yaml ではなく、サブグラフのスキーマに記述します。ルーターの設定では、機能の有効／無効を切り替え、（@policy の場合は）評価を行うプラグインを接続するだけです。references/configuration.md → Authorization を参照してください。

永続化クエリのセーフリスト（GraphOS PQL）

APQ とは異なります。 APQ（apq）は、クライアントが送信するあらゆるオペレーションをキャッシュするランタイムの帯域幅最適化であり、セキュリティは提供しません。セーフリストでは、クライアントがビルド時に登録する GraphOS 管理の永続化クエリリスト（PQL）を使用し、ルーターはリストにないオペレーションを拒否します。これが「永続化クエリのセーフリスト化」というセキュリティ制御です。これはGraphOS の機能であり、GraphOS に接続されたルーター（APOLLO_KEY + APOLLO_GRAPH_REF）が必要です。

セキュリティレベルを選択してください（上に進むほど制限が厳しくなります）。

レベル	設定	動作
監査（最初に推奨）	persisted_queries.log_unknown: true	未登録のオペレーションをログに記録しますが、拒否はしません。強制する前に、すべてのクライアントが登録済みであることを確認するために使用します。
セーフリスト	safelist.enabled: true	PQL にないオペレーションを拒否します。登録済みであれば、IDと完全な文字列の両方を受け付けます。
セーフリスト、ID のみ	safelist.enabled: true + require_id: true	未登録のオペレーションおよび自由形式のオペレーション文字列を、文字列が登録済みであっても拒否します。

次に、以下を確認してください。

• ルーターは GraphOS に接続されていますか？ セーフリストには、GraphOS（またはオフラインライセンスの場合は local_manifests）から取得する PQL が必要です。
• クライアントはオペレーションを PQL に公開済みですか（CI/CD で rover persisted-queries publish を使用）？ 未公開の場合は、監査モードから開始してください。
• safelist を有効にする場合は、APQ を無効にする必要があります（apq.enabled: false）。両者は併用できません。

設定キーの履歴：v1.32.0 以降は GA の persisted_queries（v1.25.0～v1.32.0 では preview_persisted_queries）。すべての v2 で GA です。references/configuration.md → Persisted Query Safelisting を参照してください。

コネクター（v2 のみ）

• サブグラフ名とソース名（connectors.sources.<subgraph>.<source> として使用）
• コネクターのランタイム設定用の任意の $config 値
• 以前の v2 プレビュー設定から移行する場合は、preview_connectors を connectors に変更します

オペレーション制限

調整のガイダンスを提示してください。

Operation depth limit controls how deeply nested a query can be.

  Router default: 100 (permissive — allows very deep queries)
  Recommended starting point: 50

  Lower values (15–25) are more secure but will reject legitimate queries
  in schemas with deep entity relationships or nested fragments.
  Higher values (75–100) are safer for compatibility but offer less
  protection against depth-based abuse.

  Tip: Run your router in warn_only mode first to see what depths your
  real traffic actually uses, then tighten:
    limits:
      warn_only: true

What max_depth would you like? [default: 50]

同じ原則が max_height、max_aliases、max_root_fields にも当てはまります。

テレメトリ

• OTEL コレクターのエンドポイント（デフォルト：http://otel-collector:4317）
• Prometheus のリッスンポート（デフォルト：9090）
• トレースのサンプリング率（デフォルト：0.1 = 10%）

トラフィック制御

• クライアント向けレート制限の容量（デフォルト：1000 req/s）
• ルーターのタイムアウト（デフォルト：60s）
• サブグラフのタイムアウト（デフォルト：30s）

レスポンスキャッシュ（v2 のみ、v2.6.0 以降）

セキュリティ：データ漏洩のリスクがあります。 レスポンスキャッシュの設定を生成する前に、ユーザー固有のデータを返す型とフィールドについて、必ずユーザーに確認してください。キャッシュデータはデフォルトで共有されます。Cache-Control: private を指定していないサブグラフのレスポンスは、すべてのユーザーに表示されます。ユーザー固有のサブグラフでは Cache-Control: private を返し、ルーターに private_id を設定する必要があります。

• 確認事項：ユーザー固有のデータを提供するサブグラフはどれですか？（例：accounts、profiles、carts）
• 確認事項：ユーザーをどのように識別しますか？（JWT の sub クレーム、セッショントークン、API キー）
• Redis URL（デフォルト：redis://localhost:6379）
• デフォルトの TTL（デフォルト：5m）
• アクティブな無効化を有効にしますか？有効にする場合：無効化のリッスンアドレスと共有キー
• セクションテンプレートを使用します：templates/v2/sections/response-caching.yaml
• セキュリティ要件、スキーマディレクティブ、高度な設定については、references/response-caching.md を参照してください（Security セクションから読み始めてください）

ステップ 5：設定を生成する

1. templates/{version}/ から適切なバージョンのテンプレートを読み込みます
2. セクション化された機能でサポートされているものについては、セクションテンプレートを組み立て、必要に応じて APQ／サブスクリプション用のベーステンプレートのスニペットを統合します
3. ユーザーから提供されたパラメーターを挿入します
4. 対象バージョンを示すコメントブロックを先頭に追加します

ステップ 6：検証する

生成後のチェックリストを実行します：

• 設定で参照されているすべての環境変数が文書化されている
• CORS オリジンにワイルドカードが含まれていない（本番環境）
• レート制限が all:（サブグラフのみ）ではなく、router:（クライアント向け）に設定されている
• JWT では issuer（v1）ではなく issuers（v2）を使用している（またはその逆）
• 本番環境の場合：introspection=false、sandbox=false、subgraph_errors=false
• ヘルスチェックが有効になっている
• ホームページが無効になっている（本番環境）
• 実行：Router バイナリを利用できる場合は router config validate <file>

必須の検証ゲート（必ず実行）

router.yaml を生成または編集した後は、必ず次の手順を実施してください：

1. validation/checklist.md を実行し、各チェック項目の合格／不合格を報告します。
2. Router CLI を利用できる場合は、router config validate <path-to-router.yaml> を実行します。
3. Router CLI を利用できない場合は、その旨を明記したうえで、チェックリストを最後まで実施します。
4. 検証が完了するまで、設定を最終版として提示しないでください。

コードとしての設定（git + CI/CD）

router.yaml は、すべてのリクエストに対するルーターの契約です。運用上の後回しにせず、アプリケーションコードとして扱ってください。設定を生成または編集する際は、ユーザーに次のワークフローを案内してください：

• router.yaml をバージョン管理にコミットします。 サービスと一緒に git リポジトリに格納し、変更はプルリクエストでレビューします。これにより、API レイヤーで最も安全性が重要なファイルについて、履歴の確認、変更者の特定、ロールバックが可能になります。
• シークレットは絶対にコミットしないでください。 APOLLO_KEY、JWKS URL、Redis URL、無効化キーはファイルに含めず、${env.*} 展開を使って参照し、デプロイ時に注入します。コミットされたファイルは、リポジトリへのアクセス権を持つ誰もが安全に読める状態にしてください。
• CI で検証します。 すべての PR で router config validate router.yaml を実行し、不正な設定やバージョン不一致の設定がリリース前にビルドを失敗させるようにします。CI で使用する Router のバージョンは、デプロイするバージョンに固定してください。
• 設定変更とスキーマチェックを組み合わせます。 スキーマ変更では rover subgraph check／rover subgraph publish（rover スキル）を実行し、設定変更ではこの CI 検証ゲートを実行します。どちらも同じデプロイのゲートとして機能します。
• 同じファイルをすべての環境に昇格させます。 開発環境と本番環境の差分は、コミット済みの別ファイルではなく環境変数で表現します。これにより、レビューした設定がそのまま実行されます。

最小限の CI ステップ（依頼された場合のみ、実際のコマンドを提示します）：

# Validate router config on every pull request
- run: router config validate router.yaml

ステップ 7：条件付きで次のステップを案内

Apollo Router に関するリクエスト（設定の生成、編集、検証、一般的な Router のガイダンス）に回答した後、ユーザーが実行可能な前提条件をすでに満たしているか判断してください。

• GraphOS 管理パス：APOLLO_KEY と APOLLO_GRAPH_REF、または
• ローカルパス：合成済みの supergraph.graphql とアクセス可能なサブグラフ

前提条件がすでに満たされている場合、追加の案内文は不要です。

前提条件が不足している、または不明な場合は、簡潔な 次のステップ の案内で締めくくってください（最大 1〜3 行）。スキルを優先し、コマンドは記載しないでください。

1. スーパグラフスキーマを合成または取得するために、rover スキルを提案します。
2. スーパグラフの準備ができたら、生成した設定を検証して実行するために apollo-router を続けて使うよう提案します。
3. サブグラフが不足している場合は、ひな形の作成とテストに apollo-server、graphql-schema、graphql-operations スキルを提案します。

ユーザーから明示的に求められない限り、この案内にシェルコマンドをそのまま記載しないでください。

クイックスタート（スキル優先）

1. この apollo-router スキルを使って、環境に合わせて router.yaml を生成または調整します。
2. 実行パスを選択します。
   • GraphOS 管理パス：APOLLO_KEY と APOLLO_GRAPH_REF を指定します（ローカルでのスーパグラフ合成は不要です）。
   • ローカルスーパグラフパス：graphql-schema と apollo-server を使ってサブグラフを定義・実行し、続いて graphql-operations でスモークテストを行い、その後 rover スキルで supergraph.graphql を合成または取得します。
3. この apollo-router スキルを使って、準備状況を検証し（validation/checklist.md）、実行時の起動に必要な入力を確認します。

標準の Router リッスン設定を使用する場合、デフォルトのエンドポイントは引き続き http://localhost:4000 です。

実行可能なシェルコマンドをユーザーが求めた場合は、そのリクエストに応じて提示してください。それ以外の場合は、クイックスタートの案内をスキル中心にしてください。

実行モード

モード	コマンド	用途
ローカルスキーマ	router --supergraph ./schema.graphql	開発、CI/CD
GraphOS 管理	APOLLO_KEY=... APOLLO_GRAPH_REF=my-graph@prod router	自動更新を伴う本番環境
開発	router --dev --supergraph ./schema.graphql	ローカル開発
ホットリロード	router --hot-reload --supergraph ./schema.graphql	再起動せずにスキーマを変更

環境変数

変数	説明
APOLLO_KEY	GraphOS の API キー
APOLLO_GRAPH_REF	グラフ参照（graph-id@variant）
APOLLO_ROUTER_CONFIG_PATH	router.yaml のパス
APOLLO_ROUTER_SUPERGRAPH_PATH	スーパグラフスキーマのパス
APOLLO_ROUTER_LOG	ログレベル（off、error、warn、info、debug、trace）
APOLLO_ROUTER_LISTEN_ADDRESS	リッスンアドレスの上書き

リファレンスファイル

• 設定 — YAML 設定のリファレンス
• ヘッダー — ヘッダーの伝播と操作
• プラグイン — Rhai スクリプトとコプロセッサ
• テレメトリ — トレース、メトリクス、ロギング
• コネクター — Router v2 のコネクター設定
• レスポンスキャッシュ — エンティティ／ルートフィールドのキャッシュ、無効化、可観測性（v2 のみ）
• トラブルシューティング — よくある問題と解決策
• 差分マップ — v1 と v2 の設定の違い
• 検証チェックリスト — 生成後の確認項目

CLI リファレンス

router [OPTIONS]

Options:
  -s, --supergraph <PATH>    Path to supergraph schema file
  -c, --config <PATH>        Path to router.yaml configuration
      --dev                  Enable development mode
      --hot-reload           Watch for schema changes
      --log <LEVEL>          Log level (default: info)
      --listen <ADDRESS>     Override listen address
  -V, --version              Print version
  -h, --help                 Print help

基本ルール

• 設定を生成する前に、必ず対象の Router バージョン（v1 または v2）を確認してください
• 新規プロジェクトでは、デフォルトで v2 を使用してください
• 生成する設定の先頭には、対象バージョンを明記したコメントブロックを必ず含めてください
• ローカル開発では、必ず --dev モードを使用してください（イントロスペクションとサンドボックスが有効になります）
• 本番環境では、イントロスペクション、サンドボックス、ホームページを必ず無効にしてください
• 本番環境では、GraphOS 管理モードを優先してください（自動更新、メトリクス）
• ファイルベースのスキーマを使ったローカル開発では、--hot-reload を使用してください
• ログやバージョン管理に APOLLO_KEY を絶対に公開しないでください
• すべてのシークレットおよび機密設定には、環境変数（${env.VAR}）を使用してください
• 複雑な構成では、コマンドライン引数より YAML 設定を優先してください
• 本番環境にデプロイする前に、設定の変更をローカルでテストしてください
• 本番環境でユーザーが allow_any_origin またはワイルドカード CORS を有効にした場合は、警告してください
• v1 から v2 への移行では、ゼロから再生成するのではなく、router config upgrade router.yaml を推奨してください
• Router 設定を生成または編集した後は、必ず validation/checklist.md を実行してください
• Router CLI が利用可能な場合は、必ず router config validate <file> を実行してください
• CLI による検証を実行できなかった場合（例：Router バイナリが見つからない場合）は、必ずその旨を報告してください
• ランタイムの前提条件が不足している、または不明な場合は、必ず簡潔な条件付きの引き継ぎ案内を追加してください
• この引き継ぎ案内ではスキルを優先し、ユーザーが明示的にコマンドを求めない限り、生のシェルコマンドは避けてください
• クイックスタートの案内ではスキルを優先し、ユーザーが明示的にコマンドを求めない限り、コマンドは記載しないでください
• Rover が必要なのはローカルの supergraph パスのみであり、GraphOS 管理ランタイムではローカルでの Rover による合成は不要であることを明記してください
• デフォルトの開始値には max_depth: 50 を使用してください。15 は制限が厳しすぎ、100 は緩すぎます
• 制限を最初に導入する際は、適用前に実際のトラフィックを観察できるよう warn_only: true を推奨してください
• Response Caching を提案できるのは ROUTER_VERSION=v2 の場合のみです（v2.6.0 以降が必要です）
• Redis URL、パスワード、無効化用共有キーには、必ず ${env.*} を使用してください
• 本番環境の設定では、response_cache.debug: true を絶対に有効にしないでください
• 本番環境では、Cache-Control ヘッダー（受動的な TTL）と @cacheTag（能動的な無効化）の併用を推奨してください
• Response Cache の設定を生成する前に、どのフィールドがユーザー固有のデータを返すかを必ず確認してください。すべてのデータを共有キャッシュに安全に保存できると決めつけないでください
• ユーザー固有のデータを提供するサブグラフには、必ず private_id を設定し、それらのサブグラフが Cache-Control: private を返すようにしてください（Apollo Server では @cacheControl(scope: PRIVATE) を使用し、その他のフレームワークではヘッダーを直接設定します）
• プライベートデータへの対処なしに Response Cache の設定を生成しないでください。ユーザーが「ユーザー固有のデータはない」と述べた場合も、続行前に必ず明示的な確認を取ってください
• 無効化エンドポイントは必ず 127.0.0.1 にバインドしてください。本番環境で 0.0.0.0 にバインドすることは絶対に避けてください
• APQ と persisted-query のセーフリストを決して混同しないでください。APQ（apq）はセキュリティ上の価値を持たない帯域幅最適化であり、セーフリスト（persisted_queries.safelist）は操作の許可リストです。ユーザーが「実行できるクエリを制限したい」と尋ねた場合は、APQ ではなくセーフリストを案内してください
• persisted_queries.safelist を有効にする場合は、必ず APQ（apq.enabled: false）を無効にしてください。両者は相互排他的です
• safelist.enabled を有効にする前に、すべてのクライアントが登録されていることを確認できるよう、persisted queries は監査モード（log_unknown: true）から始めることを推奨してください
• persisted-query のセーフリストには、GraphOS に接続されたルーターが必要であることを明記してください（APOLLO_KEY と APOLLO_GRAPH_REF を使用して PQL を取得するか、オフラインライセンスでは local_manifests を使用します）
• preview_persisted_queries（v1.25.0～v1.32.0）ではなく、persisted_queries（GA、v1.32.0 以降およびすべての v2）を使用してください
• グローバルな authorization.require_authentication と宣言的ディレクティブは、異なるレイヤーとして扱ってください。前者はリクエスト全体へのアクセスを制御し、後者（@authenticated／@requiresScopes／@policy）はフィールドレベルおよび型レベルでフィルタリングします
• 宣言的認可ディレクティブには、GraphOS に接続されたルーター（v1.29.1 以降。Developer／Standard プランでは v2.6.0 以降）とクレームソース（JWT 認証、または apollo::authentication::jwt_claims を設定するコプロセッサ）が必要であることを明記してください
• 認可ディレクティブはデフォルトで有効であることに注意してください。authorization.directives.enabled: false は無効にする設定にすぎません。「有効にする」ための設定が必要だと示唆しないでください
• @policy では、apollo::authorization::required_policies を評価するために、Supergraph ステージの Rhai スクリプトまたはコプロセッサも必要であることを明記してください
• 認可ディレクティブはサブグラフスキーマに配置し、router.yaml には絶対に配置しないでください。ルーター設定では機能の有効／無効のみを切り替えます
• router.yaml をバージョン管理にコミットし、すべてのシークレットを ${env.*} で参照してデプロイ時に注入したうえで、すべての PR に対して CI で router config validate を実行することを推奨してください
• シークレット（APOLLO_KEY、JWKS／Redis URL、無効化キー）を設定ファイルにコミットしないでください。コミットする router.yaml は、リポジトリへのアクセス権を持つすべての人と共有しても安全でなければなりません