pulumi-stack

Create a new stack

$ pulumi stack init [stack_name]

$ pulumi stack [[-u|--show-urns]]

$ pulumi stack ls

$ pulumi stack ls [[-a|--all]]

$ pulumi stack select [stack_name]

$ pulumi stack rm [stack_name]

$ pulumi stack output --show-secrets

$ pulumi stack export --file [path/to/file.json]

pulumi stack [command] [options]

Common pulumi stack commands:

init [name] [--secrets-provider=type]
select [name] [--create]
ls [--all] [--json]
rm [name] [--force] [--yes] [--config-only]
rename [old-name] [new-name]
tag [add|rm|ls] [key] [value] [--json]
export [--file=path] [--json]
import [--file=path] [--force]
output [name] [--json] [--show-secrets]
graph
history

--all
    (Used with ls) Lists all stacks, including those not associated with the current project.

--create
    (Used with select) Creates the stack if it doesn't already exist when selecting it.

--cwd
    Runs the command in a different directory, useful for multi-project repositories.

--config-only
    (Used with rm) Only removes the stack's configuration and encrypted secrets from the project's Pulumi.yaml, not its state from the backend.

--file
    (Used with export, import) Specifies the file path for stack state operations.

--force
    (Used with rm, import) Forces the operation, e.g., removes a stack even if it's not empty, or overwrites an existing state file during import.

--json
    Emits output as JSON, useful for programmatic consumption.

--project
    (Used with ls) Only lists stacks associated with a specific project name.

--secrets-provider
    (Used with init) The type of secrets provider to use for the new stack (e.g., default, passphrase, awskms, azurekeyvault, gcpkms).

--show-secrets
    (Used with output) Displays stack outputs marked as secrets (use with caution).

--stack
    The name of the stack to operate on. If not specified, the currently selected stack is used.

--yes / -y
    (Used with rm) Skips confirmation prompts for destructive operations.

The pulumi-stack command is a fundamental part of the Pulumi CLI, designed for managing stacks. In Pulumi, a stack represents an isolated, independently configurable instance of your Pulumi program. You typically use different stacks for different deployment environments, such as development, staging, and production. Each stack maintains its own state file, tracking the cloud resources it manages, and has its own configuration values, including secrets.

pulumi-stack provides various subcommands to interact with these stacks. You can initialize new stacks (init), switch between existing ones (select), list all available stacks (ls), or remove them (rm). It also allows for advanced operations like renaming a stack (rename), adding or removing tags (tag), and exporting or importing stack state (export, import). The pulumi-stack command ensures that your deployments are isolated, preventing accidental changes across environments and enabling consistent, repeatable infrastructure provisioning. It's crucial for organizing your cloud infrastructure projects into distinct, manageable deployments.

• Data Loss Risk: Using pulumi stack rm can lead to permanent data loss if the stack's resources are not first destroyed via pulumi destroy. Using --force with rm will remove the stack even if it manages existing resources, potentially leaving orphaned infrastructure in your cloud account.
• State Management: Stacks rely on a backend to store their state. Issues with backend connectivity or permissions can prevent pulumi-stack from operating correctly.
• Secrets Handling: Stacks manage encrypted secrets. Ensure your secrets provider is correctly configured and accessible when working with sensitive stack configurations or outputs.
• Active Stack: Always be aware of which stack is currently selected (use pulumi stack ls to see the active stack) to avoid unintended operations on the wrong environment.

A Pulumi stack is an isolated instance of your infrastructure program. It manages a distinct set of cloud resources, its own configuration settings (including encrypted secrets), and its own state file, which tracks the deployed resources. This isolation is crucial for managing separate development, staging, and production environments without interference.

When you first initialize a Pulumi project with pulumi new, a default stack (often named dev or derived from the project name) is created and automatically selected. If no stack is explicitly selected for a subsequent Pulumi operation, the CLI will typically default to the currently active stack.

Each stack is configured with a secrets provider (e.g., passphrase, AWS KMS, Azure Key Vault, Google Cloud KMS). This provider is responsible for encrypting and decrypting sensitive configuration values and stack outputs, ensuring that secrets are not stored in plaintext within the state file, enhancing security.

Pulumi was founded in 2017 with a vision to enable developers to define, deploy, and manage cloud infrastructure using familiar programming languages. Stacks are a core concept introduced early in Pulumi's development, providing the necessary isolation and lifecycle management for different deployment environments. The pulumi-stack command set has evolved to offer robust control over these isolated deployments, reflecting the growing needs for infrastructure as code practices that support multiple environments and continuous delivery workflows.

pulumi(1), pulumi up(1), pulumi destroy(1), pulumi config(1)