provider-upgrade

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

原則

プロバイダーのアップグレードは翻訳であり、変更リクエストではありません。

ユーザーのインフラに対する意図は変わっていません。同じバケット、同じ関数、同じクラスターを引き続き求めています。変わったのは、プロバイダーの API でその意図を表現する方法です。あなたの役割は、既存のコードを新しい API に翻訳し、コードの記述と既存のリソースとの間に違いがないと Pulumi が認識できるようにすることです。

次の 4 つのレイヤーを念頭に置いてください。

1. ユーザーの意図 - ユーザーがクラウド上で何を望んでいるか（アップグレード中も変わりません）
2. コード - プロバイダー API を使ってプログラムがその意図をどのように表現するか（更新が必要な場合があります）
3. Pulumi の状態 - 既存のリソースを Pulumi がどのように記録しているか（調整が必要な場合があります）
4. 実際のクラウド - 実際のインフラ（アップグレード中に変更されるべきではありません）

アップグレード中、変わらないレイヤー 1 と 4 を引き続き正しく表現するために、レイヤー 2 と 3 の変更が必要になる場合があります。

正しく翻訳できれば、差分はゼロになります。Pulumi エンジンには「アップグレード」という概念はありません。目標の状態（コード）と実際の状態（状態ファイル）を比較して、整合させるだけです。翻訳が正しければ、両方の状態が一致し、何も起こりません。差分があれば、翻訳が誤っているか、コード変更以外の対応（インポート、エイリアス、手動の手順）が必要です。いずれの場合も、差分は受け入れるべき結果ではなく、解決すべき問題です。

基本のループ

flowchart TD
    A[Bump version] --> B[Run preview with env vars]
    B --> C{Clean?}
    C -->|Yes| D[Create PR]
    C -->|No| E[Diff Checkpoint: categorize every diff]
    E --> F{Any Category A?}
    F -->|Yes| G[Fix wrong translations]
    G --> B
    F -->|No| H{Any Category B?}
    H -->|Yes| I[Investigate with toolbox]
    I --> J[Fix or document]
    J --> B
    H -->|No| D

1. プロバイダーの依存関係を更新します
2. 必要な CLI フラグを指定してプレビューします
3. 差分チェックポイント - same ではないすべてのリソースを分類します（次のセクションを参照）
4. カテゴリー A を修正 - same にならなかったコード変更
5. カテゴリー B を調査 - 変更していないリソースの差分
6. クリーンになるか、残った差分をすべて調査し終えるまで繰り返します
7. アップグレードの概要を含めて PR を作成します

---

差分チェックポイント

ここが最も重要なセクションです。プレビューのたびに必ず実行してください。

same ではないリソースごとに、次の質問に答えてください。 「コードの変更によって、このリソースに直接的または間接的な影響がありましたか？」

「直接的」とは、リソースブロック自体を編集したことを意味します。「間接的」とは、共有変数、別のリソースの出力、ヘルパー関数、デフォルト値、またはこのリソースが依存するリソースなど、このリソースに値を渡すものを変更したことを意味します。変更によって Pulumi がこのリソースに対して計算する内容が変わる可能性がある場合は、カテゴリー A です。

該当するカテゴリーに従ってください。

カテゴリ A：このリソースのコードを変更した

コードの変更では、同じ意図を新しい API に反映する必要がありました。リソースに same と表示されていれば、変換は正しいです。それ以外が表示されていれば、変換は誤りです。「コードを変更したのだから差分が出るのは当然」ということではありません。意味的に同等な変更であれば、差分は出ません。

既存のリソースを変更したところ、update と表示された場合：

名前の変更、再構成、値の調整によって、構文だけでなく意味も変わっています。古いコードと新しいコードが同じ目標状態にコンパイルされるなら、リソースには same と表示されます。update は、そうではないことを意味します。

自分に問いかけてください。「この名前の変更が本当に同等なら、リソースには same と表示されるはずです。そうなっていません。古いコードと新しいコードで、意味的に何が異なるのでしょうか？」

よくある原因：新しいプロパティ名が、内部では別のフィールドに対応している。値の形状が変わり、変換によって情報が失われた、または追加された。新しいバージョンでデフォルト値が変わり、以前の値を明示的に設定する必要がある。新しいプロバイダーバージョンが以前は追跡していなかったフィールドを追跡するようになり、差分に追加のプロパティが表示されるようになった（現在の状態と一致させるには、これらを明示的に設定する必要があります）。

変更していないプロパティ（新しいフィールドの追加、型の正規化（string->number）、追加のデフォルト値など）が更新に含まれている場合、プロバイダーが追跡対象を変更しています。ただし、差分があるなら、pulumi up はその値をクラウド API に送信します。何も起きないと思い込まないでください。変更されたプロパティを一つずつ調査してください。

新しいリソースブロックを追加したところ、create と表示された場合：

アップグレード中に新しいリソースブロックが追加された場合、通常、それはクラウド上にすでに存在するインフラストラクチャを表しています。以前のプロバイダーは別のリソースの一部として暗黙的に管理していましたが、新しいプロバイダーでは明示的なリソースが必要になっています。しかし、クラウドオブジェクトはすでに存在します。Pulumi は新しいインフラストラクチャを作成しようとしますが、それは望んでいる動作ではありません。

解決策は create ではなく import です。既存のクラウドリソースを Pulumi に取り込ませてください。

自分に問いかけてください。「この新しいリソースが表しているクラウドオブジェクトは何でしょうか？すでに存在していますか？アップグレード前はどのように管理されていましたか？」

// Wrong - creates duplicate infrastructure
const stage = new aws.apigateway.Stage("prodStage", { ... });

// Right - adopts the existing resource
const stage = new aws.apigateway.Stage("prodStage", { ... }, {
    import: "<rest-api-id>/prod",  // import ID format varies by resource type
});

リソースブロックを削除したところ、delete と表示された場合：

プレビューに delete と表示されている場合、pulumi up はプロバイダーの Delete API を呼び出し、このクラウドリソースを破棄するか、設定を解除します。これは実際の破棄であり、単なる状態のクリーンアップではありません。クラウドインフラストラクチャはまだ存在しており、ほぼ間違いなく引き続き必要です。

これは pulumi state delete とは異なります。pulumi state delete はプロバイダーの API を呼び出さずに、Pulumi の追跡対象からリソースを削除します。新しいプロバイダーバージョンでリソースタイプが削除された場合、正しい手順は次のとおりです。

1. pulumi state delete '<urn>' — 手動の手順で、追跡対象からのみ削除します
2. 代替リソースがある場合は、インポートを使って追加し、新しいタイプのリソースとしてクラウドの状態を取り込みます
3. プレビューで確認します

プレビューに delete があるまま、PR の作成に進まないでください。pulumi up によって実行される削除は、実際のインフラストラクチャを破棄します。リソースを状態から削除する必要がある場合は、ユーザー向けの手動手順として記載してください。

自分に問いかけてください。「このリソースはどのクラウドインフラストラクチャを管理していますか？pulumi up でこの削除が実行された場合、何が破棄されるか、または設定解除されるでしょうか？」

カテゴリ B：このリソースのコードを変更していません

この差分は、コード変更によるものではありません。プロバイダーのバージョン変更そのものに起因します。デフォルト値の違い、状態表現の変更、または動作の違いが原因です。 references/diagnostic-toolbox.md を読み、調査してください。

このような差分には、次のものがあります。

• コードで修正可能 - 変更されたデフォルト値を明示的に設定する、エイリアスを追加する
• ドキュメントに記載された実質的な変更なし - アップグレードガイドに、実際のインフラに影響を与えずに pulumi up で解消されると記載されています。この分類には、アップグレードガイドまたはプロバイダーのドキュメントからの引用が必須です。「実質的な変更なしに見える」というあなた自身の判断だけでは不十分です。ユーザーは、実際のインフラ変更と見かけ上の差異を区別することをあなたに任せており、判断を誤ればクラウド環境に予期しない変更が生じます。
• 手動の手順が必要 - 状態からの削除と再インポートを行い、その手順をユーザーに説明する
• 不明 - 調査結果をユーザーに提示し、指示を求める

分類した後

完全性の確認： プレビューで same 以外の状態が示されているリソースはすべて、チェックポイントに含める必要があります。[diff: ...] 注釈が付いているリソースも、明示的な作成／更新／削除マーカーがなくても対象です。リストに記載していない場合、チェックポイントは不完全です。不足しているリソースに戻って分類してください。

受け入れる差分の根拠： 差分を「問題なし」として受け入れる場合は、カテゴリ A でもカテゴリ B でも根拠が必要です。「API では同等として扱われると思う」や「状態の調整のように見える」は根拠になりません。根拠として認められるものは、アップグレードガイドへの記載、確認できる GitHub issue、または動作を説明するプロバイダーのドキュメントです。根拠を見つけられない場合は、差分を修正するか、ユーザーに報告してください。

順序： カテゴリ B を調査する前に、カテゴリ A の問題をすべて修正してください。コードの修正によってプレビュー結果が変わるため、先にカテゴリ B の差分を調査すると手間が無駄になります。まず自分の誤りを修正し、再度プレビューしてから、残った差分を確認してください。

最終プレビューに delete や replace を残さないでください。 PR を作成する段階で delete または replace が残っている場合は、作業を止めてください。delete は pulumi up によってクラウドインフラが破棄されることを意味します。replace は破棄して再作成することを意味します。これらを「残った差分」として許容することはできません。先に（コードの修正、エイリアス、またはドキュメントに記載された手動の手順により）解消する必要があります。

---

はじめに

必須の CLI フラグ

プレビューを実行するときは、次のフラグを使用してください。これらを指定しないと、実際には存在しない差分（タグの誤った削除、リージョンの追加）が表示されることがあります。これらのフラグなしで実行されたプレビューを解釈しないでください。

pulumi preview --refresh --run-program

• --refresh は、差分を比較する前に実際のクラウド状態を更新します。
• --run-program は、更新中に Pulumi プログラムを実行します。

非推奨機能を追わない

非推奨でも引き続き動作するものは、そのままにしてください。代替機能への移行は、メリットがないままリスクを招きます。非推奨の警告は許容できますが、差分は許容できません。

// BAD: migrating deprecated-but-working properties introduces risk
new aws.s3.Bucket('bucket');
new aws.s3.BucketLogging('bucketLogging', {...});  // unnecessary migration

// GOOD: fix only the actual error, leave working code alone
new aws.s3.Bucket('bucket', {
  logging: {...},  // "loggings" renamed to "logging" - real breaking change
  website: {...},  // deprecated but works - don't touch
});

変更は必要最小限にする

変更する行はすべて、リグレッションを引き起こす可能性があります。動作する最小限の変更を優先してください。

pulumi up を実行しない

プロバイダーのアップグレードではソースコードが変更されるため、デプロイ前にコードレビューが必要です。 PR → レビュー → マージ → CI/CD でデプロイ。

---

はじめに

1. バージョン情報を取得する

ユーザーの依頼、Pulumi Registry、パッケージマネージャーのメタデータ、またはリポジトリに既存の依存関係の制約から、対象バージョンを特定してください。

ユーザーが対象バージョンを指定していない場合は、最新の安定バージョンをデフォルトとして使用してください。 影響を受けるスタックやプロジェクトをユーザーが尋ねている場合は、変更を加える前に、スキル package-usage または利用可能な最適なパッケージインベントリーツールを使用してください。

1a. プロバイダー固有のリファレンスを確認する

メジャーバージョンによっては、誤った順序で修正すると実環境のリソースが破壊される、後方互換性のない変更が含まれていることがあります。プレビューだけでは、こうした変更は明らかになりません。references/ にこのプロバイダーと対象メジャーバージョンに対応するファイル（たとえば、pulumi-gcp を 10.x に更新する場合の gcp-v10.md）がある場合は、今すぐ読み、ステップ 2 の前にその「Before the bump」セクションに従ってください。このアップグレードでは、ステップ 3 の「後方互換性のない変更を最初に調査しない」というルールより、こちらを優先します。

2. 依存関係を更新する

• TypeScript/JavaScript：npm install @pulumi/{provider}@^{version} または yarn add @pulumi/{provider}@^{version}
• Python：pyproject.toml または requirements.txt の pulumi_{provider}>={version}（ハイフンではなくアンダースコア）を更新してから、インストールします
• Go：go get github.com/pulumi/pulumi-{provider}/sdk/v{major}@latest を実行し、すべてのインポートパス（例：v6 -> v7）を更新してから、go mod tidy を実行します
• .NET：dotnet add package Pulumi.{Provider} --version {version}
• Java：pom.xml または build.gradle の依存関係バージョンを更新します
• YAML：リソースオプションまたはプロバイダー設定のプロバイダーバージョンを更新します。例については https://www.pulumi.com/docs/iac/languages-sdks/yaml/yaml-language-reference/#providers-and-provider-versions を参照してください。

インストール後、ロックファイル（package-lock.json、go.sum など）で実際にインストールされたバージョンを確認してください。schema-tools で比較する際は、この正確なバージョンを使用します。

3. プレビューを実行する

依存関係を更新したら、すぐに pulumi preview --refresh --run-program を実行してください。後方互換性のない変更を最初に調査しないでください。特にマイナーバージョンでは、アップグレードがそのまま成功することがよくあります。

プレビューに問題がなく（プロバイダーバージョンの更新のみであれば）、PR を作成します。

---

プレビューの進捗

プレビューは最初のエラーで失敗し、ほかのエラーが隠れてしまうことがあります。エラーを 1 つ修正すると、新たなエラーが明らかになることもあります。これは正常な進捗であり、修正によって状況が悪化しているわけではありません。

• 新しいエラー、または異なるエラー -> 進捗です。続行してください
• エラーの数が減った -> 進捗です。続行してください
• 同じエラーが残る -> 修正が機能していません。別の方法を試してください
• エラーはないが差分がある -> 差分チェックポイントを実行してください

---

アップグレードの概要

プレビューに問題がなくなったら（または可能な範囲で問題が解消されたら）、次の概要を提示します。

## Upgrade Summary: {provider} v{current} -> v{target}

### Code Changes
| File | Change | Why it preserves intent |
|------|--------|------------------------|
| package.json | Version bump | - |
| index.ts:15 | loggings -> logging | Property renamed, same underlying field |

### Preview Result
All resources show `same` except provider version bump.
{Or: N resources show diffs - see below}

### Remaining Diffs (if any)
| Resource | Operation | What happens on `pulumi up` | Risk | Source |
|----------|-----------|---------------------------|------|--------|
| aws:s3:Bucket (myBucket) | update (-tags) | No-op, state reconciles | None | AWS v7 guide section 3.2 |

Every remaining diff MUST cite an authoritative source (upgrade guide, provider docs,
upstream GitHub issue). "I believe this is expected" is not a source.

### Manual Steps Required (if any)
1. `pulumi state delete '<urn>'` - remove old type binding
2. `pulumi import <type> <name> <id>` - adopt under new type
3. `pulumi preview --refresh --run-program` - verify clean

### Deprecation Warnings (no action taken)
- List deprecated-but-working code left intentionally

プレビューに問題がない場合（または残りの差分がすべて、出典を示したうえで何もしない変更として記録されている場合）は、プルリクエストを作成します。未解決の差分が残っている場合は、例外レポートとして概要を提示し、プルリクエストを作成する前に、どのように進めるかユーザーに確認してください。

---

リファレンス

• references/diagnostic-toolbox.md - アップグレードガイド、schema-tools（インストール、実行、出力の解釈）、スタック状態の検査、SDK 型、GitHub の課題。カテゴリー B の差分を調査する際に読んでください。
• references/gcp-v10.md - pulumi-gcp v10 の後方互換性のない変更すべてについて、状態スキャン、grep パターン、修正の順序、リスクを記載しています。pulumi-gcp を 10.x に更新する前に読んでください（ステップ 1a を参照）。