docs(import): refocus import guide on CLI-first and program-first (bulk) approaches

[joeduffy]

Fixes #15053

What changed

The import guide previously organized its two CLI-based workflows (single-resource import and bulk import from a JSON file) as if they were parallel-but-separate features, and buried the "generate an import file from a program" workflow — the one issue #15053 asks us to foreground — deep inside a "Bulk Import Operations" section, well after the code-based import resource option.

This restructures the page around the two approaches users actually reach for:

1. CLI-first import — run pulumi import <type> <name> <id> against a single resource, then copy the generated code into your program. Unchanged in substance, just retitled and reordered.
2. Program-first (bulk) import — write your program first (optionally using components), run pulumi preview --import-file <path> to generate an import file with names, URNs, and types already filled in, fill in the blank id fields, then run pulumi import --file <path> to import everything in one operation. This is now the lead workflow within the section, with the existing component-import walkthrough as its worked example.

The pre-existing "author the JSON file by hand" workflow and the resource/schema reference table are preserved verbatim, just moved under a new "Authoring an import file by hand" subheading as an alternative to generating the file with pulumi preview --import-file.

The import resource option keeps its full existing content (including the mismatched-state walkthrough) but is now explicitly framed as a third, older mechanism superseded by the two approaches above, per the issue.

I also found and fixed a broken internal anchor link (#how-import-works, which didn't exist) pointing it at the correct #where-to-find anchor, and added a short cross-link from the components concept page to the new program-first import section so readers building components know they can bulk-import them.

Verification

I cross-checked the flag names against the authoritative, auto-generated CLI reference pages (pulumi_import.md and pulumi_preview.md) rather than inventing anything: pulumi import --file/-f and pulumi preview --import-file both match what's documented there. Front matter parses as valid YAML, Hugo shortcodes (chooser/choosable, notes) remain balanced exactly as in the original, and the file ends with a single trailing newline.

---

🧠 This PR was created by workprentice on behalf of @joeduffy.

[github-actions]

Pre-merge Review — Last updated 2026-07-03T19:00:29Z

Tip

Summary: This PR refactors the resource-import guide (content/docs/iac/guides/migration/import/), reframing it around the two recommended import approaches — CLI-first import (Approach 1) and program-first (bulk) import (Approach 2) — and repositioning the older import resource option as a still-supported-but-superseded mechanism; it also adds a cross-link from the components concept page to the new bulk-import section. The failure mode that would block a reader here is a stale section anchor (several headings were renamed) or a broken cross-reference sending them to the wrong place, or a mis-described command sequence. The renamed-section anchors and the new components → import cross-link all resolve — the #where-to-find target carries an explicit {#where-to-find} heading ID, and because the Hugo build was skipped for this content-only PR, anchors were checked manually against the head revision — all 25 factual claims check out against the guide and CLI reference, and frontmatter/aliases are clean. The only nit is a moved example that carries ascending ordered-list numbering.

Review confidence:

Dimension	Level	Notes
mechanics	HIGH
facts	HIGH
code correctness	HIGH

Investigation log

• Cross-sibling reads: not run (not in a templated section)
• External claim verification: 25 of 26 claims verified (0 unverifiable, 0 contradicted) · 4 specialists (numerical, cross-reference, capability, framing); 0 cross-specialist corroborations · routed: 0 inline, 22 Pass 1, 0 Pass 2, 4 Pass 3 (verified 3, contradicted 0, unverifiable 1).
• Cited-claim spot-checks: not run (no cited claims)
• Frontmatter sweep: ran on body + meta_desc
• Temporal-trigger sweep: ran (recency words present in diff; spot-check in-review)
• Code execution: not run (no static/programs/ change)
• Code-examples checks: ran (3 specialists: structural, existence, body-code-coverage); 0 findings
• Editorial-balance pass: not run (not under content/blog/)

🚨 Outstanding	⚠️ Low-confidence	💡 Pre-existing	✅ Resolved
0	4	0	0

🔍 Verification trail

26 claims extracted · 25 verified · 0 unverifiable · 0 contradicted

• L364 in content/docs/iac/concepts/components/_index.md "There is a documentation page titled 'program-first (bulk) import' located at /docs/iac/guides/migration/import/#approach-2-program-first-bulk-import." → ✅ verified (evidence: content/docs/iac/guides/migration/import/_index.md contains the heading '## Approach 2: Program-first (bulk) import' at line 160, which generates the anchor #approach-2-program-first-bulk-import referenced in the claim.; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L24-30 in content/docs/iac/guides/migration/import/_index.md "In program-first import, you fill in the cloud provider ID for each resource in the generated import file, then run pulumi import --file to bring all of them…" → ✅ verified (evidence: The same doc states: "Edit the generated file, filling in the id field for each resource with its identifier from the cloud provider. Run pulumi import --file <path> to import all of the resources into your stack's state in a single op…; source: repo:content/docs/iac/guides/migration/import/_index.md (lines 163-167, 205-209))
• L28 in content/docs/iac/guides/migration/import/_index.md "Running pulumi import adds the resource to your stack's state and generates the code needed to manage it, which you then copy into your Pulumi program." → ✅ verified (evidence: The pulumi_import CLI doc states: "A definition for each resource will be printed to stdout in the language used by the project associated with the stack; these definitions should be added to the Pulumi program," and the import guide itsel…; source: content/docs/iac/cli/commands/pulumi_import.md and content/docs/iac/guides/migration/import/_index.md)
• L30 in content/docs/iac/guides/migration/import/_index.md "Program-first import involves writing your Pulumi program first, potentially using components to describe many resources at once, then running pulumi preview…" → ✅ verified (evidence: The same doc later describes the identical workflow: "Run pulumi preview --import-file ` to generate an import file for every resource the program would otherwise create," matching the claim's description of program-first/bulk impor…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L32 in content/docs/iac/guides/migration/import/_index.md "Both the CLI-first and program-first import approaches rely on the same underlying mechanics, described in the 'How resource import works' section." → ✅ verified (evidence: The source file states verbatim: "Both approaches rely on the same underlying mechanics, described in How resource import works below, and both result in resources that are fully managed by Pulumi going forwar…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L32 in content/docs/iac/guides/migration/import/_index.md "The import resource option is a third, older import mechanism that is still supported." → ✅ verified (evidence: The source doc itself states: "A third, older mechanism --- the import resource option --- is still supported and explained later in this guide, but it has generally been superseded by the two approaches ab…; source: repo:content/docs/iac/guides/migration/import/_index.md#L32)
• L54 in content/docs/iac/guides/migration/import/_index.md "The pulumi import command looks up the resource using the specified type token and resource identifier, adds the resource to the stack's current state, and e…" → ✅ verified (evidence: The doc page itself shows the CLI syntax pulumi import <type> <name> <id> right after this sentence, and describes the type/lookup workflow consistent with well-established pulumi import behavior of locating the resource, adding it to…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L54 in content/docs/iac/guides/migration/import/_index.md "The pulumi import CLI-first approach requires the least manual effort of the import approaches, so is generally recommended." → ✅ verified (evidence: The claim is a verbatim restatement of the doc's own line: "This option requires the least manual effort, so is generally recommended, and is best suited to projects consisting of only one stack." This is the author's own editorial posit…; source: repo:content/docs/iac/guides/migration/import/_index.md#L54)
• L54 in content/docs/iac/guides/migration/import/_index.md "CLI-first import is best suited to projects consisting of only one stack." → ✅ verified (evidence: The official Pulumi docs page for this exact guide states verbatim: "This option requires the least manual effort, so is generally recommended, and is best suited to projects consisting of only one stack."; source: https://www.pulumi.com/docs/iac/guides/migration/import/)
• L62-64 in content/docs/iac/guides/migration/import/_index.md "The type token for a given resource can be found by navigating to the Import section of the resource's API documentation in the Pulumi Registry." → ✅ verified (evidence: The Pulumi docs page itself states: "you'll find the type token for a given resource by navigating to the Import section of the resource's API documentation in the Pulumi Registry."; source: https://www.pulumi.com/docs/iac/guides/migration/import/)
• L160-162 in content/docs/iac/guides/migration/import/_index.md "When importing many resources at once, or resources already described by a Pulumi program (e.g., a set of components), it's usually easier to let Pulumi genera…" → ✅ verified (evidence: The same doc states at L30: "Program-first import, sometimes called bulk import... This approach scales better when you're importing many resources, or resources that are already described by a program you've written." The components page…; source: repo:content/docs/iac/guides/migration/import/_index.md (L30, L162); repo:content/docs/iac/concepts/components/_index.md)
• L162-167 in content/docs/iac/guides/migration/import/_index.md "The program-first (bulk) import workflow has four steps: write the Pulumi program describing the infrastructure to import; run pulumi preview --import-file <p…" → ✅ verified (evidence: The source file (content/docs/iac/guides/migration/import/_index.md, lines 162-167) lists exactly these four steps: "1. Write the Pulumi program... 1. Run pulumi preview --import-file `... 1. Edit the generated file, filling in the…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L164 in content/docs/iac/guides/migration/import/_index.md "In program-first import, you should not run pulumi up before generating the import file, because the resources described by the program already exist in the…" → ✅ verified (evidence: The doc itself states at line 164: "Don't run pulumi up yet --- the resources described by the program already exist in your cloud account, so applying the program as written would try to create them again." This is a verbatim match to t…; source: repo:content/docs/iac/guides/migration/import/_index.md#L164)
• L171 in content/docs/iac/guides/migration/import/_index.md "In the example, the Pulumi program defines a VPC component from the AWS Crosswalk for Pulumi library." → ✅ verified (evidence: The example's import.json shows a resource of type "awsx:ec2:Vpc" (the awsx package, marketed as "AWS Crosswalk for Pulumi"), matching the doc's example programs under static/programs/awsx-vpc-*, confirming the VPC component is indeed from…; source: repo:content/docs/iac/guides/migration/import/_index.md (lines 171, 185) and repo:static/programs/awsx-vpc-typescript/Pulumi.yaml)
• L173 in content/docs/iac/guides/migration/import/_index.md "The example code creates a new VPC using all default settings." → ✅ verified (evidence: The referenced example program at static/programs/awsx-vpc-typescript/index.ts contains: // Allocate a new VPC with the default settings.\nconst vpc = new awsx.ec2.Vpc(\"vpc\"); — no configuration properties are passed, confirming the cl…; source: repo:static/programs/awsx-vpc-typescript/index.ts)
• L179 in content/docs/iac/guides/migration/import/_index.md "Running pulumi preview --import-file import.json generates a placeholder import file for every resource that would be created." → ✅ verified (evidence: The same doc states elsewhere: "you can run pulumi preview --import-file <file> to generate a placeholder import file for every resource that would be created. The generated file will contain all the names, URNs, and types already filled…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L181-199 in content/docs/iac/guides/migration/import/_index.md "The generated import.json file for the VPC component example has a resources array containing an entry of type awsx:ec2:Vpc named vpc marked as a compo…" → ✅ verified (evidence: The doc's example import.json shows exactly: {"type": "awsx:ec2:Vpc", "name": "vpc", "component": true} followed by {"type": "aws:ec2/vpc:Vpc", "name": "vpcVpc", "id": "", "parent": "vpc", "logicalNa…; source: repo:content/docs/iac/guides/migration/import/_index.md (L181-199))
• L201 in content/docs/iac/guides/migration/import/_index.md "In the generated import file, the component is defined as a separate resource, and all parent values are set according to the preview." → ✅ verified (evidence: The doc's own JSON example shows the component as a separate resource entry ("type": "awsx:ec2:Vpc", "name": "vpc", "component": true) followed by child resources with "parent": "vpc", and the schema table confirms parent is "The nam…; source: repo:content/docs/iac/guides/migration/import/_index.md (lines 183-201, 488-501))
• L203 in content/docs/iac/guides/migration/import/_index.md "After generating the import file, you edit it to replace all <PLACEHOLDER> values with existing resource IDs from your AWS account." → ✅ verified (evidence: The doc itself states: "2. Edit the JSON file to replace all <PLACEHOLDER> values with existing resource IDs from your AWS account." matching the claim verbatim, in the context of the pulumi preview --import-file workflow shown just ab…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L205-209 in content/docs/iac/guides/migration/import/_index.md "Running pulumi import --file import.json imports all the resources in one operation." → ✅ verified (evidence: The same doc states elsewhere: "Run pulumi import --file <path> to import all of the resources into your stack's state in a single operation" (line 167), and the CLI reference confirms --file/-f passes a JSON file listing all resourc…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L211 in content/docs/iac/guides/migration/import/_index.md "The same bulk-import approach can be used to import any component resource and its sub-resources." → ✅ verified (evidence: The doc itself states verbatim: "The same approach can be used to import any component resource and its sub-resources," and the import file schema documents component and remote boolean fields explicitly for creating component resource…; source: repo:content/docs/iac/guides/migration/import/_index.md (L211, L500-501))
• L213-215 in content/docs/iac/guides/migration/import/_index.md "You can author an import file by hand rather than generating one with pulumi preview --import-file, which is useful when scripting a bulk import from an inve…" → ✅ verified (evidence: The doc itself states in the "Authoring an import file by hand" section: "You can also author an import file by hand rather than generating one with pulumi preview --import-file. This is useful when scripting a bulk import from an invent…; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L505 in content/docs/iac/guides/migration/import/_index.md "The import resource option is documented under the heading 'The import resource option'." → ✅ verified (evidence: Line 505 of the file reads exactly ## The \import` resource option, matching the earlier cross-reference link text `import` resource option` at line 32.; source: repo:content/docs/iac/guides/migration/import/_index.md)
• L507 in content/docs/iac/guides/migration/import/_index.md "The import resource option is documented in this guide for completeness and because existing programs still use it." → ➖ not-a-claim (evidence: This is an editorial/positioning statement about why the guide's own authors chose to document the import resource option, not a falsifiable third-party assertion that can be checked against an external source.; source: content/docs/iac/guides/migration/import/_index.md (self-referential authorial rationale))
• L507 in content/docs/iac/guides/migration/import/_index.md "For new work, CLI-first import or program-first (bulk) import is preferred over the import resource option." → ✅ verified (framing: strengthened — claim states CLI-first/bulk import is "preferred over" the resource option; source says the CLI approach "is generally recommended," and the res…; evidence: The official Pulumi docs state: "This option requires the least manual effort, so is generally recommended, and is best suited to projects consisting of only one stack," referring to the pulumi import CLI command, while the import resource…; source: https://www.pulumi.com/docs/iac/guides/migration/import/)
• L507 in content/docs/iac/guides/migration/import/_index.md "Before pulumi preview --import-file existed, the import resource option was the recommended way to import multiple resources across multiple stacks or depl…" → ✅ verified (evidence: The same doc states elsewhere: "A third, older mechanism --- the import resource option ... is still supported ... but it has generally been superseded by the two approaches above [CLI-first and program-first import using `pulumi preview…; source: repo:content/docs/iac/guides/migration/import/_index.md (lines 30-32, 507))
• L203-205 in content/docs/iac/guides/migration/import/_index.md "Component-import example's numbered steps use ascending 1./2./3. markers instead of the repeated 1. convention" → 🚩 flagged (ordered-list numbering)

🚨 Outstanding in this PR

No outstanding findings in this PR.

⚠️ Low-confidence

Review each and resolve as appropriate — these don't block the PR.

• [L203-205] content/docs/iac/guides/migration/import/_index.md — The numbered steps in the "Import a component with all resources" example use ascending 1. / 2. / 3. markers. The repo convention (and STYLE-GUIDE.md) is for every ordered-list item to begin with a literal 1. so reordering doesn't churn the diff. This block was moved verbatim from later in the guide, so the numbering predates this PR — but it's a one-line-per-marker fix worth making while the section is being reworked: change the 2. (L203) and 3. (L205) markers to 1. so all three items read 1..

Style findings

Found by pattern-based linting; Findings may be false positives.

• line 364: [style] wordiness — 'all of' is too wordy.
• line 26: [style] filler — Don't start a sentence with 'There are'.
• line 30: [style] wordiness — 'all of' is too wordy.

💡 Pre-existing issues in touched files (optional)

No pre-existing issues in touched files.

✅ Resolved since last review

No items resolved since the last review.

📜 Review history

• 2026-07-03T19:00:29Z — Refocused the import guide on CLI-first and program-first (bulk) approaches; renamed-section anchors and the new components cross-link verified to resolve and all 25 factual claims confirmed, with one minor ordered-list-numbering nit in the moved example (a8f117b)

---

Need a re-review? Want to dispute a finding? Mention @claude and include #update-review.
(For ad-hoc questions or fixes, just @claude — no hashtag.)

[pulumi-bot]

Your site preview for commit a8f117b is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-20080-a8f117bb.s3-website.us-west-2.amazonaws.com

[CamSoper]

Automated rubber stamp approval applied

---

Generated by Claude Code