pulumi/pulumi

State management

Active contributors: Thomas Gummerer, Ian Wahbe, Justin Van Patten, Fraser Waters

Purpose

Sometimes the snapshot drifts from reality: a resource gets deleted out-of-band, a refactor renames a URN, a stack needs to be repaired after a half-finished update. Pulumi exposes a small toolbox of state-editing commands so users don't need to hand-edit JSON.

Commands

The user-visible surface is pulumi state and pulumi stack:

Command	Purpose
`pulumi stack export [--file]`	Serialize the snapshot to JSON
`pulumi stack import [--file]`	Replace the snapshot from JSON
`pulumi stack history`	Update history
`pulumi stack output`	Read stack outputs
`pulumi state delete <urn>`	Remove a resource from the snapshot (does not touch the cloud)
`pulumi state rename <urn> <new-name>`	Rename without replace — adds an alias
`pulumi state move <urn> --dest=<other-stack>`	Cross-stack move
`pulumi state unprotect <urn>`	Clear the protect flag
`pulumi state edit`	Open the snapshot in $EDITOR (atomic write-back)
`pulumi state upgrade`	Migrate snapshot to the latest format

Where it lives

Concern	Path
CLI commands	`pkg/cmd/pulumi/state/`
Stack-level commands	`pkg/cmd/pulumi/stack/`
Underlying surgery	`pkg/resource/edit/`
Snapshot persistence	`pkg/backend/snapshot.go`, `pkg/backend/journal.go`, `sdk/go/common/resource/snapshot.go`
Backend `Apply`/`Edit` glue	`pkg/backend/state/`
Integrity check	`pkg/resource/deploy/analyze_snapshot.go`, `pkg/backend/validating_persister.go`

How `pulumi state` operations work

graph TD
    Cmd[pulumi state delete urn] --> Backend[Backend.GetStack]
    Backend --> Lock[Acquire snapshot lock]
    Lock --> Load[Load current snapshot]
    Load --> Edit[pkg/resource/edit operations]
    Edit --> Validate[Snapshot.VerifyIntegrity]
    Validate --> Persist[validating_persister.Save]
    Persist --> Release[Release lock]

Every state edit:

Locks the stack against concurrent updates.
Loads the current snapshot.
Applies the edit using the immutable state_builder pattern.
Validates integrity (no dangling parents, providers exist, no duplicate URNs).
Persists via the validating persister, journaled where applicable.
Releases the lock.

If integrity validation fails, the original snapshot is preserved unchanged.

Common workflows

Adopt a manually-deleted resource back into Pulumi

A user deleted an S3 bucket via the AWS console. Pulumi still has it in state.

pulumi refresh                    # marks it as gone (snapshot updated)
# or, if you prefer:
pulumi state delete <urn> --force # drop it explicitly

Rename a resource without replacing it

pulumi state rename <old-urn> <new-name>
# Or, in code: add an alias and rename in source

Move a resource to another stack

pulumi state move urn:... --dest=other-stack
# The destination stack inherits the resource; the source stack drops it.

Recover from a half-finished update

Pulumi already keeps a journal (pkg/engine/journal_snapshot.go). On the next CLI invocation it reapplies pending journal entries. If that fails:

pulumi stack export > stack.json     # backup
$EDITOR stack.json                   # surgical edit
pulumi stack import < stack.json

Unprotect a resource

pulumi state unprotect <urn>
pulumi destroy

Protect: true is what blocks pulumi destroy from removing a critical resource; clear it to proceed.

Snapshot format compatibility

pulumi state upgrade migrates older snapshots to newer formats. Format versioning is in sdk/go/common/apitype/:

The DeploymentV<N> types are the on-disk shape.
Snapshot.VerifyIntegrity runs on every load to catch corruption early.
DIY backend keeps the legacy form readable for backwards compatibility (pkg/backend/diy/backend_legacy_test.go).

Pending operations

If pulumi up is interrupted (Ctrl-C, network failure), the snapshot can have pending operations — resources that were mid-Create or mid-Delete. These show up in pulumi stack export:

{
  "pendingOperations": [
    {
      "resource": { "urn": "urn:pulumi:..." },
      "type": "creating"
    }
  ]
}

The next pulumi up will:

For creating: try to import or recreate.
For updating: re-run the update.
For deleting: re-attempt the delete.

Sometimes the pending operation can't be resolved (e.g. the create call returned an opaque error). pulumi stack export | $EDITOR | pulumi stack import is the escape hatch.

Entry points for modification

A new state subcommand — pkg/cmd/pulumi/state/. Mirror an existing simple command.
A new edit primitive — pkg/resource/edit/. Used both by the CLI and by Automation API state surgery.
Snapshot format change — bump the format version in sdk/go/common/apitype/, write a migrator in pulumi state upgrade, keep the previous version readable.