How to use the command 'pulumi preview' (with examples)

The pulumi preview command is a versatile tool used within the Pulumi infrastructure as code platform. It allows developers and operators to preview changes that would be applied to a given stack, letting them understand what updates will occur before they apply them. This is especially useful for avoiding unintended modifications in cloud environments. The command can be used in various ways, tailored with different flags to present this information in formats that best suit the user’s needs.

Use case 1: Show a preview of updates to a stack’s resources

Code:

pulumi preview

Motivation:

This basic command is often the first step before applying any changes to your infrastructure stack. By using it, the user gains clarity on what resources are scheduled for addition, update, or deletion. It functions as a safeguard, ensuring no unexpected resource changes are accidentally compared to the current stack’s state. This can be of paramount importance in a production environment where unintended changes can have a cascading effect on services.

Explanation:

The command pulumi preview does not have any additional arguments in its basic form. It provides a summary view of all upcoming changes to the stack upon execution of a pulumi up command. Here, it efficiently communicates the proposed changes without making any, thus acting as a crucial step in the infrastructure management lifecycle.

Example output:

Previewing update (dev):

     Type                 Name                Plan
 +   pulumi:pulumi:Stack  my-project-dev      create
 ~   aws:s3:Bucket        mybucket            update

Resources:
    + 1 to create
    ~ 1 to update
    0 to delete

Use case 2: Show a preview of updates to a stack’s resources in JSON format

Code:

pulumi preview --json

Motivation:

Using the JSON output format is highly beneficial for automation processes within continuous integration/continuous deployment (CI/CD) pipelines. It enables the detailed informational output to be easily parsed and integrated into automated systems that might log, dissect, or even alert based on the data provided. When managing multiple services across environments, automated tooling becomes indispensable, and JSON is a universally accepted format that facilitates this integration.

Explanation:

The additional argument --json specifies that the output should be formatted in JSON, a structured format that is both machine-readable and human-readable, suitable for various integrations and logging practices.

Example output:

{
  "steps": [
    {
      "op": "create",
      "type": "pulumi:pulumi:Stack",
      "urn": "urn:pulumi:dev::my-project::pulumi:pulumi:Stack::my-project-dev"
    },
    {
      "op": "update",
      "type": "aws:s3:Bucket",
      "urn": "urn:pulumi:dev::my-project::aws:s3/bucket:Bucket::mybucket"
    }
  ],
  "summary": {
    "create": 1,
    "update": 1,
    "delete": 0
  }
}

Use case 3: Preview updates as a rich diff showing overall changes

Code:

pulumi preview --diff

Motivation:

The --diff argument provides a detailed diff for anyone who needs an in-depth understanding of the changes. This is especially useful for code reviews or when collaborating with team members to communicate precisely what has been altered at a granular level. It visually represents the changes like a code diff, helping users see exactly what lines or configuration items are affected without abstract summaries.

Explanation:

The --diff argument enhances the utility of the preview by breaking down modifications into a side-by-side comparison, showcasing both the current state and proposed changes. This mimics traditional diff tools, which developers find intuitive and straightforward for interpreting changes to their workspaces and systems.

Example output:

Previewing update (dev):

  pulumi:pulumi:Stack: (create)
    [urn=urn:pulumi:dev::my-project::pulumi:pulumi:Stack::my-project-dev]

  aws:s3:Bucket: (update)
    [id=mybucket]
    ~ region: "us-west-1" => "us-west-2"

Use case 4: Display help

Code:

pulumi preview --help

Motivation:

Running the --help flag is crucial for new users to learn about the command’s various options and for seasoned users to refresh their knowledge about its functionalities. This ensures efficient usage of the tool, helping users quickly understand all available functionality and adapting to changes or additions in newer versions.

Explanation:

The --help argument prompts the command-line interface to provide assistance documentation right within the terminal. This output typically includes explanations of all available options and a brief description of what each does, serving both learning and reference purposes.

Example output:

Show a preview of updates a stack's resources.

Usage:  pulumi preview [flags]

Flags:
  -d, --diff               Display operation as a rich diff
  -j, --json               Display operation as JSON

  --show-config            Show configuration keys and their values
  --show-replacement-steps Show detailed resource replacement steps
  --help                   Show help for 'preview' command

Conclusion:

Utilizing the pulumi preview command with its various flags can greatly enhance the efficiency of managing and deploying infrastructure changes. Each use case allows users to interact with potential updates in a way that best fits their operating environment, whether that means previewing changes in a simple list, detailed JSON, or comprehensive diff format, or just getting immediate help on usage. Mastery of these options drives better collaboration, ensures minimal disruption, and maintains constant insight into infrastructure evolution.