Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 36 ยท CI/CD and Operations

Previews, Pull Requests and Review Practices for Pulumi

Read pulumi preview output with confidence: symbols, replace versus update, --diff, --json and plans. Learn what reviewers should check and how to gate risky deletes and replacements.

pulumi preview is the most important safety tool you have. It runs your program, compares the result with state and prints what would happen, without changing anything. In a team, the preview is also the thing reviewers read: a code diff of three lines can be a delete of a production database, and only the preview shows it.

Previews need real state and credentials, so the output examples here are illustrative and read-only. The runnable stand-ins parse a preview-like document and apply review rules, which you can adapt to a CI step that fails dangerous plans.

Reading the symbols

TEXT
Previewing update (prod):
     Type                         Name              Plan        Info
     pulumi:pulumi:Stack          shop-prod
 ~   โ”œโ”€ aws:s3:BucketV2           assets            update      [diff: ~tags]
 +   โ”œโ”€ aws:sqs:Queue             jobs              create
 +-  โ”œโ”€ aws:ec2:Instance          web               replace     [diff: ~ami]
 -   โ””โ”€ aws:s3:BucketV2           old-logs          delete

Resources:
    + 1 to create
    ~ 1 to update
    +-1 to replace
    - 1 to delete
    1 unchanged
Symbol Meaning Risk
+ create Low; check cost and naming
~ update in place Medium; check what changes
- delete High for stateful resources
+- replace (create new, then delete old) High; data may be lost, IDs change
-+ replace with delete first (deleteBeforeReplace) Highest; downtime between delete and create
++ create replacement (an intermediate step of a replace) Same as replace

The [diff: ~ami] note is gold: it names the property that forced the change. A property that is immutable at the provider (an AMI, an RDS engine, a subnet's CIDR) turns an update into a replacement.

Useful flags

Terminal
pulumi preview --diff              # property-level diff of every change
pulumi preview --show-sames        # also list unchanged resources
pulumi preview --json > plan.json  # machine-readable output for tools
pulumi preview --expect-no-changes # exit non-zero if anything would change
pulumi preview --refresh           # read the cloud first, so drift is included
pulumi preview --save-plan plan.json   # experimental: save the plan...
pulumi up --plan plan.json             # ...and apply exactly that
pulumi preview --target urn:...        # limit to specific resources (use rarely)

--diff is the one reviewers should use for risky changes. --save-plan and --plan (marked experimental in the CLI) let you apply exactly what was reviewed, which closes the gap where the world changes between preview and up.

What a reviewer should check

  1. Deletes and replaces first. For each one, ask "what holds data here?" Databases, buckets with objects, volumes, queues with messages, DNS zones and certificates deserve extra attention.
  2. Why did it replace? If the diff shows an immutable property, was the change intentional? Often the fix is to avoid changing it, or to use ignoreChanges, or to create a new resource and migrate.
  3. Count and scale. A loop that now creates 500 resources instead of 5 is a bug in a variable, not a feature.
  4. Security changes: IAM policies, security-group rules, public access, encryption flags.
  5. Cost-bearing creates: NAT gateways, load balancers, large instances.
  6. Does the preview match the description? A PR titled "fix tag typo" that plans a replace is wrong.
flowchart TB
  A["Open preview"] --> B{"Any delete or replace?"}
  B -- "yes" --> C["Check data and downtime; get an owner's OK"]
  B -- "no" --> D{"Matches the PR description?"}
  C --> D
  D -- "no" --> E["Ask the author to explain or fix"]
  D -- "yes" --> F["Approve"]

Make the preview a mandatory part of every infrastructure review.

Stand-in: summarize a preview and flag risk

Pulumi's JSON output is rich; this stand-in uses a simplified shape (operation, type, name, reason) to produce a summary like a CI comment, with a risk verdict.

Node.js Stand-in: summarizing a preview for a PR comment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In a pipeline, the same logic can read pulumi preview --json, post the summary as a comment and set a required check that only a maintainer can override.

Stand-in: a guard for stateful resources

Pulumi's own safety net for the same worry is the protect option: a protected resource cannot be deleted or replaced until protection is removed. The next stand-in shows how an apply step would treat protected resources.

Node.js Stand-in: protect blocks delete and replace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

update is allowed on a protected resource; only destructive operations are blocked. Add protect: true to databases, state buckets, KMS keys and anything where losing the resource would be a bad day, and remove it deliberately when you truly want to delete.

Making previews trustworthy

  • Preview against the right stack with refresh. A preview that ignores drift can mislead.
  • Preview with the same config that deploy will use; a missing config key is a common reason for "works in preview, fails in up".
  • Keep previews deterministic. Code that reads the clock, random numbers or the network produces noisy diffs. Use pulumi-random resources (stored in state) instead of Math.random().
  • Avoid giant previews. Split big stacks so reviewers can understand the change.
  • Read the warnings. Provider deprecations and policy advisories appear in the output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the +- symbol mean in a preview?

    +- is a replacement, which can mean new IDs, downtime or data loss for stateful resources.
  2. 2. Which flag exits non-zero when anything would change?

    --expect-no-changes is useful for drift checks and for verifying refactors that should change nothing.
  3. 3. A one-line PR changes an AMI and the preview shows a replace of a production instance. What should the reviewer do?

    Small code changes can have large effects. The preview and its diff reveal them.
  4. 4. What does protect: true do?

    Protected resources cannot be deleted or replaced by an update; updates in place still work.

Summary

  • pulumi preview shows creates, updates, deletes and replaces, and --diff names the properties that cause them.
  • Deletes and replaces of stateful resources deserve explicit human review.
  • Use --refresh, --json, --expect-no-changes and plan files to make previews trustworthy and automatable.
  • Summarize previews in PR comments and gate risky operations with required approval.
  • Use protect as a second line of defense for resources you cannot afford to lose.

Next: The Automation API: Pulumi as a Library