pulumi-import

Generate the resource definition with a given name for an existing provider resource

$ pulumi import [type_token] [name] [id]

$ pulumi import aws:iam/user:User [my_user_resource] [id]

$ pulumi import cloudflare:index/workersScript:WorkersScript [my_worker_script] [account_id/script_name]

$ pulumi import --file [path/to/file.json] --out [path/to/file]

pulumi import <resource_type_token> <resource_id> [--file <path>] [--parent <urn>] [--stack <stack_name>] [--yes] [options]

<resource_type_token>
    The type token or URN of the resource to import (e.g., aws:s3/bucket:Bucket for an S3 bucket, or a full URN).

<resource_id>
    The unique identifier of the existing resource in the cloud provider (e.g., 'my-unique-bucket-name' for an S3 bucket).

--file <path>
    Specify the path to the Pulumi program file where the generated resource code will be inserted. If omitted, the command typically prints the generated code to stdout.

--parent <urn>
    The URN of an existing parent resource to associate the imported resource with, helping to organize the resource hierarchy.

--stack <stack_name>
    The name of the Pulumi stack to perform the import operation in. Defaults to the currently selected stack.

--yes
    Skip confirmation prompts and proceed directly with the import operation.

--protect
    Mark the imported resource as protected, preventing accidental deletion via subsequent Pulumi updates.

--message <message>
    An optional message to associate with the import operation, visible in the Pulumi history.

pulumi-import is a crucial subcommand within the Pulumi CLI that enables users to bring existing infrastructure resources, provisioned outside of Pulumi, under Pulumi's management. This is invaluable for adopting Pulumi in brownfield environments where infrastructure already exists. The command connects to a cloud provider (e.g., AWS, Azure, GCP, Kubernetes) and retrieves the details of a specified resource using its type token and ID. It then attempts to generate the corresponding Pulumi code (in the chosen language of the project, such as TypeScript, Python, Go, or C#) and records the resource's state in the current Pulumi stack's state file. The generated code typically represents a basic definition of the resource. After running pulumi-import, users must review the generated code, make any necessary adjustments or additions (e.g., adding outputs, properties, or child resources), and then run pulumi up. The pulumi up command reconciles the newly imported resource in the state with the actual cloud resource, ensuring that Pulumi now has full control and understanding of its configuration and lifecycle.

Importing resources is a multi-step process that requires careful attention. Not all resource types may be fully supported for import, or may require manual adjustments to the generated code. The pulumi import command only generates the code and updates the state; a subsequent pulumi up is required to reconcile the state with the actual cloud resource and confirm its successful import. Always review the generated code and the plan presented by pulumi up before confirming changes. It is advisable to back up your state file or work in a controlled environment before performing complex imports.

The typical import workflow involves:
1. Identify the resource: Determine the exact type token (e.g., aws:ec2/instance:Instance) and the ID of the resource you wish to import.
2. Run pulumi import: Execute the command with the resource type and ID, optionally specifying a file to write the code to.
3. Review generated code: Examine the code output by pulumi import. It's often a basic representation. You may need to add more properties, outputs, or structure.
4. Run pulumi up: After adjusting the code, run pulumi up to reconcile the state. Pulumi will compare the imported state with your code and perform any necessary updates to align them (often a no-op if the code matches the imported state perfectly, or a refresh of properties).

To import a resource, you need its Pulumi resource type token and its unique cloud provider ID.
Type Tokens: These can be found in the Pulumi documentation for the specific provider (e.g., Pulumi AWS documentation for aws:s3/bucket:Bucket).
Resource IDs: These are the native IDs assigned by the cloud provider. For example, an AWS S3 bucket's ID is its name; an EC2 instance's ID is its instance ID (i-xxxxxxxxxxxxxxxxx); an Azure Storage Account's ID is its name. These are typically visible in the cloud provider's console or via their CLI.

The pulumi-import command was introduced as a pivotal feature to address the challenges of managing existing infrastructure with Pulumi. In earlier stages of Pulumi's development, bringing existing resources under management often involved manual state manipulation or writing code from scratch and then performing a refresh. The introduction of pulumi-import significantly streamlined this 'brownfield' adoption scenario, making it easier for organizations with pre-existing cloud deployments to transition to Infrastructure as Code with Pulumi. It has undergone continuous improvements to support a wider range of resources and improve the accuracy of generated code.

pulumi(1), pulumi up(1), pulumi state(1), pulumi refresh(1)