Add blog post about component state migrations

[julienp]

Blog post for the component state migrations that shipped with https://github.com/pulumi/pulumi/releases/tag/v3.264.0

[julienp]

This change is part of the following stack:

• Document component state migrations #21865
  • Add blog post about component state migrations #21871 ◀

_{Change managed by git-spice.}

[github-actions]

Sentinel — merge gate status (preview)

Warning

⚠️ Preview mode — this check is NOT blocking your merge

The Sentinel is in preview (report-only) mode: its check-run concludes neutral whatever the gates below say, so nothing here gates this PR. The rows are informational and safe to ignore for now. It would have concluded success.

This will be enforced in the near future. Once it is, every row below has to be green before this PR can merge. The rows are the sign-offs a merge needs — some yours, some a reviewer's or a deploy's. Tell us in #docs if one looks wrong.

All gates green — nothing would block this merge.

	Gate	What it needs
✅	G1 review-ran	Nothing to do: review current at 3cf8eb534.
✅	G2 findings-answered	Nothing to do: every finding answered.
✅	G3 right-approver	Nothing to do: a routing-team member approved.
➖	G4 infra-evidence	Doesn't apply to this PR: no changed path affects the deploy.
➖	G5 oversized-ack	Doesn't apply to this PR: not oversized.

_{Evaluated at head 3cf8eb534.}

[github-actions]

Social Media Review

content/blog/component-state-migrations/index.md

No social: block in frontmatter — this post will not be promoted as-is. Copy drafted below from the article body for all three platforms.

X — missing

No copy provided. Suggested copy drafted below.

LinkedIn — missing

No copy provided. Suggested copy drafted below.

Bluesky — missing

No copy provided. Suggested copy drafted below.

---

Suggested copy

X (244/255 chars):

Swap a component's internals without a migration path, and Pulumi may replace it, taking the security group that references it, and anything downstream, with it.

Pulumi's new state migrations let component authors ship that upgrade themselves.

LinkedIn (873/2950 chars):

Upgrade a Pulumi component's internals, and by default the saved state doesn't know the new code represents the same resources. Pulumi may replace what's there, including a VPC, which means replacing the security group that points at its ID, and potentially forcing changes on anything running on that network, like a database.

We built component state migrations to close that gap. A migration callback runs before Pulumi diffs the program against state, translating the old records into their new shape and mapping old names to new ones.

We wrote an example that walks a VPC through three real versions: a legacy AWSX component, the modern AWSX component, and finally plain AWS resources with no component at all. The underlying VPC, subnet, and gateway never get touched.

Here's how the migration callbacks work, and what it takes to ship one with your own component.

Bluesky (266/300 chars):

Change a component's internals without telling Pulumi's state, and an upgrade can replace resources that were never meant to move, like a VPC, dragging the security group that references it along with it.

Pulumi's new state migrations fix that. Here's how it works.

Updated for commit `d9105b091a0e7725370d5bd2070b50420c4d87f6` (short: `d9105b0`) at 2026-09-25 10:46 UTC.

[github-actions]

Reviewer's guide v2 — not for the author

Tip

This is the reviewer's guide. Work through the ⚠️ checklist below, then approve — approving asserts only that the ⚠️ items looked right to you. Machine-verified this run: links, shortcodes, page metadata, and every claim marked verified (receipts on the evidence page). Code samples are read, not compiled.

PR author: your to-do list is the other review comment, "Author action guide" — nothing on this card is yours.

Approval needed from: @pulumi/docs-blog-review, @pulumi/docs-guild, @pulumi/docs-tools — any member's approval satisfies the merge gate.

Note

What this PR changes:

• New blog post content/blog/component-state-migrations/index.md: explains component state migrations through an AWSX VPC walkthrough.
• Three TypeScript snippet files under static/programs/awsx-vpc-state-migration-blog-typescript/, excluded from program tests.
• Small edits to the state-migrations guide and the statemigrations resource-option page.
• Two Vale vocabulary additions.

Readers would be misled by a link to a missing or mismatched example, or by a warning about a replacement the upgrade doesn't actually cause. The fact-check, frontmatter and link validation, Hugo build, and code-snippet reads all ran.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	MEDIUM	4 claims about the examples directory couldn't be inspected
coherence	HIGH
cross-sibling consistency	MEDIUM	no sibling fan-out ran; docs edits are small
code correctness	MEDIUM	snippets are .ts.txt files and aren't compiled

⚠️ Check these before approving

ID	Where	Finding
F5	content/blog/component-state-migrations/index.md L45	"In a real application, changes to a component's network can cause downtime or require more resource replacements." — verdict: verified. Spurious: the paragraph is explicitly hypothetical ("Now imagine…"), so this general statement doesn't need a citation.

Editorial stances introduced by this PR

Superlative, ranking, or comparative language the diff adds. No verdict — a page's own framing isn't fact-checkable — but confirm each is a stance the docs should take, and that no agent-written rewrite introduced it unasked.

None — the extractor found no positioning or comparison language in this PR's added lines.

✅ What you can rubber-stamp

• Facts: 57 factual claims checked — 53 verified clean, 1 flagged in the ⚠️ list, 3 settled — see the evidence page.
• Mechanics: frontmatter sweep ran; Hugo build green; 3 added internal link(s) resolve.
• Style: 0 advisory suggestions left with the author; never blocking.

💡 Pre-existing issues in touched files: 0 — details on the evidence page.

📎 Full evidence: verification trail, investigation log, review history.

_{Review v2 · updated 2026-09-25T15:18:28Z · head commit 3cf8eb5}

---

For the reviewer: the ⚠️ items above are the minutes that matter — the receipts for everything machine-verified are on the evidence page. The author's open items live on their own card (the comment headed "Author action guide"); while any are open, a Waiting on the author list above tracks them, and merge stays blocked until they're answered. If something here seems off, comment on the PR — @claude <your point> #update-review re-adjudicates with your input.

[github-actions]

Author action guide v2 — nothing blocks merge

Note

Nothing here blocks merge — no open items need an answer from you. A human reviewer still approves the merge.

This PR adds a blog post on component state migrations, plus small docs tweaks and three sample files. The review fact-checked 57 claims; four depend on an examples directory or on upgrade behavior that only you can confirm.

🚨 Fix or disagree

Nothing to fix — this section is empty.

❓ Questions for you

No open questions for you.

✅ Resolved since last review

ID	Where	Finding
F1	content/blog/component-state-migrations/index.md L19	"The GitHub repository at https://github.com/pulumi/examples/tree/master/aws-ts-awsx-vpc-state-migration contains all three example programs (v1, v2, v3) and…" — verdict: unverifiable; framing: The page loads, but the fetched body says nothing about the directory's contents. — concede: @CamSoper confirmed; gh contents listing shows pulumi/examples master has aws-ts-awsx-vpc-state-migration (README.md, v1, v2, v3), so the links resolve.
F2	content/blog/component-state-migrations/index.md L39	"The AWSX VPC example at github.com/pulumi/examples follows a network through three versions of code: v1, v2, and v3, where you start with v1, upgrade to v2…" — verdict: unverifiable; framing: The page was fetched, but its truncated body doesn't cover the claim. A gh contents listing of pulumi/examples/aws-ts-awsx-vpc-state-migration would settle it. — concede: @CamSoper confirmed; the directory listing shows v1, v2, and v3 subdirectories, matching the post's v1 → v2 → v3 description.
F3	content/blog/component-state-migrations/index.md L43	"Without a state migration connecting old state to new code, upgrading the AWSX VPC component could replace the VPC instead of keeping it." — verdict: unverifiable; framing: shifted: the source says changing a security group's VpcId forces replacement of the security group, but the claim says upgrading the AWSX VPC component… — concede: @CamSoper (maintainer) confirmed that upgrading without the migration would replace the VPC; domain-knowledge answer accepted.
F4	content/blog/component-state-migrations/index.md L144	"The VPC example at https://github.com/pulumi/examples/tree/master/aws-ts-awsx-vpc-state-migration contains all three programs and the migration code shown in…" — verdict: unverifiable; framing: The source only shows the directory exists. It says nothing about what's inside ("all three programs and the migration code"). — concede: @CamSoper (maintainer) confirmed the example contains all three programs and the migration code shown in the post.

📎 Full evidence: verification trail, investigation log, review history.

_{Review v2 · updated 2026-09-25T15:18:28Z · head commit 3cf8eb5}

---

How to answer

Every 🚨 and ❓ item above needs one of these before merge:

1. Fix it — push the change. If your push lines up with the flagged lines, this card shows a 🔄 banner within a minute and then refreshes itself. No banner? Comment:

   @claude I pushed a fix for F1 #update-review
   

2. Disagree with it — say which item and why; the review re-checks with your input:

   @claude F2: <your reasoning — e.g. where the figure comes from> #update-review
   

   Either way your answer counts: the review marks the item resolved, or keeps it with a 🛡️ note for your human reviewer to weigh — it stops blocking merge in both cases.

3. Accept it as-is — you own the PR; a one-line reason is a valid answer, and your reviewer sees it beside the finding:

   @claude F2: accepting as-is — <your reason> #update-review
   

   To accept every open item at once: @claude accepting all open items — <reason> #update-review.

The #update-review hashtag matters — it routes your reply to this review, and (besides pushing a fix) it is the only reply that unblocks merge. A bare @claude gets you ad-hoc help and leaves this card — and the merge block — untouched.

Please don't edit, hide, or delete this comment — it is the review's record. Full mechanics: CONTRIBUTING.md §AI-assisted contributions.

[github-actions]

🤖 Review auto-refreshed — the latest push only touched lines with outstanding findings.

[julienp]

@claude pushed #update-review

[github-actions]

🤖 Review updated on @julienp's request.

[julienp]

@claude updataes #update-review

[github-actions]

🤖 Review updated on @julienp's request.

[julienp]

@claude #update-review

F13: confirmed
F14: confirmed

[github-actions]

🤖 Review updated on @julienp's request.

[julienp]

@claude front matter update #update-review

[github-actions]

🤖 Review updated on @julienp's request.

[CamSoper]

@claude confirm F1, F2, F3, and F4 and #update-review

[github-actions]

🤖 Review updated on @CamSoper's request.

[CamSoper]

@julienp sorry for the delay -- You're good to go

[cnunciato]

Nice work @julienp! Sorry I didn't get a chance to read this before it merged — looks like it's missing an image. I'll get that fixed up for ya!