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 [[-s|--stack]] [stack_name]

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

pulumi refresh [STACK_NAME] [options]

--stack, -s <STACK_NAME>
    Specify the stack to refresh. If omitted, the currently selected stack is used.

--message, -m <MESSAGE>
    A message to associate with the refresh operation in the history.

--target <URN>
    Specify a URN (Uniform Resource Name) of a resource to refresh. Only this resource will be checked for drift. Can be specified multiple times.

--target-dependents
    Refresh dependents of a --target resource as well. Use with --target.

--skip-preview
    Skip the refresh preview and proceed directly to applying the state changes without confirmation.

--non-interactive
    Disable interactive prompts, useful for automation and scripting.

--config <KEY=VALUE>
    Set a configuration value for the refresh, overriding stack config values.

--config-file <PATH>
    Use a specific configuration file instead of the default 'Pulumi..yaml'.

--json
    Emit output as JSON. Useful for programmatic consumption of refresh results.

--color <auto|always|never>
    Customize output colorization for the console.

--debug
    Enable debug logging, providing more verbose output for troubleshooting.

--logtostderr
    Force logging to stderr instead of files.

--tracing <ENDPOINT>
    Enable OpenTracing for detailed performance analysis.

pulumi refresh is a command within the Pulumi Infrastructure as Code (IaC) framework designed to synchronize the Pulumi state file with the actual deployed cloud resources. Unlike pulumi up, which applies changes from your code to the cloud, pulumi refresh inspects the live cloud environment and updates Pulumi's internal state to accurately reflect any changes that may have occurred outside of Pulumi's management.

This process is crucial for detecting and rectifying "drift," where the actual infrastructure diverges from the expected state defined in your Pulumi program. The command performs a dry run by querying the current status of all resources managed by the stack. If it finds resources that have been manually modified, deleted, or added out-of-band, it will update the state file accordingly.

For example, if a resource was deleted directly in the cloud console, pulumi refresh will remove that resource from the Pulumi state, effectively "forgetting" about it. If a resource's properties were changed manually, refresh will update the state to reflect these new properties. It's an essential tool for maintaining the integrity of your Pulumi state, ensuring that subsequent pulumi up operations start from a correct understanding of the existing infrastructure, preventing unintended destructive actions or misleading previews.

While pulumi refresh itself does not modify cloud resources, it does modify the Pulumi state file. This modification can be significant: if resources have been deleted out-of-band, refresh will remove them from the state, meaning Pulumi will no longer manage them. If properties were changed externally, the state will be updated to reflect those changes, which could lead to unexpected behavior if subsequent pulumi up operations are run without understanding these state shifts. Always review the refresh plan carefully before confirming, especially in production environments, to ensure the proposed state changes align with your expectations.

pulumi refresh is the primary mechanism for detecting 'drift' in your infrastructure. Drift occurs when the actual state of your cloud resources deviates from the state recorded in your Pulumi program and state file. Running refresh regularly can help identify and resolve these discrepancies before they cause issues with subsequent deployments or system behavior, maintaining the integrity of your IaC pipeline.

After a successful pulumi refresh, subsequent pulumi up commands will operate on the updated state. If refresh removed resources from the state (e.g., they were deleted manually from the cloud), pulumi up will no longer attempt to manage or recreate them. If properties were updated, pulumi up might then attempt to correct them back to the desired state in your code (if the code specifies that property), or simply acknowledge the change if the code is flexible.

Pulumi, launched in 2018, revolutionized Infrastructure as Code by enabling developers to define cloud infrastructure using general-purpose programming languages (like TypeScript, Python, Go, C#, Java, YAML). The pulumi refresh command was an integral part of the CLI from early stages, addressing the critical need for state synchronization in dynamic cloud environments. Its development reflects Pulumi's commitment to providing robust tools for managing infrastructure drift and maintaining a single source of truth for cloud resources, evolving alongside the core Pulumi engine to support new cloud providers and resource types. It ensures that the declared intent in code remains aligned with the actual deployed cloud infrastructure.

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