infrahub-planning-upgrades

Infrahub アップグレードパスプランナー

概要

実行中の Infrahub バージョンからターゲットバージョンまでの経路を、マイナーバージョンごとに 1 ステップとして記載した UPGRADE_PLAN.md を生成します。その範囲内のすべての破壊的変更を、このリポジトリと、接続可能な場合はこのインスタンスに照らして確認します。

このプランはアップグレード方法を説明するものであり、アップグレードを実行するものではありません。 アップグレード、スキーマの読み込み、ブランチへの書き込みは一切実行せず、アップグレードコマンドをユーザーに提示することもありません。読み取り専用の調査を実行し、その結果を表示する場合があります。 ユーザーのデプロイ方法（Docker Compose、Helm、Enterprise、Community）によって正確なコマンドが決まり、それらは該当するデプロイ方法のアップグレードガイドで管理されます。

エディションではなく、バージョンを対象とします。 このプランが扱うのは、同じエディション内での後続バージョンへの移行です。Community と Enterprise の間の切り替えは、どちらの方向であってもバージョンアップグレードではなく、リリースノートでも扱われていません。その旨を伝え、計画を立てる代わりに https://docs.infrahub.app/overview/community-vs-enterprise#migration-path を案内してください。バージョンアップグレードとエディション変更の両方を含む依頼の場合は、バージョンアップグレードのみを計画し、エディション変更は対象外であることを明記します。

Write は UPGRADE_PLAN.md のみを対象として許可されています。Bash は gh を使ったリリースノートの読み取りと、読み取り専用の調査に対して許可されています。

プロジェクトのコンテキスト

このスキルはフォークされたコンテキストで実行されるため、親の会話を参照できません。そのため、ユーザーの依頼は引数としてそのまま渡されます。内容はバージョンと、貼り付けられたスキーマ、デプロイ方法（手順 6 で、それに基づいてアップグレードガイドを選択します）、エディション、「とにかく実行して」といった要望など、プランに必要なすべての情報です。 例： /infrahub:planning-upgrades We run 1.9.2 on Docker Compose, Community, and want 1.10.0. Here is our schema: ...

ターゲットが指定されていない場合は、ユーザーに尋ねます。現在のバージョンが指定されていない場合は、infrahubctl info の出力（Infrahub Version:）から読み取ります。サーバーに接続できない場合は、ユーザーに尋ねます。

ワークフロー

1. 始点・終点とアップグレードの経由箇所を決めます。 Infrahub がサポートするアップグレードは、直前のマイナー バージョン（N-1）からのみです。そのため、1.6.3 から 1.9.0 へのアップグレードは 3 つの経由箇所になります。 1.6 から 1.7、1.7 から 1.8、1.8 から 1.9 です。ユーザーが 「一度に」と希望しても、マイナーバージョンをまたぐ アップグレードは計画しないでください。パッチバージョンは異なります。1 回のアップグレードで 保留中のすべてのマイグレーションが順に適用されるため、 1.9.1 から 1.9.6 は 1 つの経由箇所になります。また、マイナーバージョン間の移行は 直前のマイナーバージョンの任意のパッチバージョンから開始できます（1.9.1 から 1.10.0）。現在のマイナーバージョン内で 先にパッチバージョンをまとめてアップグレードする（1.10.8 から 1.10.10）ことは、 独立したセクションとして行っても構いませんが、必須ではありません。
2. パッチバージョンも含めて対象範囲内のすべてのリリースを列挙し、それぞれのリリースノートを読みます。 何かを取得する前に、 rules/sources-enumerate-every-hop.md を読んでください。破壊的変更は パッチリリースにも含まれますが、それを示す機械可読なフラグはありません。
3. リポジトリを調査します。 スキーマ YAML、 .infrahub.yml、GraphQL クエリ、Python の チェック、ジェネレーター、トランスフォームを確認します。インスタンスに接続できる場合は、 infrahubctl info （connectivity-server-check） で確認し、MCP の読み取りツールを使ってライブデータを読み取ります （mcp-tools）。 インスタンスの確認は任意ですが、リポジトリの確認は必須です。
4. すべての指摘事項に判定を示し、根拠を付けます。 Affected 列と Evidence 列を埋める前に、 rules/impact-verdict-needs-evidence.md を読んでください。
5. 読み取り専用で調査します。 コマンドを実行または表示する前に、 rules/safety-read-only-probes.md を読んでください。ユーザーからアップグレードの実行を求められた場合も、もう一度読んでください。
6. 以下の形式で UPGRADE_PLAN.md を作成します。 各経由箇所の手順は文章で記述します。バックアップを取り、 before の指摘事項を解消し、アップグレードガイドに従って対象バージョンへアップグレードし、 during と after の指摘事項を解消します。ガイドの内容を書き写すのではなくリンクし、 エディションが分かる場合は該当するエディションのページを選びます。
   • 概要：https://docs.infrahub.app/deploy-manage/maintain-upgrade/upgrade/overview
   • Community：https://docs.infrahub.app/deploy-manage/maintain-upgrade/upgrade/community
   • Enterprise：https://docs.infrahub.app/deploy-manage/maintain-upgrade/upgrade/enterprise

計画の形式

経由箇所ごとに ## セクションを 1 つ設け、昇順に並べます。 見出しには経由箇所の 2 つのバージョンを記載します（## 1.9 -> 1.10）。 各経由箇所には、次の 9 列をこの順序で並べた指摘事項の表を 1 つ記載します。

変更	リリース	種類	重大度	時期	影響対象	根拠	対応	ソース

列	値
Release	1 つのバージョン（X.Y.Z）。範囲は指定しません
Kind	breaking または preparation
Severity	critical、warning、または info
When	経由箇所の before、during、または after
Affected	yes、no、または unknown

各値の意味と具体例は reference.md にあります。最初の行を書く前に読んでください。

ルールのカテゴリー

カテゴリー	プレフィックス	ルール
ソース	sources-	sources-enumerate-every-hop
影響	impact-	impact-verdict-needs-evidence
安全性	safety-	safety-read-only-probes

参考資料

• reference.md：列の意味と計画の例です。手順 6 で読んでください。
• rules/_sections.md：ルールの一覧です。