pulumi-refresh

Compare the current stack's state with the state in the cloud provider and adopt any changes into the current stack

$ pulumi refresh

$ pulumi refresh --diff

$ pulumi refresh --expect-no-changes

$ pulumi refresh --preview-only

$ pulumi refresh --stack [stack_name]

$ pulumi refresh --help

pulumi refresh [flags]

--color string
    Colorize output. Choices are: always, never, raw, auto.

--config stringArray
    Configuration to use during the refresh.

--config-file stringArray
    Path to the configuration file to use during the refresh.

--diff
    Display diff of changes during refresh.

--expect-no-changes
    Return an error if any changes occur during this refresh.

--from string
    Run the refresh from the given checkpoint (e.g. "@v1").

--message string
    Attach a message to the refresh.

--parallel int
    Allow P resource operations to run in parallel at once (1 for no parallelism). Defaults to unbounded.

--policy-pack stringArray
    Run one or more policy packs as part of this refresh.

--policy-pack-config stringArray
    Path to the policy pack configuration file to use during the refresh.

--secrets-provider string
    The type of the provider that should be used to encrypt and decrypt secrets (valid choices are: default, passphrase, cloud, azurekeyvault, awskms, gcpkms, hashivault).

--show-reads
    Show reads in the CLI output.

--skip-pending-creates
    Skip resources that are pending creation from refresh.

--stack string
    The name of the stack to use.

--suppress-outputs
    Suppress display of stack outputs (in case they contain sensitive values).

--target stringArray
    Only perform resource operations on the given resource names.

--target-dependents
    Allows targeting of dependent resources when using --target.

-y, --yes
    Automatically approve and perform the refresh after previewing it.

The `pulumi refresh` command compares your Pulumi state with the actual resources existing in your cloud provider. This reconciliation process identifies discrepancies, such as resources created outside of Pulumi, manual modifications, or resources deleted without Pulumi's knowledge. The refresh operation updates the Pulumi state to accurately reflect the current infrastructure. This ensures that subsequent Pulumi operations, like deployments or destroys, operate on an up-to-date view of your resources. It is crucial for maintaining the integrity of your infrastructure-as-code managed by Pulumi, especially when dealing with environments that might experience external changes. Regular refreshing helps prevent unexpected issues and discrepancies between your desired state and the actual infrastructure. When discrepancies are found, pulumi stores these changes in the state file, but does not modify the underlying resources. These stored changes can be previewed using `pulumi preview` and applied using `pulumi up`.

The refresh operation can potentially take a long time, especially for large and complex infrastructures, as it needs to inspect each resource in your Pulumi stack. Always review the changes identified by the refresh operation before performing a `pulumi up` to ensure that the planned modifications are intentional and expected.

Drift occurs when the real-world state of your infrastructure diverges from the state defined in your Pulumi program. This can happen due to manual changes, scripts executed outside of Pulumi, or other external factors.

`pulumi refresh` is designed to detect and mitigate drift. When drift is detected, Pulumi will update its state file to reflect the current reality. After a refresh, you can run `pulumi preview` to see the changes that would be applied by `pulumi up`, and then run `pulumi up` to reconcile your infrastructure.

Common use cases for `pulumi refresh` include:
Recovering from accidental manual changes: If someone accidentally modifies a resource outside of Pulumi, refresh can bring your state back into sync.
Integrating with existing infrastructure: When adopting Pulumi in an environment with pre-existing resources, a refresh helps to import the current state into Pulumi's management.
Auditing and compliance: Regular refresh operations can provide a way to audit and ensure your infrastructure matches your declared configuration.
Periodic Synchronization: Automating refresh operations on a scheduled basis can ensure ongoing state accuracy.

The `pulumi refresh` command was introduced as part of the core Pulumi functionality to address the challenges of drift and maintaining accurate infrastructure state. As infrastructure-as-code adoption grew, the need to reconcile the declared state with the actual state became increasingly important. `pulumi refresh` evolved alongside Pulumi's feature set to support various cloud providers, configuration options, and policy integrations.

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