Pulumi Upgrade Provider

Pulumi Upgrade Provider

Overview

Run upgrade-provider, fix known failures, and rerun until success. Keep git operations read-only in the repo; the tool owns branch/commit/PR state.

Run Loop

1. Create output directory:

mkdir -p .pulumi

2. Run from repo root:

upgrade-provider $ORG/$REPO --repo-path . > .pulumi/upgrade-provider-stdout.txt 2> /dev/null

3. Wait for completion (can take up to 10 minutes). 4. Check for errors by scanning .pulumi/upgrade-provider-stdout.txt lines starting with error: . 5. If failed, fix using this skill's references/upgrade-provider-errors.md (from the skill folder, not the repo), then rerun. For upstream go get failures involving ignored replace directives or unknown revision v0.0.0, rerun with --target-version after applying the documented provider/go.mod replacements; preserve the original major/non-major intent and add --major only for actual major version upgrades. 6. If a fix requires creating/amending/removing/rebasing patches, use the upstream-patches skill for the patch workflow. 7. If you fixed a conflict, report exact edits (file paths + concrete changes or preserved intent). 8. If the upgrade changed patches, run ./scripts/upstream.sh checkout and review applied upstream commits:

• List commit SHAs/titles from upstream.
• Summarize the intent of each commit in plain language.
• Call out any behavioral changes or risks.

9. On success, proceed to Post-run Tasks.

When to Stop and Report Failure

Stop iterating and report failure if any of these conditions are met:

1. Command not found (exit code 127): The upgrade-provider tool is not in PATH. 2. Same error 3 times: You've attempted to fix the same error 3 times without success. 3. Unknown error pattern: The error is not covered in references/upgrade-provider-errors.md and you cannot determine a safe fix. 4. Requires human judgment: The fix needs user input, such as:

• Choosing between multiple valid approaches
• Breaking changes that affect public API
• Deprecation strategies
• Architectural decisions about module organization

When stopping, report: 1. The error(s) encountered. 2. What fixes were attempted (with file paths and changes). 3. Why human intervention is needed. 4. Any partial progress.

Post-run Tasks

The tool creates a PR on successful upgrade.

1. MUST fetch the PR URL for the current branch using read-only commands:

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

2. MUST audit generated doc replacements for unresolved placeholders:

if [ -f provider/replacements.json ]; then
  rg -n '"new":.*TODO|TODO' provider/replacements.json || true
fi

If any TODO is found in provider/replacements.json:

• Treat it as a post-upgrade blocker; replacement values render into generated docs.
• Inspect each old/new pair and replace TODO with concrete Pulumi-facing wording, usually Pulumi, this provider, or the provider.
• Run focused validation if the repo has the test:

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

After the upgrade-provider tool has created the PR, fix these placeholders as normal follow-up work.

3. MUST append a "Fixes applied to unblock upgrade" section to the existing PR body if any fixes were applied (do not overwrite):

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)"

Use REST (gh api) instead of gh pr edit to avoid GraphQL project-card errors. Keep existing body content; only append.

Notes

• git rebase --continue --no-edit is not supported in older git versions. Use git rebase --continue and accept the existing commit message.
• To avoid the editor prompt during git rebase --continue, run it with GIT_EDITOR=true (or GIT_EDITOR=:).

Guardrails

• Never commit, push, or create branches manually during the upgrade-provider run loop; only run read-only git commands.
• After the tool creates a PR, follow-up commits are permitted for post-run fixes.
• ./scripts/upstream.sh checkout|rebase|check_in are allowed because the tool manages git state.
• Do not stash changes; the tool manages git state.

References

• Use this skill's references/upgrade-provider-errors.md (from the skill folder, not the repo) for patch conflict, ignored upstream replacement, vendored upstream dependency, .NET duplicate file, and new module mapping fixes.

Upgrade Provider Errors

Use this file when the upgrade-provider tool fails and you need concrete fixes. For patch edits/removals/rebases, follow the upstream-patches skill workflow.

Patch conflicts during rebase

The tool uses scripts/upstream.sh to apply patch commits in the upstream submodule. If a patch no longer applies cleanly, you will see rebase errors like:

error: could not apply 83b04967e... docs patching
hint: Resolve all conflicts manually, mark them as resolved with
hint: "git add/rm <conflicted_files>", then run "git rebase --continue".

Fix from the upstream directory, following upstream-patches defaults (edit the owning patch commit; do not create a new patch unless asked):

1. Identify conflicted files. 2. Resolve conflicts while preserving the intent of the patch in patches/. 3. Search for conflict markers and remove all of them before continuing. 4. git add the resolved files. 5. git rebase --continue.

If git rebase --continue opens an editor in automation contexts, run with GIT_EDITOR=true.

Avoid:

• Hand-editing patches/*.patch unless intentionally doing raw patch surgery.
• Direct edits under upstream/ outside checkout/check_in workflow.

After the rebase completes, rerun upgrade-provider from the repo root.

Patch intent guidance

• Docs-related patches usually replace or remove Terraform references. Preserve those changes when resolving conflicts.

Upstream provider relies on ignored replace directives

When upgrade-provider fails during Update TF Provider with an upstream module resolution error like:

go get github.com/rancher/...: exit status 1:
go: github.com/rancher/terraform-provider-rancher2@... requires github.com/rancher/rancher@v0.0.0: unknown revision v0.0.0

the upstream provider may have invalid-looking require entries that are only made valid by its own replace directives. Go ignores replace directives from dependency modules; only the main module's go.mod replacements are honored.

Fix in the Pulumi provider repo:

1. Inspect upstream go.mod at the target tag or commit. 2. Add the narrowest necessary upstream replace directives to provider/go.mod. 3. Avoid copying the entire upstream replace block unless required; broad replacements can conflict with Pulumi or bridge dependencies. 4. Run go mod tidy from provider/. 5. Rerun upgrade-provider from the repo root with the target version explicit. Preserve the original major/non-major intent:

upgrade-provider pulumi/<provider> --repo-path . --target-version <version>

Add --major only when the target upstream version crosses the current upstream major version. Passing --major for a same-major target makes upgrade-provider fail and can trigger unwanted major-version rewrite behavior.

If repo tools are managed by mise, run under the repo environment so Go and converter plugins match CI:

eval "$(mise env)" && upgrade-provider pulumi/<provider> --repo-path . --target-version <version>

Example: pulumi-rancher2 upgrading to upstream terraform-provider-rancher2 v14.1.0 needed main-module replacements like:

replace (
  github.com/rancher/rancher => github.com/rancher/rancher v0.0.0-20260226161459-b186acea1a52
  github.com/rancher/rancher/pkg/apis => github.com/rancher/rancher/pkg/apis v0.0.0-20260226161459-b186acea1a52
  github.com/rancher/rancher/pkg/client => github.com/rancher/rancher/pkg/client v0.0.0-20260226161459-b186acea1a52
)

In that case, copying upstream OpenTelemetry replacements caused conflicts with Pulumi/bridge dependencies; the narrower Rancher-focused replacements were sufficient.

Upstream provider edits vendored dependency but module graph is stale

When make tfgen or upgrade-provider fails compiling the upstream Terraform provider with missing fields or methods from one of its dependencies, check whether upstream edited a vendored copy of that dependency without publishing or requiring a matching module version.

Common symptoms:

unknown field Destination in struct literal of type "github.com/f5devcentral/go-bigip".Gtmmonitor
client.CreateGtmMonitor undefined
client.GetGtmMonitor undefined

Confirm before fixing:

1. Identify the dependency package in the compiler errors. 2. Inspect the upstream provider tag or commit and compare its vendor/<module>/... files against the module version selected by provider/go.mod. 3. If the needed fields or methods exist only under upstream vendor/, treat this as an upstream vendored-dependency patch case.

Fix in the Pulumi provider repo:

1. Add or update the upstream Terraform provider submodule at upstream, pinned to the target upstream tag or commit. 2. Set .gitmodules for the submodule to include ignore = dirty so an applied patch queue does not leave top-level git status noisy. 3. Use the upstream-patches skill and ./scripts/upstream.sh checkout / check_in workflow to add a new patch containing only minimal go.mod files in the affected vendored dependency directories. This is an allowed new-patch case because the provider needs durable vendored module metadata:

./scripts/upstream.sh checkout
cd upstream
# Add minimal go.mod files under vendor/<module>/...
git add vendor/<module>/go.mod
git commit -m "Add module metadata for vendored <module>"
cd ..
./scripts/upstream.sh check_in

4. Add narrow replace directives in provider/go.mod that point only the stale dependency modules at ../upstream/vendor/<module>. 5. Run go mod tidy from provider/, then rerun make tfgen or upgrade-provider.

Example:

replace github.com/f5devcentral/go-bigip => ../upstream/vendor/github.com/f5devcentral/go-bigip

replace github.com/f5devcentral/go-bigip/f5teem => ../upstream/vendor/github.com/f5devcentral/go-bigip/f5teem

Avoid:

• Copying the dependency into provider/third_party or another provider-owned vendor directory.
• Replacing the whole upstream Terraform provider module with ../upstream unless necessary; this can break bridge documentation and example discovery because the module cache layout changes.
• Hand-editing patches/*.patch instead of using upstream-patches, unless intentionally doing raw patch surgery.

When adding this kind of patch, make the tracking issue explicit and de-duplicated:

1. Search existing issues first:

gh issue list --label "area/patch" --search "vendored dependency <module> in:title,body" --json number,title,url

2. If no matching issue exists, create one with gh issue create, labeled area/patch, explaining why the patch exists and when it can be removed:

gh issue create \
  --title "Track vendored dependency patch for <module>" \
  --label "area/patch" \
  --body "$(cat <<'EOF'
The provider upgrade needs a patch because upstream vendors dependency changes
that are not available from the published module graph.

Removal criteria:
- Upstream requires a published dependency module containing the vendored changes, or
- The provider no longer needs the dependency replace directives.

Verification:
- Delete the patch and related provider/go.mod replace directives.
- Run make tfgen.
EOF
)"

3. Link the issue from the upgrade PR's "Fixes applied to unblock upgrade" section.

Removal criteria should usually be: upstream requires a published dependency module containing the vendored changes, or the provider no longer needs the dependency replace directives. Verify removal by deleting the patch and replace directives, then rerunning make tfgen.

New resources missing module mapping

When new upstream resources appear, token mapping can fail with errors like:

* "google_observability_trace_scope": could not find a module that prefixes 'observability_trace_scope' in '[...]'

Fix by updating provider/resources.go (or the repo-equivalent file):

1. Determine the Terraform module name (usually the first segment after the provider prefix). In the example, use observability. 2. Add a module mapping in moduleMapping:

var moduleMapping = map[string]string{
  "observability": "Observability",
}

3. If related resources already map to a different module, map the new resource individually instead of adding a new module key. Example:

DataSources: map[string]*tfbridge.DataSourceInfo{
  "aws_vpn_gateway": {Tok: awsDataSource(ec2Mod, "getVpnGateway")},
}

After updating, rerun upgrade-provider.

.NET duplicate file from nested Get suffix collision

When make generate_sdks fails during .NET SDK generation with an error like:

panic: fatal: An assertion has failed: duplicate file: Chaos/Inputs/ProbeTemplateHttpProbeMethodGetArgs.cs

look for a newly-added nested schema type where a parent type and a child field/type collide with the .NET generator's helper suffixes. Common pattern:

• Parent object type: <X>
• Child field/type: <X>Get
• .NET state helper for the parent: <X>GetArgs.cs
• .NET input helper for the child: <X>GetArgs.cs

Confirm the shape was introduced by the upstream bump before renaming. Compare the generated schema on the default branch with the upgrade branch. Derive the branch and schema path instead of assuming provider-specific names:

default_branch=$(git remote show origin | sed -n 's/.*HEAD branch: //p')
schema_path=$(find provider/cmd -path '*/schema.json' -print -quit)
git show "origin/${default_branch}:${schema_path}" | rg "<NestedTypeName>"
rg "<NestedTypeName>" "$schema_path"

Replace <NestedTypeName> with the colliding nested type prefix from the duplicate filename.

Fix by applying a normal bridge Name override in provider/resources.go to rename the smallest nested field that causes the collision. Do not use CSharpName; it only changes C# property labels and does not change generated nested type filenames. Avoid schema post-processors unless there is no ordinary bridge mapping available.

Example:

"harness_chaos_probe_template": {
  Tok: harnessResource("chaos", "ProbeTemplate"),
  Fields: map[string]*tfbridge.SchemaInfo{
    "http_probe": {
      Elem: &tfbridge.SchemaInfo{
        Fields: map[string]*tfbridge.SchemaInfo{
          "method": {
            Elem: &tfbridge.SchemaInfo{
              Fields: map[string]*tfbridge.SchemaInfo{
                "get": {Name: "getMethod"},
              },
            },
          },
        },
      },
    },
  },
},

After updating the bridge mapping, rerun upgrade-provider from the repo root so schema and SDKs regenerate consistently.

ID attribute wrong type (tfgen unresolved ID mapping)

When make tfgen fails with an error like:

error: Resource linode_producer_image_share_group has a problem: "id" attribute is of type "Int", expected type "string". To map this resource consider overriding the SchemaInfo.Type field or specifying ResourceInfo.ComputeID
error: There were 1 unresolved ID mapping errors

The upstream resource has an id attribute, but it is not a string. Fix it in provider/resources.go (or equivalent) by applying the override:

prov.P.ResourcesMap().Range(func(key string, value shim.Resource) bool {
  if value.Schema().Get("id").Type() != shim.TypeString {
    r := prov.Resources[key]
    if r.Fields == nil {
      r.Fields = make(map[string]*tfbridge.SchemaInfo, 1)
    }
    r.Fields["id"] = &tfbridge.SchemaInfo{Type: "string"}
  }
  return true
})

• If the id type is not coercible to string, set ResourceInfo.ComputeID instead.

ID attribute is input type (tfgen unresolved ID mapping)

When make tfgen fails with an error like:

error: Resource cloudflare_zero_trust_access_ai_controls_mcp_server has a problem: an "id" input attribute is not allowed. To map this resource specify SchemaInfo.Name and ResourceInfo.ComputeID

The upstream resource exposes id as Optional/Required. Remap the input field to <resource_name>_id and delegate the ID to that new property. Convert the field name to Pulumi camelCase (for example, cloudflare_zero_trust_access_ai_controls_mcp_server -> zeroTrustAccessAiControlsMcpServerId).

"cloudflare_zero_trust_access_ai_controls_mcp_server": {
  Fields: map[string]*info.Schema{
    "id": {
      Name: "zeroTrustAccessAiControlsMcpServerId",
    },
  },
  ComputeID: tfbridge.DelegateIDField(resource.PropertyKey("zeroTrustAccessAiControlsMcpServerId"),
    "cloudflare", "https://github.com/pulumi/pulumi-cloudflare"),
},