pulumi-state

Delete a resource from the current stack's state

$ pulumi state delete

$ pulumi state move [resource_urn] --dest [stack_name]

$ pulumi state rename

$ pulumi state repair

$ pulumi state edit --stack [stack_name]

$ pulumi state [[-h|--help]]

pulumi-state subcommand [arguments...] [options]

Common subcommands include:
pulumi-state delete <URN> [--force]
pulumi-state edit
pulumi-state import <type> <name> <ID> [--parent <parent-URN>]
pulumi-state rename <old-URN> <new-URN>
pulumi-state show [--URN <URN> | --id <ID>] [--json] [--plain]

<subcommand>
    The specific action to perform on the state file. Common subcommands include delete, edit, import, rename, and show.

--stack <name>
    Specify the stack to operate on. If omitted, the currently selected stack is used. This is a global Pulumi option applicable to state commands.

--json
    Emit output as JSON, suitable for programmatic consumption. Available for many subcommands, e.g., show.

--non-interactive
    Disable interactive prompts, useful for automation scripts where no user input is desired.

delete <URN>
    Remove a specific resource from the state file by its Uniform Resource Name (URN). This operation does not delete the actual cloud resource; it only removes Pulumi's tracking of it.

delete --force
    Used with the delete subcommand to skip confirmation prompts, allowing for non-interactive removal of resources from the state.

import <type> <name> <ID>
    Integrate an existing cloud resource into the Pulumi state file. This requires specifying the Pulumi resource type (e.g., aws:s3/bucket:Bucket), a logical name for the resource within your program, and its physical ID in the cloud provider.

show [--URN <URN> | --id <ID>]
    Display the detailed contents of the Pulumi state file. Can be used to view the entire state, or filtered to show details for a specific resource using its URN or its physical cloud ID.

edit
    Open the state file in an interactive text editor (typically vi, nano, or the editor defined by your EDITOR environment variable) for manual modification. Use with extreme caution as incorrect edits can corrupt the state.

The pulumi-state command is a crucial part of the Pulumi infrastructure-as-code (IaC) ecosystem, designed for managing and interacting with the Pulumi state file. This file acts as the authoritative record of your deployed cloud resources, mapping your desired infrastructure (as defined in your Pulumi program) to the actual resources provisioned in your cloud provider. The command provides a powerful set of subcommands to inspect, modify, and troubleshoot your deployment state.

It allows users to view resource details, remove resources from the state without affecting the cloud, import existing cloud resources into the state, and even edit the state file directly (with extreme caution). Proper management of the state file is essential for consistent and reliable infrastructure deployments, as it ensures that Pulumi can accurately track and manage your cloud environment, facilitating updates, rollbacks, and diff operations.

Directly editing the Pulumi state file using pulumi-state edit is highly risky and should only be performed by advanced users with extreme caution. Incorrect modifications can corrupt your state, leading to inconsistencies between your Pulumi program and your deployed cloud resources, potentially causing resource loss or unexpected deployments. The delete subcommand removes resources only from the state file, not from your cloud provider; the actual cloud resource will remain. Always ensure you have a backup of your state, especially when performing manual operations. Concurrent manual state edits by multiple users can also lead to state corruption.

Pulumi state can be stored in various backends, including the Pulumi Service (the default for new projects), local files, or cloud storage solutions like AWS S3, Azure Blob Storage, or Google Cloud Storage. The specific backend used for a stack is configured separately, and pulumi-state commands automatically interact with the currently configured backend for the selected stack.

While pulumi-state offers powerful tools for advanced scenarios and troubleshooting, it's generally best practice to manage your infrastructure through your Pulumi program (written in TypeScript, Python, Go, C#, Java, or YAML) and use commands like pulumi up, pulumi refresh, and pulumi destroy for routine operations. Direct manipulation of the state file should be reserved for specific, well-understood advanced operations, and always be done with a clear understanding of the implications and with appropriate backups.

The concept of state management has been fundamental to Pulumi since its inception around 2017. As an infrastructure-as-code platform, Pulumi relies on a robust state file to track and manage deployed cloud resources. The pulumi-state command suite was developed as an essential set of utilities to interact with this state file directly. It evolved to provide capabilities for inspecting, debugging, and performing surgical operations on the state, addressing advanced use cases and troubleshooting scenarios that go beyond typical pulumi up or destroy operations. Its importance grew as users needed finer control and visibility into their infrastructure's declared state.

pulumi(1), pulumi up(1), pulumi refresh(1), pulumi destroy(1)