Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท State and Backends

Import and State Surgery: Adopting Resources and Fixing State Safely

Bring existing cloud resources under Pulumi with pulumi import and the import option, then fix state with state delete, rename, move, protect and stack export or import.

Real projects rarely start from nothing. There is a bucket someone created in the console, a database that predates Pulumi, a stack whose resources must be split across two projects. This lesson covers the two toolkits for those situations: import (bring existing resources into state) and state surgery (carefully edit state itself).

Both need a real backend and cloud account, so commands are read-only. The stand-ins model a state file as JSON so you can practice the logic of each operation.

Importing existing resources

The pulumi import command

Terminal
pulumi import aws:s3/bucketV2:BucketV2 assets assets-3f9a1c2
#              ^ type token            ^ name ^ provider ID

This reads the real resource, adds it to state under the logical name assets, and prints the code that would describe it. You paste that code into your program. The type token is in the provider docs; the ID format is on each resource's "Import" section (a bucket uses its name; some resources use parent/child IDs).

To import many, write a JSON file and pass it in:

JSON
{
  "resources": [
    { "type": "aws:s3/bucketV2:BucketV2", "name": "assets", "id": "assets-3f9a1c2" },
    { "type": "aws:sqs/queue:Queue",       "name": "jobs",   "id": "https://sqs.eu-central-1.amazonaws.com/123456789012/jobs" }
  ]
}
Terminal
pulumi import --file resources.json --out imported.ts

The import resource option

You can also declare the import in code and let pulumi up do it:

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

If your inputs differ from the real resource, the preview shows what would change, so fix the code until the preview shows no update for that resource. Afterwards you may delete the import option (it only matters on the first run).

Import workflow

flowchart TB
  A["List resources to adopt"] --> B["pulumi import or import option"]
  B --> C["Paste generated code"]
  C --> D["pulumi preview: any changes?"]
  D -- "yes" --> E["Edit code until it matches reality"]
  E --> D
  D -- "no changes" --> F["Commit; now managed by Pulumi"]

Aim for an empty preview. A resource that Pulumi wants to modify right after import means your code does not describe it yet.

Tips:

  • Import small batches, and keep dependencies in mind (import the VPC before the subnets that reference it).
  • Generated code often includes read-only or default properties; remove those the provider computes.
  • Components are not imported; import their children and construct the component with matching names (or use aliases).
  • Resources created by Terraform can be converted in bulk with pulumi convert --from terraform plus an import, but verify by preview, never trust a mechanical conversion blindly.

State surgery

Sometimes state is wrong: a resource was deleted manually and refresh did not clean up, you renamed a logical name without an alias, or you are splitting a stack. The pulumi state commands change state without touching the cloud.

Command Effect
pulumi state delete <urn> Forget a resource (the cloud resource remains)
pulumi state delete <urn> --target-dependents Also forget resources that depend on it
pulumi state rename <urn> <new-name> Change the logical name in state
pulumi state move --source a --dest b <urn> Move resources between stacks or projects
pulumi state protect / unprotect <urn> Toggle the protect flag
pulumi state repair Fix a malformed checkpoint (dangling parent/dependency references)
pulumi stack export / import Dump and replace the whole checkpoint
pulumi state upgrade Move a local backend's state to the latest format

Rules of thumb:

  1. Back up first: pulumi stack export --file backup.json.
  2. Prefer a purpose-built command over hand-editing JSON.
  3. Always follow with pulumi preview and expect an empty diff (or exactly the diff you intended).
  4. Do not run surgery during a deployment. Hold the stack quiet, as locking cannot protect you from a coworker deploying from another branch.
  5. state delete does not destroy anything; it leaves an orphan in the cloud unless you later delete it manually or re-import it.

Renaming safely

Renaming a logical name in code normally means a replace. You have two safe options: add aliases in code (best, because it travels with the program through every stack) or pulumi state rename per stack (one-off). With aliases:

TypeScript
const assets = new aws.s3.BucketV2("static-assets", { /* ... */ }, {
  aliases: [{ name: "assets" }],
});

Stand-in: state as a document

State is JSON, so surgery commands are small functions. This stand-in implements delete, rename and protect checks on a toy checkpoint, and shows why deleting a resource that others depend on must be refused or cascade.

Node.js Stand-in: delete, rename and protect on a toy checkpoint

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.

The real state delete behaves the same way: it refuses to orphan dependents unless you say so, and refuses to delete a protected resource until you unprotect it. The extra safety checks are a feature.

Moving resources between stacks

Splitting one large stack into two ("network" and "app") is a common reason for surgery. The usual flow:

  1. Create the destination stack and project with the same provider configuration.
  2. pulumi state move --source org/shop/prod --dest org/network/prod <urn> ... to move the resources (and dependencies they reference).
  3. Move the matching code into the new project.
  4. Run pulumi preview in both stacks; both must show no changes.
  5. Replace direct references with a stack reference (see the earlier lessons on stack references).

Never copy resources by hand-editing two state files unless you have no alternative.

Stand-in: verifying "preview shows no changes" after an import

After importing, the check that matters is "does my code match reality?". This stand-in compares imported properties with the code's inputs and lists what a preview would change.

Node.js Stand-in: preview after import

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.

When to import and when to recreate

  • Import for anything with data or a stable identity: databases, buckets with content, DNS zones, certificates.
  • Recreate for cheap, stateless things you can safely rebuild.
  • Do not import resources another tool still manages. Two tools managing one resource fight each other.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does pulumi state delete <urn> do to the real cloud resource?

    State commands edit the checkpoint only. The resource keeps existing in the cloud as an orphan.
  2. 2. After a successful pulumi import and pasting the generated code, what should pulumi preview show?

    If the code matches the real resource, there is nothing to change. A diff means the code needs adjusting.
  3. 3. What is the safest way to rename a logical resource name across every stack?

    An alias travels with the program and applies in every stack, avoiding replacement.
  4. 4. What should you always do before state surgery?

    A backup lets you restore the checkpoint if the operation goes wrong.

Summary

  • pulumi import and the import option adopt existing resources; the goal is an empty preview afterwards.
  • pulumi state delete, rename, move, protect and repair change state only, never the cloud.
  • Back up with stack export before surgery, prefer dedicated commands and confirm with pulumi preview.
  • Aliases are the durable way to rename; they work in every stack.
  • Do not import resources that another tool still manages.

Next: Unit Testing Pulumi Programs with Mocks