signadot-validate

Signadot：マイクロサービスの変更を検証する

Signadot を使用すると、サービスをローカルで実行できない場合を除き、イメージをビルドせずに、実際のクラスター依存関係に対してコード変更を検証できます。ローカルマッピングされたサンドボックスを優先します。変更したサービスをローカルで実行し、ルーティングキーを使ってクラスターのトラフィックをサービスにルーティングし、検証パス全体が成功するまで繰り返します。

リファレンスマップ

ワークフローが該当するトピックに到達した場合にのみ、次の一段階のリファレンスを読み込んでください。

• references/sandbox-setup.md：クラスターとワークロードの解決、サンドボックスの再利用／作成／更新、devbox の検出、環境変数の再構築、プロセスの起動、ポートのルール。
• references/validation-types.md：統合テスト、既存の E2E スイート、アドホックなブラウザー自動化、ルーティングキーの注入を伴う既存のタグ付き Signadot プランの実行方法。
• references/troubleshooting.md：503、ベースラインのような応答、ブラウザーの空白表示、伝播の失敗、非同期ホップ、プロセスの終了、gRPC DNS の遅延に関する迅速な診断。
• references/worked-example.md：ローカルサンドボックスを使用して UI の変更を検証するエンドツーエンドの例。

コアワークフロー

ワークフローは 4 つのフェーズで構成されます。A（コーディング前）、B（サンドボックスをセットアップ）、C（検証を実行）、D（反復）。手順は実行順に番号が付いており、それぞれ詳細を説明するリファレンスにリンクしています。

1. コーディング前に「検証済み」の定義を決める（フェーズ A）。ユーザーが検証タイプを指定していない場合は、質問を 1 つして、次の選択肢を提示します。統合テスト、既存の e2e スイート、アドホックなブラウザー自動化、または既存のタグ付き Signadot プランです。検証タイプによって、実装の構成、サンドボックスのポート、ルーティングキーの受け渡し方法が変わります。Locust、Postman、カスタム Cypress スクリプトなど、別のツールが指定された場合も、同じ原則に従います。HTTP/gRPC クライアントがどこにあり、ルーティングキーをどのように送信するかを確認します。 references/validation-types.mdを参照してください。
2. クラスターとワークロードを特定する（フェーズ B）。利用可能な場合は Signadot MCP サーバーを使用し、それ以外の場合は CLI を使用します。推測ではなく、ツールまたはリポジトリ内の Signadot 仕様を使って名前を特定します。複数のクラスター、ワークロード、または devbox があるためツールの応答で確認を求められた場合は、ユーザーに選択を依頼します。 references/sandbox-setup.mdを参照してください。
3. 作成する前に再利用する（フェーズ B）。新しく作成する前に、同じユーザーとワークロードに対応する稼働中のサンドボックスがあるか確認します。再利用すると、ローカルテストの環境変数、curl、ブラウザー自動化の間でルーティングキーを維持できます。 references/sandbox-setup.mdを参照してください。
4. サンドボックスを作成または更新する（フェーズ B）。条件に合う既存のリポジトリ仕様が.signadot/にある場合は、それを使用します。それ以外の場合は、変更した、または変更によるユーザーから見える経路をたどるために必要なサービスだけを含む、ローカルマッピングを備えた最小限のサンドボックスを作成します。 必須フィールド、ポートのルール、プレビューエンドポイントのポリシーについては、references/sandbox-setup.mdを参照してください。
5. 環境変数を取得し、サービスを起動する（フェーズ B）。まず、リポジトリで通常使用する実行コマンドを確認します。サービス間のアドレス、シークレット、機能フラグをはじめ、必要な環境変数をすべてエクスポートします。バックグラウンドで実行する前にビルドし、プロセスが稼働していて、ポートがリッスンしていることを確認します。 references/sandbox-setup.mdと、「Starting The Service」セクションを参照してください。
6. クラスター URL 経由で検証する（フェーズ C）。ルーティングキーヘッダーを付けて、http://<svc>.<namespace>.svc:<service-port>/...にトラフィックを送信します。localhost:<port>を直接呼び出して検証してはいけません。 フェーズ A で選択したタイプに該当するサブセクションについては、references/validation-types.mdを参照してください。
7. 失敗を受けて反復する（フェーズ D）。失敗の内容を正確に確認し、原因を最小限の範囲で修正し、影響を受けるサービスを再起動して、同じサンドボックスに対して同じ検証を再実行します。合意した検証経路に合格するまでは、成功を報告してはいけません。 references/troubleshooting.mdを参照してください。
8. **適切に終了処理する。**サンドボックス名、クラスター、ルーティングキー、ターゲット URL、検証コマンドまたはブラウザー経路、停止したローカルプロセスを報告します。既定ではサンドボックスを起動したままにし、削除コマンドは選択肢としてのみ提示します。

MCP と CLI の使用

Signadot MCP サーバーが利用可能な場合は、制御プレーンの作業に使用します。クラスター、サンドボックス、routegroup、ワークロード、エンドポイント、devbox の一覧表示と確認、および下記の副作用ポリシーで許可される場合のサンドボックスの作成または更新を行います。意図に基づいて検索し、ツールを呼び出す前にツールスキーマを読み込み、記憶よりもツールの出力を優先します。

MCP が利用できない場合は、CLI の代替手段を使用します。

signadot cluster list -o json
signadot sandbox list -o json
signadot sandbox get <name> -o json
signadot sandbox apply -f <spec.yaml>
signadot sandbox get-env <name>
signadot sandbox get-files <name>

MCP で同じワークロード、ConfigMap、Secret、または Service のデータを取得できず、ローカル環境からクラスターにアクセスできる場合に限り、kubectl get <kind> <name> -n <ns> -o yamlを使用します。

シグナル一覧

シグナル	用途
ローカルプロセスが実際のクラスターのトラフィックを受信する	イメージをビルドせずに変更したサービスを検証する際の、デフォルトの第一選択肢です
クラスターの DNS/IP がローカルで名前解決できる	signadot local connect または開発ボックスを使うと、.svc 名にアクセスできます
ルーティングされたリクエストの処理中にローカルの stdout/stderr が出力される	リクエストが変更したコードに届くのを確認し、パニックを把握して、デバッガーをアタッチします
サンドボックスの準備状態、フォーク、ルーティング状態、トンネル接続	コードをテストする前に、サンドボックスでルーティングできることを確認します
明示的にリクエストした場合のプレビューエンドポイント	手動でルーティングヘッダーを設定せずにフォークへ確実にアクセスできますが、公開 URL *.preview.signadot.com が公開される可能性があります
ルーティングキーによる分離	キー付きトラフィックがサンドボックスに到達し、キーなしのトラフィックはベースラインにとどまることを証明します
signadot local proxy	依存先への到達性を診断します。検証結果ではありません

副作用に関するポリシー

アクション	デフォルトの動作
クラスター、ワークロード、エンドポイント、サンドボックス、ルートグループの読み取り	自律的に行います
このタスク用の分離されたサンドボックスの作成	クラスターとワークロードを一意に特定できる場合は、自律的に行います
このタスクが所有していることが明らかなサンドボックスの更新	自律的に行います
共有サンドボックスまたはルートグループの更新	事前に確認します
defaultRouteGroup.endpoints などの公開プレビューエンドポイントの追加	事前に確認します
サンドボックスの削除	事前に確認します。デフォルトでは起動したままにします
sudo signadot local connect --cluster <cluster> または signadot local disconnect の実行	ローカルのネットワークスタックを変更し、sudo が必要になる場合があるため、ユーザーに実行を依頼します
signadot local status または signadot local proxy の実行	有用な場合は自律的に行います。proxy は診断用であり、検証の証明にはなりません

ルーティングルール

重要なポートは2種類

2種類のポートの概念を混同しないでください。

コンテキスト	使用するポート	解決方法
サンドボックスのローカルマッピング	ワークロード／コンテナポート	resolve_workload_port などの MCP ワークロードポートリゾルバー、またはワークロード仕様を使用します
.svc URL への検証トラフィック	Kubernetes サービスポート	resolve_endpoints などのエンドポイントリゾルバー、Service オブジェクト、またはリポジトリの Signadot 仕様を使用します

マッピングで誤ったコンテナポートを使用していても、トンネルが接続されていればサンドボックスが ready: true になることがあります。その場合、リクエストはベースラインに流れます。ルーティングが機能していないように見える場合は、/etc/hosts に <sandbox>-<mapping>-*.<namespace>.svc などの仮想ホストエントリーがあるか確認してください。

常にクラスターの URL にアクセスする

検証トラフィックは、ローカルプロセスではなくクラスターのサービス URL をターゲットにする必要があります。

curl -sS "http://<svc>.<namespace>.svc:<service-port>/<path>" \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>"

gRPC の場合：

grpcurl -plaintext \
  -H "baggage: sd-routing-key=<routing-key>" \
  -H "tracestate: sd-routing-key=<routing-key>" \
  -d '{"field":"value"}' \
  <svc>.<namespace>.svc:<service-port> package.Service/Method

キー名が sd-routing-key の baggage と tracestate は常に受け付けられます。clusterConfig.routing.customHeaders に追加のヘッダーが記載されている場合は、記載されたすべてのヘッダーにルーティングキーを値として設定してください。クエリパラメーターによるルーティングは、ヘッダーを設定できない場合にのみ使用してください。

signadot local proxy は、クラスターの依存先にマシンから到達できるかどうかのデバッグに役立ちます。ただし、localhost のプロキシ URL では、同じエンドツーエンドのルーティング経路を迂回するため、検証結果にはなりません。

ホップ間でキーを転送する

ルーティングキーがサンドボックス化された下流サービスに届くのは、すべてのホップでキーが伝播される場合に限られます。コードで明示的にコピーしない限り、未加工の HTTP/gRPC クライアント、カスタムプロキシハンドラー、非同期プロデューサーでは、キーが失われることがよくあります。新しいフォワーダーを追加する場合は、受信した baggage ヘッダーを送信リクエストにコピーするか、サービスで既に使用されている計装済みクライアントを使用してください。

シークレットと環境変数

ワークロードの仕様、ConfigMap、または Secret から環境変数を再構成する場合：

• コードを原因と決めつける前に、必要な値をすべて解決してください。DB アドレス、認証情報、機能フラグの不足は、最初のリクエストで 500 エラーとして現れることがよくあります。
• チャット、ログ、要約にシークレットの値を出力しないでください。<redacted> に置き換え、デコードした Secret の内容を貼り付けないでください。
• シークレットはプロセス環境に直接エクスポートすることを優先してください。環境ファイルが必要な場合は、制限付きのアクセス権で書き込み、後処理時に削除してください。
• サービスアドレスについては、コードを検索し、*_ADDR、*_HOST、*_URL などの設定参照や、言語固有のヘルパーを確認してください。Pod 内で機能するデフォルト値が、ローカルプロセスでは機能しないことがあります。

検証タイプの選択

• 統合テスト：言語標準のテストコマンドを .svc URL に対して実行し、テストクライアントまたは共通トランスポートでルーティングヘッダーを注入します。
• 既存の e2e スイート：リポジトリにある既存のコマンドと設定を使用します。ベース URL を .svc URL に設定し、フレームワークの HTTP レイヤーでルーティングヘッダーを付加します。
• アドホックなブラウザー自動化：ブラウザーから UI を操作し、変更をエンドツーエンドで検証します。利用可能なブラウザー自動化ツールを使用してください（一般的なのは Playwright です）。すべてのリクエストにルーティングヘッダーを注入し、ブラウザーの状態が保持される場合は、最初に以前のルートをクリアしてから UI の全経路を操作します。
• 既存のタグ付き Signadot プラン：selectionHint でタグを選び、サンドボックスに対して実行します。プランに関するその他のすべての事項（パラメーター、シークレット、ログ／出力、作成、タグ付け）については、signadot-plan スキルを参照してください。

選択したタイプを実行する前に、references/validation-types.md を読んでください。

失敗時のループ

検証に失敗しても、「検証に失敗しました」で止めないでください。次のループを続けてください。

1. 失敗内容を正確に引用します。ステータスコード、エラーメッセージ、スタックトレース、見つからない UI 要素、不正なフィールド、または空のブラウザー状態を示します。
2. 考えられる原因が、アプリのコード、サンドボックスの構成、不足している環境変数、古いプロセス、誤ったポート、ルーティングキーの伝播、またはローカルでも実行する必要がある変更済みの下流コンシューマーのいずれかを特定します。
3. 最小限の修正を適用し、影響を受けるプロセスを再ビルドして再起動し、同じルーティングキーとターゲット URL で同じ検証を再実行します。
4. ユーザーの判断なしでは決められない判断が修正に必要な場合に限り、いったん止めて確認します。たとえば、先に進めて修正するか、後方互換性のある変更にするか、意図的な破壊的変更を受け入れるかを選ぶ場合です。誤字、不足している環境変数、停止したプロセスの再起動など、機械的な修正について許可を求めず、そのまま適用してループを続けてください。

完了を宣言する前に、検証済みの動作を Signadot プランとして明文化すべきか検討してください。バグが再現可能で重要であり、他ではカバーされていない場合に実施します。誤字、インフラの不安定さ、探索的な確認、非決定的な失敗モードでは省略してください。サンドボックスはまだ起動しているため、新しいプランを一度実行すれば、タグ付け前にバグを検出する（または修正済みのコードで合格する）ことを確認できます。

クイック診断

症状	考えられる原因	最初に確認する項目
devbox から Envoy の 503 が返るが、ポッドは正常	Service のポートではなく、コンテナのポートにアクセスしている	Service オブジェクト／エンドポイントリゾルバー
レスポンスが以前のベースライン動作のように見える	ルーティングキーが失われた、または localhost のターゲットが使用された	ターゲット URL とすべてのルーティングヘッダー
サンドボックスの準備が完了し、トンネルも接続済みだが、ローカルプロセスにトラフィックが届かない	サンドボックスのマッピングポートが誤っている	/etc/hosts の仮想サンドボックスエントリー
ローカルプロセスは起動するが、最初の実際のリクエストで 500 が返る	環境変数が不足している、または依存関係のアドレスを解決できない	設定の参照箇所とエクスポートされた環境変数
操作後にブラウザーの本文やアクセシビリティツリーが空になる	SPA のランタイムエラー	ブラウザーのコンソールエラーと page.content().length
バックグラウンドプロセスが起動後すぐに終了する	シェルジョブが SIGHUP を受け取った、またはポートが競合している	プロセスの状態、リスナー、ログファイル
gRPC のダイヤルが DNS のタイムアウト付近で停止する	Go gRPC の SRV 検索の遅延	passthrough:/// ターゲットと接続の再利用

詳細な兆候と修正方法については、references/troubleshooting.md を参照してください。

最終レポート

以下を含めてください。

• 検証の種類と、使用したコマンド／ツールのパス
• クラスター、サンドボックス名、ルーティングキー、サービス URL
• ブラウザー／ユーザーの操作経路が該当する場合は、それも含めて成功した項目
• 停止したローカルプロセスの PID またはポート
• サンドボックスのティアダウンコマンド。実行せず、選択肢として提示してください。

signadot sandbox delete <sandbox-name>

ユーザーがローカルネットワークへの接続を実行した場合は、後で次のコマンドを実行できることを伝えてください。

signadot local disconnect