provider-upgrade

Upgrading Pulumi Providers

The Principle

A provider upgrade is a translation, not a change request.

The user's infrastructure intent hasn't changed - they still want the same bucket, the same function, the same cluster. What changed is how the provider's API expresses that intent. Your job is to translate their existing code into the new API so that Pulumi sees no difference between what the code says and what already exists.

There are four layers to keep in mind:

1. User intent - what the user wants in the cloud (unchanged during an upgrade)
2. Code - how the program expresses that intent using the provider API (may need updating)
3. Pulumi state - Pulumi's stored representation of what exists (may need reconciliation)
4. Real cloud - the actual infrastructure (should not change during an upgrade)

During an upgrade, layers 2 and 3 may need to change so that they continue to correctly represent the unchanged layers 1 and 4.

A correct translation produces zero diff. The Pulumi engine doesn't have a concept of "upgrade" - it just compares goal state (your code) against actual state (the state file) and reconciles. If the translation is correct, those two states match and nothing happens. If you see a diff, either your translation is wrong, or something beyond a code change is needed (import, alias, manual step). In all cases, the diff is a problem to solve, not a consequence to accept.

The Core Loop

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. Bump the provider dependency
2. Preview with required CLI flags
3. Diff Checkpoint - categorize every non-same resource (see next section)
4. Fix Category A - code changes that didn't produce same
5. Investigate Category B - diffs on resources you didn't change
6. Repeat until clean or remaining diffs are fully investigated
7. Create PR with upgrade summary