Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Concepts and Stacks

Desired State, URNs and How Pulumi Diffs

See how Pulumi decides what to change: resource registration, URNs, check and diff, in-place update versus replacement, and the create-before-delete rule, with runnable stand-ins.

Once you understand how Pulumi decides what to do, its behaviour stops being surprising. This lesson follows a resource from the line of code that declares it to the step the engine runs: registration, identity by URN, provider check and diff, and the difference between an in-place update and a replacement.

The engine, providers and cloud are not available on this site. The code below uses read-only real snippets plus runnable JavaScript stand-ins that mimic the algorithm in simplified form.

Registering resources

When your program runs new aws.s3.BucketV2("assets", {...}), the SDK does not call AWS. It sends a RegisterResource request to the engine: type, name, inputs, parent and options. The engine answers with the resource's outputs once the step has run (or predicted values during a preview).

TypeScript
const bucket = new aws.s3.BucketV2("assets", {
  tags: { team: "web" },
});

That one line means: "there must be a resource of type aws:s3/bucketV2:BucketV2 named assets with these inputs".

Identity: the URN

The engine identifies a resource across runs by its URN:

Text
urn:pulumi:<stack>::<project>::<type>::<name>
urn:pulumi:dev::web::aws:s3/bucketV2:BucketV2::assets

If a URN in the program also exists in the state, the engine compares them. If it exists only in the program, it is a create. If it exists only in the state, it is a delete. A resource with a parent includes the parent's type in the URN path (parent$child), so moving a resource under a different parent changes its URN. Renaming the first argument of a resource also changes the URN, which is why a plain rename becomes a replace. You can avoid that with aliases (Resource Options).

Check and diff

For a URN present on both sides, the engine asks the provider two questions:

  1. Check: "Are these new inputs valid?" The provider validates and may fill defaults, including auto-names.
  2. Diff: "How do the old inputs/state differ from the new inputs?" The provider returns which properties changed and whether each change needs a replacement.
flowchart TD
  A["URN in program?"] -->|no| X["delete"]
  A -->|yes| B["URN in state?"]
  B -->|no| C["create"]
  B -->|yes| D["provider check, then diff"]
  D -->|no changes| E["same"]
  D -->|in place| F["update"]
  D -->|replacement needed| G["replace"]

The decision tree for every resource in every update.

Update versus replace

Cloud APIs differ in what can be changed after creation. Tags on a bucket can change in place. The region of a bucket cannot, and neither can the availability zone of a subnet. The provider marks such properties as forcing replacement.

  • Update keeps the physical resource and changes properties.
  • Replace creates a new physical resource and deletes the old one.

The default replacement order is create first, then delete. If a resource has a fixed physical name that must be unique, the new one cannot exist next to the old one, so you set deleteBeforeReplace: true to delete first. Dependents are updated to point to the new resource in between, which minimises downtime when your resources reference each other.

Replacement is a normal, safe operation for stateless things and a dangerous one for databases. Always read the plan for +- before approving, and protect critical resources with protect: true.

Outputs known only after creation

During pulumi preview some values do not exist yet, such as the ID of a not-yet-created bucket. They show as <computed>. Your program receives these as Outputs that resolve later (Inputs and Outputs).

Stand-in: check and diff

Run this to watch a diff function classify changes. The forcesReplacement list plays the role of the provider's schema.

JS Stand-in: provider diff

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

No output.

Stand-in: URN-based planning

JS Stand-in: plan by URN

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

No output.

Practical consequences

  • Changing the logical name (first argument) usually replaces a resource. Use an alias when refactoring.
  • Moving code between files or into a component changes URNs for children; again use aliases or parent carefully.
  • Read ~ versus +- in previews; replacements of data stores deserve a pause.
  • If an update fails halfway, the state still matches what was created; fix the cause and run pulumi up again. The engine is idempotent: running it twice leaves the same result.
  • pulumi preview --diff explains exactly which property forced a replacement (it marks it with [forces replacement]).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does the engine recognise the same resource across runs?

    The URN is the logical identity; the cloud ID is a property of the resource.
  2. 2. What does the provider's diff decide?

    Diff reports changed properties and which of them cannot be changed in place.
  3. 3. You rename a bucket's logical name from 'logs' to 'logs-v2' with no alias. What does the plan show?

    The URN changed, so the engine sees a new resource and a missing old one.
  4. 4. What is the default replacement order?

    Create-before-delete is the default; deleteBeforeReplace flips it for resources with fixed unique names.

Summary

  • Each new Resource registers a desired resource; the engine never runs create calls directly from your code.
  • URNs identify resources; present only in program means create, only in state means delete.
  • The provider's check validates inputs and diff tells update versus replace.
  • Replacement is create-then-delete by default; protect stateful resources.
  • Renaming or re-parenting changes URNs unless you add aliases.

Next: Inputs and Outputs