pulumi-preview

Show a preview of updates to a stack's resources

$ pulumi preview

$ pulumi preview [[-j|--json]]

$ pulumi preview --diff

$ pulumi preview --policy-pack [path/to/directory]

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

pulumi preview [stack-name] [options...]

--stack
    Operates on a specific Pulumi stack by name. If omitted, the currently selected stack is used.

--target
    Specify a URN (Uniform Resource Name) of a resource to target for the preview. Only changes related to this resource will be shown.

--target-dependents
    If used with --target, also include changes to resources that depend on the specified target resource(s).

--message
    Associates a descriptive message with the preview operation, often used for logging or auditing.

--diff
    Shows full property-level diffs of resource changes, providing a detailed breakdown of what will be modified.

--expect-no-changes
    Causes the command to exit with an error if any changes are proposed during the preview, useful for CI/CD pipelines to ensure idempotency.

--refresh
    Refreshes the state of the stack from the cloud provider before performing the preview, ensuring the most accurate comparison.

--json
    Emits the preview output in JSON format, facilitating programmatic consumption and integration with other tools.

--non-interactive
    Disables interactive prompts, making the command suitable for automated scripts and CI/CD environments.

--policy-pack
    Specifies a policy pack to apply during the preview, allowing early detection of policy violations against your infrastructure plan.

--color
    Controls colorization of the output. Modes include 'auto', 'always', or 'never'.

--show-replacement-steps
    Displays detailed steps involved when a resource needs to be replaced, highlighting destructive actions.

The pulumi-preview command provides a 'dry run' of your Pulumi program, showing exactly what infrastructure changes Pulumi intends to make without actually applying them. It calculates the desired state of your infrastructure based on your code and compares it against the current state of your cloud resources, producing a detailed plan of proposed additions, modifications, and deletions. This command is an essential safety and planning tool, enabling developers and operators to review potential impacts, identify errors early, and ensure that infrastructure updates align with expectations before committing to any deployments. The output typically includes a comprehensive diff, highlighting property-level changes for each resource.

While pulumi-preview provides a robust forecast, it doesn't guarantee a completely successful pulumi up. Runtime issues, transient cloud provider errors, or external service limitations are not always predictable. Furthermore, the preview primarily reflects declarative changes and might not fully capture side effects of custom code within Pulumi programs or external system interactions that occur only during actual deployment.

pulumi-preview serves as an early gate for policy enforcement. By integrating with Pulumi Policy as Code, it can automatically run policy checks against your proposed infrastructure changes. This enables you to catch compliance violations, security misconfigurations, or cost inefficiencies before they are deployed, ensuring that your infrastructure adheres to organizational standards from the very beginning of the deployment lifecycle.

Pulumi emerged in 2018 as an Infrastructure as Code (IaC) solution, distinguishing itself by enabling infrastructure definition using general-purpose programming languages. From its inception, the pulumi-preview command has been a cornerstone feature, embodying Pulumi's dedication to safe and transparent infrastructure management. It has consistently allowed users to meticulously inspect proposed infrastructure changes before they are committed, significantly reducing deployment risks and enhancing developer confidence.

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