Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 36 ยท State and Backends

Pulumi State: What Is Inside a Checkpoint and How Updates Use It

Look inside Pulumi state: the checkpoint JSON, URNs, inputs vs outputs, dependencies, secrets and how pulumi up diffs desired state against recorded state.

Pulumi is a state-based tool. After every update it records what it created in a checkpoint, a JSON document stored per stack. On the next pulumi up it compares your program (the desired state) with the checkpoint (the recorded state) and with the cloud (when you refresh), then computes the smallest set of operations to reconcile them.

Understanding the checkpoint turns many mysterious behaviors into obvious ones: why a rename deletes a resource, why a secret looks like gibberish, why state surgery commands exist. The Pulumi CLI cannot run on this site, so real commands and JSON are read-only; the runnable examples are stand-ins that implement the diff idea.

Looking at state

Terminal
pulumi stack export > state.json     # the whole checkpoint
pulumi stack --show-urns             # tree with URNs
pulumi stack output                  # only the exported outputs

A trimmed export looks like this (values shortened):

JSON
{
  "version": 3,
  "deployment": {
    "manifest": { "time": "2026-05-04T09:12:44Z", "magic": "...", "version": "v3.140.0" },
    "secrets_providers": { "type": "service" },
    "resources": [
      {
        "urn": "urn:pulumi:dev::shop::pulumi:pulumi:Stack::shop-dev",
        "custom": false,
        "type": "pulumi:pulumi:Stack"
      },
      {
        "urn": "urn:pulumi:dev::shop::pulumi:providers:aws::default_6_50_0",
        "custom": true,
        "id": "0b8f8c2d-....",
        "type": "pulumi:providers:aws::default_6_50_0",
        "inputs": { "region": "eu-central-1" }
      },
      {
        "urn": "urn:pulumi:dev::shop::aws:s3/bucketV2:BucketV2::assets",
        "custom": true,
        "id": "assets-3f9a1c2",
        "type": "aws:s3/bucketV2:BucketV2",
        "inputs":  { "tags": { "team": "web" } },
        "outputs": { "arn": "arn:aws:s3:::assets-3f9a1c2", "bucket": "assets-3f9a1c2", "tags": { "team": "web" } },
        "parent": "urn:pulumi:dev::shop::pulumi:pulumi:Stack::shop-dev",
        "provider": "urn:pulumi:dev::shop::pulumi:providers:aws::default_6_50_0::0b8f8c2d-....",
        "propertyDependencies": {},
        "created": "2026-05-04T09:12:40Z",
        "modified": "2026-05-04T09:12:40Z"
      }
    ]
  }
}

The important fields:

Field Meaning
urn Stable identity: stack, project, parent types, type, logical name
id The provider's ID (bucket name, instance ID); empty for components
custom true for provider-backed resources, false for components
inputs What your program asked for last time
outputs What the provider reported back (all properties, including computed)
parent, provider Tree position and which provider instance manages it
dependencies, propertyDependencies Ordering edges used for create and delete order
protect, retainOnDelete, pendingReplacement, delete Flags that change what updates may do

Inputs versus outputs

The two property bags are the heart of Pulumi's diffing. inputs are what you specified; outputs are everything the provider knows after the call, including values it computed (ARN, creation time). On pulumi up the engine compares your new inputs with the old inputs in state. If they match, nothing happens, without calling the cloud. This is fast, but it is also why changes made behind Pulumi's back are invisible until you run pulumi refresh, which re-reads the cloud and updates outputs (and inputs to match). See Refresh and Drift.

Dependencies drive order

Each resource lists what it depends on: parents, providers, explicit dependsOn and every resource whose output it used. The engine builds a graph, creates resources in dependency order (many in parallel) and deletes in reverse order.

flowchart LR
  VPC["VPC"] --> Subnet["Subnet"]
  VPC --> SG["Security group"]
  Subnet --> Inst["Instance"]
  SG --> Inst
  Inst --> EIP["Elastic IP"]

Create left to right; delete right to left. Independent branches run in parallel.

Secrets in state

Values marked secret are stored encrypted. In the JSON they appear as an object with a fixed signature key and a ciphertext, never as plain text:

JSON
"password": {
  "4dabf18193072939515e22adb298388d": "1b47061264138c4ac30d75fd1eb44270",
  "ciphertext": "v1:abc123...:def456..."
}

Which key decrypts them depends on the stack's secrets provider (Pulumi Cloud service, passphrase, or a cloud KMS). See Backends and Login. Use pulumi stack export --show-secrets only when you truly need the plaintext, because it prints secrets to your terminal.

Stand-in: a tiny diff engine

The real engine is much richer, but the core loop is: for each desired resource, find the old one by URN and compare inputs; whatever is left in old state gets deleted. This stand-in prints a plan like pulumi preview, with replace for a change to an immutable property.

Node.js Stand-in: plan = diff(desired, recorded)

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.

Experiment: change the bucket input of assets and watch the plan become a replacement. Real providers decide this per property, and pulumi preview --diff shows exactly which property forces it.

Stand-in: dependency order

Create and delete orders come from the same graph. This version uses Kahn's algorithm and reverses the result for destroy.

Node.js Stand-in: create and destroy order

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.

Why state is precious

  • Lose it and Pulumi forgets everything. The cloud resources still exist, but the next up would try to create them again. Back up and use a backend with versioning.
  • Never edit it by hand while others deploy. Use pulumi stack export, edit carefully, then pulumi stack import, and only with the lock held. Prefer the dedicated commands in Import and State Surgery.
  • Treat it as sensitive. Even encrypted, state contains resource IDs, endpoints and configuration.
  • Each stack has its own state. dev and prod never share a checkpoint.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Pulumi compare to decide whether a resource needs an update?

    The engine diffs new inputs against recorded inputs. Differences made directly in the cloud are only noticed after a refresh.
  2. 2. What is the difference between a resource's inputs and outputs in state?

    Inputs record the request; outputs hold everything the provider returned, such as ARNs and generated IDs.
  3. 3. How do secret values appear in an exported checkpoint?

    Secrets are stored encrypted with the stack's secrets provider, as an object with a ciphertext.
  4. 4. In what order does Pulumi delete resources in a destroy?

    Resources that depend on others are deleted first, so a subnet is deleted before its VPC.

Summary

  • State is a per-stack JSON checkpoint of every resource: URN, ID, inputs, outputs, parent, provider and dependencies.
  • pulumi up diffs new inputs with recorded inputs; refresh brings recorded state in line with the cloud.
  • Dependencies come from parents, providers, dependsOn and output usage; they set create and delete order.
  • Secrets are encrypted in state according to the stack's secrets provider.
  • Protect state: back it up, restrict access and change it only with supported commands.

Next: Backends and Login: Where State Lives