planetscale-webhook-automation-recommendations

Webhook 自動化の推奨事項

目的

人に通知し、安全な自動化を開始する PlanetScale Webhook を確認し、推奨します。承認なしに Webhook を作成または更新しないでください。

Webhook 設計の原則

Webhook は自動化を開始できますが、既定では、自動化の成果物は推奨事項、Issue、ブランチ、またはプルリクエストでなければなりません。明示的な人間の承認なしに、本番データベースや本番アプリケーションの動作を直接変更してはなりません。

評価するイベント

一般および Postgres

• branch.anomaly：新しい Insights の異常。
• branch.out_of_memory：Postgres のメモリ不足イベント。
• branch.primary_promoted：プライマリのフェイルオーバー／昇格。
• branch.ready：ブランチが作成され、使用可能になった状態。
• branch.sleeping：ブランチがスリープ状態。
• branch.start_maintenance：メンテナンスの開始。
• cluster.storage：ストレージのしきい値到達または増加イベント。
• database.access_request：アクセスリクエスト。
• branch.schema_recommendation：利用可能な場合のスキーマ推奨イベント。
• webhook.test：テストイベント。

Vitess デプロイのライフサイクル

• deploy_request.opened
• deploy_request.queued
• deploy_request.in_progress
• deploy_request.pending_cutover
• deploy_request.schema_applied
• deploy_request.errored
• deploy_request.reverted
• deploy_request.closed
• keyspace.storage

推奨する振り分け先

人へのアラート通知

以下をインシデント対応または運用チャンネルに送信します。

• branch.anomaly
• branch.out_of_memory
• branch.primary_promoted
• branch.start_maintenance
• cluster.storage
• keyspace.storage
• deploy_request.errored
• deploy_request.reverted

エンジニアリングへの通知

以下を Slack、Linear/Jira、またはデプロイチャンネルに送信します。

• deploy_request.opened
• deploy_request.queued
• deploy_request.in_progress
• deploy_request.pending_cutover
• deploy_request.schema_applied
• deploy_request.closed
• branch.schema_recommendation

エージェントの受付キュー

以下をエージェントが安全に処理できるワークフローに送信します。

• branch.anomaly
• branch.schema_recommendation
• deploy_request.errored
• cluster.storage
• keyspace.storage

承認なしでエージェントが出力できる内容は、次のとおりです。

• トリアージの概要、推定原因、関連する Insights／クエリパターン。
• 推奨するスキーマ、コード、Traffic Control、または運用上の変更。
• アプリケーションコードに対するプルリクエスト。
• DDL またはマイグレーションを適用した開発ブランチ。
• レビューで保護されたブランチへのデプロイリクエストの作成。
• Issue またはチケット。

エージェントの出力だけでレビューゲートを通過してはなりません。本番デプロイ、PR のマージ、Traffic Control の適用、認証情報のローテーション、ネットワークの変更は行わないでください。これらには、人間による操作、または ../planetscale-autonomous-execution-mode/SKILL.md に基づく常設の承認が必要です。

Webhook 受信側の要件

次の要件を満たす受信側のみを推奨します。

• HTTPS エンドポイントであること。
• 迅速に 2xx を応答し、負荷の高い処理は非同期でキューに追加すること。
• リダイレクトへの追従に依存しないこと。
• PlanetScale の Webhook 署名ヘッダーと Webhook シークレットを使って署名を検証すること。
• イベント ID、またはタイムスタンプとリソースの組み合わせで冪等性を確保すること。
• デッドレターキュー、または再試行に安全なログ記録を備えること。
• 人が読める監査証跡を残すこと。
• 責任者とエスカレーション経路が明確であること。
• シークレットのローテーション手順を備えること。

推奨する自動化フロー

異常から PR へのフロー

1. branch.anomaly を受信します。
2. 署名を検証します。
3. ジョブをキューに追加します。
4. 異常の詳細と関連する Insights のクエリパターンを取得します。
5. SQLCommenter タグとリポジトリ検索を使ってコードパスを特定します。
6. スキーマ、コード、Traffic Control、または不明に分類します。
7. レポートと、必要に応じて PR を生成します。
8. データベースに影響する作業について、人間に承認を求めます。

スキーマ推奨からブランチ／デプロイまでのフロー

Vitess の場合：

1. branch.schema_recommendation を受信します。
2. 推奨事項の詳細を取得します。
3. DDL を開発ブランチに適用します。
4. フィンガープリント、メトリクス、想定される効果を添えてプルリクエストを作成します。
5. デプロイリクエストを作成します。DR と PR を合わせてレビュー可能な単位とし、作成に承認は不要です。
6. 人による承認後にデプロイするか、このデプロイクラスを許可リストに登録した継続的な認可のもとで自律的に実行します（../planetscale-autonomous-execution-mode/SKILL.md）。

Postgres の場合：

1. branch.schema_recommendation を受信します。
2. 推奨事項の詳細を取得します。
3. DDL をアプリケーションのマイグレーションに変換します。
4. 本番環境以外のブランチでテストし、結果を PR に記録します。
5. PR を作成します。
6. デプロイパイプライン経由でマージ時に本番環境へ適用するか、パイプラインがない場合は明示的な承認後に適用します。

Vitess のデプロイリクエストのライフサイクルフロー

• 作成時に通知します。
• オーナーと関連付けられたアプリケーション PR を検証します。
• キュー登録時または処理中にアラートを送信します。
• エラー発生時または取り消し時には、強いアラートを送信します。
• 切り替え待ちを通知し、ゲート付きデプロイではオーナーの確認を必須とします。
• スキーマの適用を記録し、アプリケーションのデプロイと関連付けます。

禁止すべきアンチパターン

次の方法を推奨しないでください。

• Webhook が PR／デプロイリクエストのワークフローを経由せず、本番環境で DDL を直接実行すること。（ブランチ、PR、デプロイリクエストを通じて DDL を適用するのがサポート対象の方法であり、アンチパターンではありません。）
• Webhook がレビュー可能な成果物を用意せず、スキーマ推奨を本番環境に直接適用すること。
• Webhook が Traffic Control を直接適用すること。
• Webhook が IP 制限を直接変更すること。
• Webhook が認証情報を直接ローテーションすること。
• Webhook がシークレットやリテラルを含む生の SQL を公開 Slack チャンネルに投稿すること。
• Webhook の受信側が署名検証を無視すること。
• Webhook の受信側が 2xx を返す前に、時間のかかる処理を行うこと。

出力

次の内容を返します。

• 既存の Webhook の一覧。
• 推奨されるサブスクリプションのうち不足しているもの。
• 配信先の品質レビュー。
• 署名検証の状況。
• 自動化の機会。
• 自動化に伴う安全でないリスク。
• 承認が必要な Webhook の変更案。

次の文で終えてください。

「Webhook または自動化エンドポイントは、作成、更新、削除されていません。」