pulumi/pulumi

Resource import

Active contributors: Fraser Waters, Ian Wahbe, Thomas Gummerer

Purpose

pulumi import brings an existing, already-provisioned cloud resource under Pulumi's management. It produces both a snapshot entry (so the engine knows the resource exists and what its inputs are) and source code (so the user's program declares it). After importing, subsequent pulumi ups treat the resource like any other.

Two forms:

CLI import — pulumi import aws:s3/bucket:Bucket my-bucket bucket-id-in-aws. Imports a single resource, prints generated source.
Bulk import — pass a JSON file with multiple resources. Useful for adopting a whole environment.
In-program import — declare a resource with {import: "<id>"}. The next up adopts it.

Where it lives

Concern	Path
CLI subcommand	`pkg/cmd/pulumi/import.go`-style code in `pkg/cmd/pulumi/pulumi.go`
Engine driver	`pkg/engine/import.go`
Engine logic	`pkg/resource/deploy/import.go` (~26 KB)
Step type	`ImportStep` in `pkg/resource/deploy/step.go`
Generated source emission	per-language in `pkg/codegen/<lang>/`
Snapshot side-channel	`pkg/resource/edit/`

What import does

sequenceDiagram
    participant U as User
    participant CLI as pulumi import
    participant Eng as Engine
    participant Prov as Provider

    U->>CLI: pulumi import <type> <name> <id>
    CLI->>Eng: ImportInfo
    Eng->>Prov: Read(type, id)
    Prov-->>Eng: full resource state (inputs + outputs)
    Eng->>Eng: emit ImportStep
    Eng->>Eng: write snapshot entry
    Eng-->>CLI: generated source code
    CLI->>U: prints code, suggests where to paste it

The provider's Read(id) is doing the heavy lifting: it must know how to inspect a resource by physical id and produce the canonical input set Pulumi wants.

The `ImportStep`

ImportStep is the engine's adoption mechanism. Unlike CreateStep, it does not call provider.Create — it just records the read state. To detect drift after import, run pulumi refresh (which emits RefreshSteps for every imported resource).

If you import with the wrong inputs (e.g. wrong region), the next pulumi up will replace the resource (because Diff says so). For this reason the import flow tries hard to give you working source code — get the source right and replace doesn't happen.

Generated source

pulumi import runs the same programgen machinery that powers pulumi convert. The provider's schema describes which fields are required vs optional; the generator emits idiomatic source in the chosen language. The source is not automatically inserted into your program — it's printed on stdout for you to review and paste.

For bulk imports, the file format is:

{
  "resources": [
    { "type": "aws:s3/bucket:Bucket", "name": "logs", "id": "my-logs-bucket" },
    { "type": "aws:s3/bucket:Bucket", "name": "data", "id": "my-data-bucket" }
  ]
}

Caveats

Some resources are not safely importable (e.g. things that require provider-side state). Provider authors mark these as non-importable in the schema.
Imported resources may have null for inputs that the provider chose defaults for. Generated source explicitly defaults these so a future up is a no-op.
The parent, provider, and dependencies arguments of the import resource option are honored; if you import a child of a component, get the parent right or you'll see Replace.

In-program import

new aws.s3.Bucket(
  'my-bucket',
  {
    bucket: 'existing-bucket-name',
  },
  { import: 'existing-bucket-name' }
);

The import resource option triggers an ImportStep instead of CreateStep. After the next successful up, you should remove the import option from the source — it's a one-shot adoption flag.

Entry points for modification

Adding a CLI flag — pkg/cmd/pulumi/pulumi.go import command, propagated through pkg/engine/import.go to pkg/resource/deploy/import.go.
Generating source for a new language — pkg/codegen/<lang>/gen_program.go already supports this; new languages follow the same pattern.
A new bulk-import format — pkg/resource/deploy/import.go reads the JSON; extend the schema there.