Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

pulumi up, preview, refresh and destroy

Learn the core Pulumi commands: preview, up, refresh, destroy, cancel and stack output. Read the diff symbols, use flags like --diff and --yes, and see the update cycle.

Four commands do most of the work in Pulumi: pulumi preview shows a plan, pulumi up applies it, pulumi refresh re-reads reality and pulumi destroy removes everything a stack owns. This lesson explains what each does, how to read the output and which flags you will use daily.

The real commands run on your machine. The terminal samples below are read-only, and the runnable parts are stand-ins that imitate the plan logic.

The update cycle

flowchart LR
  P["pulumi preview"] --> U["pulumi up"]
  U --> S[("state updated")]
  S --> R["pulumi refresh"]
  R --> P
  S --> D["pulumi destroy"]

Preview and up both run your program; up then performs the steps and records them.

pulumi preview

pulumi preview runs your program, compares it with the state and prints what would happen. Nothing in the cloud changes. A typical first-run preview looks like this (resource names depend on your project):

Text
Previewing update (dev):
     Type                       Name              Plan
 +   pulumi:pulumi:Stack        hello-pulumi-dev  create
 +   โ””โ”€ aws:s3/bucketV2:BucketV2  my-bucket       create

Resources:
    + 2 to create

The left column symbols:

Symbol Meaning
+ create
~ update in place
- delete
+- replace (create new, then delete old, or the reverse)
* read (data source)
(blank) unchanged

Useful flags: --diff prints property-level changes, --json emits machine-readable output, --target narrows to one resource, --expect-no-changes fails when anything would change (a good CI drift check), and --stack prod chooses a stack without switching.

pulumi up

pulumi up does a preview first, then asks:

Text
Do you want to perform this update?  [Use arrows to move, type to filter]
> yes
  no
  details

details shows the property diff. Choosing yes applies the steps in dependency order, in parallel where independent. At the end it prints stack outputs and a summary:

Text
Outputs:
    bucketName: "my-bucket-3f2a1c9"

Resources:
    + 2 created

Duration: 12s

The random suffix is auto-naming: Pulumi appends hex characters to physical names so two stacks can coexist (see Resource Options). Flags: --yes skips the prompt (use it only in automation after a reviewed preview), --skip-preview goes straight to the update, --diff shows details as it runs, --parallel N limits concurrency, --message "..." tags the update in history.

What an update does inside

  1. Run your program; collect the registered resources (the goal state).
  2. For each resource, call the provider's check (validate inputs) and diff (what would change).
  3. Build the steps: create, update, replace, delete, same.
  4. Execute steps in dependency order; save the state after every step so a crash loses little.

Because state is saved incrementally, an interrupted up leaves a consistent record plus possibly a pending operation. pulumi cancel stops a running update, and pulumi stack export | pulumi stack import can repair pending operations; pulumi refresh often fixes the rest.

pulumi refresh

Cloud resources change outside Pulumi: someone edits a tag in the console, an autoscaler adds an instance. pulumi refresh asks each provider for the current properties and updates the state to match, without touching the cloud:

Terminal
pulumi refresh --diff

After a refresh, the next up compares your program against the corrected state and therefore reverts console edits you did not codify. Use pulumi preview --refresh or pulumi up --refresh to refresh and plan in one go.

pulumi destroy

pulumi destroy deletes all resources in the stack, in reverse dependency order, but keeps the stack and its history. To remove the stack record too:

Terminal
pulumi destroy
pulumi stack rm dev

pulumi stack rm --force removes the stack without destroying resources, which orphans them; avoid it unless you know the resources are gone. Resources marked protect: true block a destroy until unprotected.

Reading outputs afterwards

Terminal
pulumi stack output                 # all outputs
pulumi stack output bucketName      # one value, plain text
pulumi stack output --json          # JSON for scripts

Stand-in: how a plan is built

This stand-in takes a previous state and a new goal and prints Pulumi-style symbols, including a replace for an immutable property. Try changing region to see a replacement.

JS Stand-in: plan with symbols

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

No output.

Stand-in: refresh and drift

JS Stand-in: refresh then plan

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command changes only the state to match the real cloud, without changing the cloud?

    Refresh reads current properties from providers and updates the state.
  2. 2. What does the +- symbol in a plan mean?

    Some property changes cannot be applied in place, so the resource is replaced.
  3. 3. What does pulumi destroy delete?

    Use pulumi stack rm afterwards to remove the empty stack.
  4. 4. Which flag makes preview fail if any change would occur, useful for drift checks in CI?

    --expect-no-changes exits non-zero when the plan is not empty.

Summary

  • pulumi preview plans, pulumi up applies (after confirmation), both run your program.
  • Plan symbols: + create, ~ update, - delete, +- replace.
  • State is saved after each step; refresh syncs state with reality and cancel stops a running update.
  • pulumi destroy empties the stack; pulumi stack rm removes the stack itself.
  • Read results with pulumi stack output.

Next: Stacks and Projects