pulumi-update

Update infrastructure to desired state

TLDR

View documentation for the original command

$ tldr pulumi up

--debug
    Enables verbose debug logging for the update operation.

--diff
    Display verbose diffs of all resource changes, showing property-level modifications.

--expect-no-changes
    Fails the update if any changes are detected, useful for CI/CD pipelines to ensure idempotency.

--json
    Emit output as JSON, suitable for programmatic consumption.

--logflow
    Log resource operations in a streaming fashion as they occur.

--message
    Associates a message with the update operation, which is recorded in the stack's history.

--parallel
    Controls the maximum number of concurrent resource operations. Default is 16.

--refresh
    Before performing the update, refresh the state of the stack to match the real world.

--skip-preview
    Skips the interactive preview step and proceeds directly to apply changes. Use with caution.

--stack
    Specifies the stack to operate on. If omitted, the currently selected stack is used.

--target
    Specifies a URN (Uniform Resource Name) of a resource to target for the update. Can be specified multiple times to target multiple resources.

--target-dependents
    When using --target, also updates resources that depend on the targeted resources.

--yes
    Skips prompts and proceeds directly to apply changes. Essential for non-interactive environments and automation.

--color
    Controls output coloring (auto|always|never).

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

DESCRIPTION

The pulumi update command is the core operation in the Pulumi workflow, used to deploy and synchronize your infrastructure with the desired state defined in your Pulumi program. When executed, Pulumi performs a "diff" operation, comparing the current state of your cloud resources (as recorded in the stack's state file) with the desired state expressed in your Pulumi code.

It then presents a preview of the proposed changes (creations, updates, or deletions of resources). Upon confirmation, pulumi update orchestrates the necessary API calls to your cloud provider (e.g., AWS, Azure, GCP, Kubernetes) to bring the infrastructure into alignment with your program.

This command is idempotent, meaning you can run it multiple times, and it will only apply changes if the desired state differs from the current deployed state. It's crucial for iterating on infrastructure designs, deploying new features, and patching existing deployments.

CAVEATS

pulumi update can make destructive changes (e.g., resource deletion or replacement). Always review the preview carefully before confirming.

Long-running updates can be interrupted due to network issues or other factors, potentially leaving the stack in an inconsistent state. Manual intervention or a subsequent pulumi refresh might be needed to resolve.

External changes to cloud resources (drift) that are not reflected in the Pulumi state file can lead to unexpected behavior during an update. A pulumi refresh before an update is often recommended to mitigate this.

WORKFLOW

The typical pulumi update workflow involves:
1. Preview: Pulumi first performs a preview to show proposed changes to your infrastructure.
2. Confirmation: It then prompts for confirmation (unless --yes is used).
3. Application: Upon confirmation, it applies the changes, creating, updating, or deleting resources as necessary.
4. Reporting: It reports the status of each resource operation, indicating success or failure.

ROLLBACKS AND STATE MANAGEMENT

Pulumi maintains a history of updates for each stack, which can be viewed with pulumi history.

In case of an issue or a failed update, Pulumi provides a pulumi rollback command to revert the stack's state to a previous successful update, helping to recover from deployment issues.

HISTORY

Pulumi was founded in 2017 with the vision of bringing modern software engineering practices, like general-purpose programming languages and familiar IDEs, to infrastructure as code (IaC). The pulumi update command has been central to this vision from the outset, serving as the primary mechanism for deploying and managing infrastructure.

It evolved to handle increasingly complex scenarios, including support for various cloud providers, policy enforcement, and detailed diffing, continuously enhancing the developer experience for IaC operations.