State, stacks & the up/preview loop

How Pulumi tracks reality.

Beginner12 min · lesson 4 of 12

Like every desired-state tool, Pulumi keeps state — a record mapping the resources in your program to the real ones it created, so it can compute the difference on the next run. The loop is preview then up: pulumi preview shows what would change, pulumi up shows it again and (on confirm) makes it real. pulumi destroy tears the stack down. Reading the preview before confirming is the safety habit.

The core loop

1write code

construct resources

2preview

diff vs state

3up

reconcile reality

4state

record what exists

preview = create, ~ update, - delete, +- replace. A replace on a database or volume means data loss — read it.

terminal

$ pulumi preview
     Type              Name          Plan
 ~   aws:s3:BucketV2   logs          update    [diff: ~tags]
 +-  aws:rds:Instance  db            replace   [diff: ~engineVersion]
$ pulumi up            # shows the same, asks to confirm

State can contain sensitive resource attributes, so it is protected: Pulumi Cloud stores it server-side with access control, and self-managed backends store it in your bucket where you must lock it down. Secrets inside state are encrypted (next lessons), which is a meaningful difference from raw Terraform state where secrets sit in plaintext.

Watch for replace (+-) on stateful resources

The +- symbol in a preview means destroy-and-recreate, triggered by changing an immutable property (an RDS engine version, an EBS type). On a database or volume that is data loss and downtime, not an in-place edit. When you see it on something stateful, stop and plan the change (snapshot, migration) rather than confirming the update.

Resources & the programInputs, Outputs & apply