pulumi-upgrade-provider

Pulumi プロバイダーのアップグレード

概要

upgrade-provider --no-submit を実行し、既知の失敗を修正して、成功するまで再実行します。実行ループ中、ツールはブランチと生成されたコミットの状態を管理しますが、プッシュや GitHub の変更は行いません。成功後、ツールが出力した計画に従って提出する前に、ローカルの結果を確認して修正してください。

事前確認

1. アップグレード前のベースラインとして、既存の変更を記録します。

baseline_file="${TMPDIR:-/tmp}/upgrade-provider-$(basename "$PWD")-baseline.txt"
git status --short --untracked-files=all | tee "$baseline_file"

既存の変更がアップグレードを妨げることはありませんが、ツールは広範囲にステージングするため、生成されたコミットに含まれる場合があります。可能であれば、明らかに無関係な作業は別のブランチまたはワークツリーに分離し、ローカルのみのファイルを移動するか、ローカルの未追跡アーティファクトを .git/info/exclude に追加してください。それ以外の場合はそのまま進め、このベースラインを最終確認に引き継いでください。すべてのコントリビューターに対してそのパスを無視すべきでない限り、リポジトリの .gitignore ルールは追加しないでください。

2. 実行ログはリポジトリの外部に保存し、ツールがステージングできないようにします。

実行ループ

1. リポジトリのルートから実行します。

log_file="${TMPDIR:-/tmp}/upgrade-provider-$(basename "$PWD").log"
upgrade-provider $ORG/$REPO --repo-path . --no-submit > "$log_file" 2> /dev/null

再試行のたびに --no-submit を指定してください。

2. 完了するまで待ちます（最大 10 分かかる場合があります）。
3. ログ内で error: から始まる行を検索して、エラーを確認します。

if command -v rg >/dev/null 2>&1; then
  rg -n '^error: ' "$log_file" || true
else
  grep -n '^error: ' "$log_file" || true
fi

4. 正常終了した場合、まずアップグレードが不要だとツールが判断したかどうかを確認します。

if grep -Fq 'No actions needed' "$log_file"; then
  echo 'No actions needed'
fi

該当する場合は、プロバイダーがすでに最新であるか、要求されたターゲットがアップグレードではないことを報告し、正常に終了します。確認または提出するローカルのアップグレードはありません。

5. それ以外の場合は、取得した標準出力からローカル完了レポート全体を抽出して読みます。

awk '/^Upgrade completed locally;/{found=1} found' "$log_file"

これには、提案された PR の本文とメタデータ、確認コマンド、およびスキップされた提出アクションがすべて含まれます。

6. 失敗した場合は、このスキルの references/upgrade-provider-errors.md（リポジトリではなくスキルフォルダー内）を参照して修正し、--no-submit を指定して再実行します。アップストリームが Terraform Plugin SDKv2 から Plugin Framework に移行した場合は、フレームワークの変更だけをアーキテクチャ上の阻害要因とせず、同じリファレンスに記載された移行ガイドの案内に従ってください。無視された replace ディレクティブまたは unknown revision v0.0.0 が原因でアップストリームの go get が失敗した場合は、文書化された provider/go.mod の置換を適用した後、--target-version を指定して再実行します。元のメジャー／非メジャーの意図を維持し、実際にメジャーバージョンをアップグレードする場合にのみ --major を追加してください。
7. 修正にパッチの作成、修正、削除、またはリベースが必要な場合は、パッチのワークフローに upstream-patches スキルを使用します。中断されたパッチのワークフローは、再実行する前に確認してください。
8. コンフリクトを修正した場合は、正確な編集内容（ファイルパスと具体的な変更、または維持した意図）を報告します。
9. ツールが No actions needed またはローカル完了レポートと提案された PR 計画を出力するまで繰り返します。この実行でプッシュや GitHub の変更を行ってはいけません。以前の実行でブランチまたは PR がすでに作成されている場合があります。

中止して失敗を報告する場合

次のいずれかに該当する場合は、反復を中止して失敗を報告します。

1. コマンドが見つからない（終了コード 127）：upgrade-provider ツールが PATH にありません。
2. 同じエラーが 3 回発生：同じエラーを 3 回修正しようとしても解決できません。
3. 不明なエラーパターン：エラーが references/upgrade-provider-errors.md に記載されておらず、安全な修正方法を判断できません。
4. パッチの状態が不明確：すべてのパッチが適用され、対象のリベースが完了したことを証明できません。
5. 人間の判断が必要：複数の妥当な実装方法からの選択や、モジュール構成に関するアーキテクチャ上の判断など、ユーザーの入力が必要です。アップストリームの破壊的変更、非推奨化、またはフレームワークの移行だけを理由に中止する必要はありません。アップグレードの実装に未解決の選択肢がある場合にのみ中止してください。

中止する場合は、次の内容を報告します。

1. 発生したエラー。
2. 試した修正（ファイルパスと変更内容を含む）。
3. 人間の介入が必要な理由。
4. 進行中の作業があればその内容。

ローカルアップグレードをレビューする

ベースブランチ、作業ブランチ、提案された PR のタイトル／本文／メタデータ、およびスキップされた送信操作については、ツールの最終レポートを正とします。

1. まず、範囲を限定した概要を確認します。

default_branch=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name)
base_ref="origin/$default_branch"
git status --short --untracked-files=all
git log --oneline "$base_ref"..HEAD
git diff --shortstat "$base_ref"...HEAD
git diff --name-only "$base_ref"...HEAD | awk -F/ '{print $1}' | sort | uniq -c

プロバイダーのアップグレードでは、生成された SDK ファイルが数千個変更されることがあります。デフォルトではブランチの差分全体を出力しないでください。git diff "$base_ref"...HEAD -- <paths> コマンドでパスを限定し、ソース、設定、パッチ、スキーマ、および想定外のディレクトリを確認します。生成された SDK については、差分全体が必要でない限り、概要または対象を絞ったファイルを確認してください。

ブランチの最終状態をアップグレード前のベースラインと照合します。

baseline_file="${TMPDIR:-/tmp}/upgrade-provider-$(basename "$PWD")-baseline.txt"
[ ! -f "$baseline_file" ] || cat "$baseline_file"

ブランチに含まれるアップグレード前から存在していたパスはすべて、アップグレード PR に含めるべきか判断します。意図したパスは残し、無関係な作業は別のブランチ／ワークツリーに移すか、プッシュ前に未公開のアップグレード履歴から削除します。同じブランチに別のコミットを作成しても履歴が分離されるだけで、PR からそのパスが除外されるわけではありません。また、ツールがコミットした後では、ステージングを解除するだけでは不十分です。履歴を書き換えた場合でも、露出した認証情報は無効化してください。

2. 公開前に、生成ドキュメントの置換内容に未解決のプレースホルダーがないか必ず監査します。

if [ -f provider/replacements.json ]; then
  if command -v rg >/dev/null 2>&1; then
    rg -n '"new":.*TODO|TODO' provider/replacements.json || true
  else
    grep -En '"new":.*TODO|TODO' provider/replacements.json || true
  fi
fi

provider/replacements.json に TODO が見つかった場合：

• 送信前に解決すべき問題として扱います。置換値は生成ドキュメントに反映されます。
• 各 old／new の組を確認し、TODO を具体的な Pulumi 向けの表現（通常は Pulumi、this provider、または the provider）に置き換えます。
• リポジトリにテストがある場合は、対象を絞った検証を実行します。

cd provider && go test -v -run TestReplacementDoesNotIncludeTodos .

3. アップグレードでパッチが変更された場合は、適用されたコミットを確認してからチェックアウトモードを終了します。

./scripts/upstream.sh checkout
git -C upstream log --oneline pulumi/checkout-base..pulumi/patch-checkout
# Inspect relevant commits with git -C upstream show <sha>.
./scripts/upstream.sh check_in

コミットの SHA とタイトルを列挙し、それぞれの意図を要約して、動作の変更やリスクを指摘します。レビュー後は必ず check_in を実行してください。upstream を pulumi/patch-checkout に残すと、次の安全なツール実行が妨げられます。

4. 手動修正ごとに対象を絞った検証を実行し、対象を絞ったフォローアップコミットを追加します。
5. 送信前に、作業ツリーがクリーンであることを必ず確認します。

レビュー済みのアップグレードを送信する

ローカル完了レポートには、提案された PR のメタデータと、スキップされたすべての操作が記載されています。PR の作成だけでなく、該当するすべての操作を必ず再現してください。

1. 提案されたタイトル、本文、リリースラベル、レビュアー、担当者をそのまま維持します。リリースラベルを独自に判断、推測、変更しないでください。プロバイダーのアップグレードでは上流バージョンの移行に従うため、ラベルは個々の変更が破壊的かどうかについてのエージェントの評価ではなく、そのバージョン差分を表します。たとえば、上流が v0.9.0 から v0.10.0 に移行する場合、動作に破壊的変更が含まれていても、マイナーアップグレードのままです。upgrade-provider が出力したラベルをそのまま使用し、懸念点があればメタデータを変更せずにレビュアーへ伝えてください。また、上流の移行先が現在の上流メジャーバージョンを超える場合を除き、--major を追加しないでください。
2. 修正によってアップグレードがブロックされなくなった場合は、可能であれば送信前に次のセクションを提案された本文に追加します。

---

### Fixes applied to unblock upgrade

- <list concrete unblocker edits here, with file paths and intent>

3. レビュー後にのみプッシュします。ツールは無条件の force-push を報告しますが、ユーザーが新しいリモート作業の上書きを明示的に承認しない限り、手動送信では、より安全な lease 保護付きの方法を意図的に使用します。

branch=$(git branch --show-current)
git push --set-upstream origin "$branch" --force-with-lease

4. レポートの説明に従って、gh を使って PR を作成または更新します。
5. 指示がある場合は、記載されたアップグレード関連の課題を PR の担当者に割り当てます。
6. ブリッジのアップグレードでは、記載された置き換え対象のブリッジ PR をクローズし、置き換え後の PR の URL をコメントします。
7. 最終的な PR の URL を取得して報告します。

gh pr view --json url --jq .url || gh pr list --head "$(git branch --show-current)" --json url --jq '.[0].url'

修正セクションを送信前に含めなかった場合は、既存の本文を置き換えずに追加します。

repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
pr_number=$(gh pr view --json number --jq .number)
gh pr view --json body --jq .body > /tmp/pr_body.txt

cat <<'EOF' >> /tmp/pr_body.txt

---

### Fixes applied to unblock upgrade

- <list concrete unblocker edits here, with file paths and intent>
EOF

gh api -X PATCH "repos/$repo/pulls/$pr_number" --raw-field body="$(cat /tmp/pr_body.txt)"

GraphQL のプロジェクトカードに関するエラーを避けるため、gh pr edit ではなく REST（gh api）を使用します。既存の本文は維持し、追記のみ行います。

注意事項

• 古い git バージョンでは、git rebase --continue --no-edit はサポートされていません。git rebase --continue を使い、既存のコミットメッセージをそのまま使用します。
• git rebase --continue でエディターのプロンプトを表示しないようにするには、GIT_EDITOR=true（または GIT_EDITOR=:）を指定して実行します。

ガードレール

• upgrade-provider の実行ループ中に、手動でコミット、プッシュ、ブランチ作成をしないでください。
• --no-submit が成功した後は、対象を絞った修正コミットと手動での送信が許可されます。
• 中断されたパッチ作業を意図的に破棄する場合を除き、./scripts/upstream.sh init -f は使用しないでください。これは破壊的な操作です。
• 送信前に、チェックアウト内に upstream を残したり、Git 操作を実行中のままにしたりしないでください。
• 変更を stash しないでください。クリーンなワークツリーを使うか、無関係な成果物を削除してください。

参考資料

• 中断されたパッチの状態、パッチの競合、SDKv2 から Plugin Framework への移行、無視対象の upstream の置き換え、ベンダー化された upstream 依存関係、.NET の重複ファイル、新しいモジュールのマッピングに関する修正には、このスキルの references/upgrade-provider-errors.md（リポジトリ内ではなく、スキルフォルダー内にあります）を参照してください。