Deployment Commands

Relevant source files

The following files were used as context for generating this wiki page:

• pkg/cmd/pulumi/operations/up.go
• pkg/cmd/pulumi/operations/preview.go
• pkg/cmd/pulumi/operations/destroy.go
• pkg/cmd/pulumi/operations/refresh.go
• pkg/engine/deployment.go
• pkg/cmd/pulumi/deployment/remote.go
• sdk/go/common/apitype/deployments.json
• pkg/resource/deploy/doc.go

Deployment commands are the core user-facing tools in the Pulumi CLI for managing the lifecycle of infrastructure resources within a stack. These commands—up, preview, destroy, and refresh—provide a comprehensive suite for creating, updating, viewing, and deleting cloud resources. They work by running a Pulumi program to compute a desired goal state, comparing it with the stack's last known state, and then planning and executing the necessary operations to align the deployed infrastructure with the code.

The deployment system is designed to be transactional and robust, recording snapshots of the stack's state after each successful update. This allows for incremental changes and reliable management of complex infrastructure. The commands are orchestrated by the engine package, which handles the deployment lifecycle, and they interact with a configured backend for state storage.

Sources: pkg/resource/deploy/doc.go, pkg/cmd/pulumi/operations/up.go:278-292, README.md:100-120

Core Commands

The primary commands for managing a stack's deployment are up, preview, destroy, and refresh.

pulumi up

The pulumi up command is used to create or update resources in a stack to match the desired state defined in the Pulumi program. It computes a minimal set of changes required and presents them for approval before making any modifications to the infrastructure.

Execution Flow

The command has two primary execution paths, determined by whether a template argument is provided.

1. Working Directory (upWorkingDirectory): This is the standard flow where pulumi up is run within an existing Pulumi project directory.
2. Template (upTemplateNameOrURL): When a template name or URL is provided, Pulumi creates a temporary project, deploys it, and then cleans up, leaving only the stack state.

The diagram below illustrates the high-level logic of the pulumi up command.

In both paths, the final step is to invoke backend.UpdateStack, which orchestrates the deployment engine to perform the update. This involves:

1. Reading the project and stack configuration.
2. Gathering update metadata.
3. Creating engine.UpdateOptions from command-line flags.
4. Executing the deployment plan, which may include a preview step.
5. Handling any errors or cancellations.

Sources: pkg/cmd/pulumi/operations/up.go:132-200

pulumi preview

The pulumi preview command shows a plan of the changes that pulumi up would make without actually performing the update. It is a dry-run mode that is useful for inspecting potential changes before applying them.

The internal flow is nearly identical to pulumi up, but it sets the previewOnly flag to true when constructing the update options. This instructs the backend to stop after the preview phase.

A key feature of preview is the ability to save the generated plan to a file using the --save-plan flag. This plan file can then be passed to pulumi up --plan <file> to execute the exact changes that were previewed, ensuring that no unexpected changes occur between preview and update.

Sources: pkg/cmd/pulumi/operations/preview.go:52-124

pulumi destroy

The pulumi destroy command tears down all resources managed by a stack. It is a destructive operation that will delete infrastructure.

The process is as follows:

1. The stack is loaded.
2. The user is prompted for confirmation.
3. engine.DestroyOptions are created from command-line flags.
4. The backend.DestroyStack function is called, which orchestrates the deletion of all resources in the stack's last known state.

Unlike up and preview, destroy does not typically run the Pulumi program, as it operates on the existing state file.

Sources: pkg/cmd/pulumi/operations/destroy.go:50-108

pulumi refresh

The pulumi refresh command compares the current state of the stack with the actual resources in the cloud and updates the state file to match reality. This is useful if resources have been changed manually outside of Pulumi (a practice known as "drift").

The process involves:

1. Loading the stack.
2. Creating engine.RefreshOptions.
3. Calling backend.RefreshStack, which queries the cloud provider for the status of each resource in the state file and updates the state accordingly.

Sources: pkg/cmd/pulumi/operations/refresh.go:49-99

Common Deployment Options

Most deployment commands share a common set of command-line flags that control their behavior. These flags are used to populate the backend.UpdateOptions and engine.UpdateOptions structs that configure the deployment engine.

Flag	Description	Relevant Files
-s, --stack <name>	Specify the stack to operate on.	up.go, preview.go, destroy.go, refresh.go
-j, --json	Serialize all output as JSON.	up.go, preview.go, destroy.go, refresh.go
-m, --message <msg>	A message to associate with the update operation.	up.go, preview.go, destroy.go, refresh.go
-t, --target <urn>	Target a specific resource URN for the operation.	up.go, preview.go, destroy.go, refresh.go
--exclude <urn>	Exclude a specific resource URN from the operation.	up.go, preview.go, destroy.go
--replace <urn>	Specify a resource URN to be replaced.	up.go, preview.go
-y, --yes	Automatically approve the preview and perform the update.	up.go, preview.go, destroy.go, refresh.go
-p, --parallel <N>	Set the number of resource operations to run in parallel.	up.go, preview.go, destroy.go, refresh.go
-r, --refresh	Refresh the state of resources before the operation.	up.go, preview.go, destroy.go
--policy-pack <path>	Run one or more policy packs during the update.	up.go, preview.go
--plan <path>	For up, use a plan file. For preview, save the plan.	up.go, preview.go
--skip-preview	Skip the preview step before an update.	up.go

Sources: pkg/cmd/pulumi/operations/up.go:610-745, pkg/cmd/pulumi/operations/preview.go:132-212, pkg/cmd/pulumi/operations/destroy.go:110-155, pkg/cmd/pulumi/operations/refresh.go:101-131

Remote Deployments

Pulumi supports running deployments remotely via the Pulumi Cloud backend. This is triggered by the --remote flag. Instead of executing the Pulumi engine locally, the CLI packages a request and sends it to the Pulumi Cloud, which then orchestrates the deployment in a managed environment.

Key Components:

• RemoteArgs Struct: This struct in pkg/cmd/pulumi/deployment/remote.go holds all the configuration for a remote deployment, such as Git source information, environment variables, and execution options.
• RunDeployment Function: This is the main entry point for kicking off a remote deployment. It validates flags, constructs an apitype.CreateDeploymentRequest, and calls the backend to initiate the job.
• Pulumi Cloud Backend: The backend receives the request, queues a deployment job, and streams logs back to the local CLI.

Sources: pkg/cmd/pulumi/deployment/remote.go:118-283, pkg/cmd/pulumi/operations/up.go:449-470

The following sequence diagram illustrates the remote deployment process.

Deployment State Schema

The state of a deployment is captured in a structured format, defined by a JSON schema. This state is what Pulumi uses to understand the current status of all resources under management.

The root of the deployment state object contains a version, a set of required features, and the main deployment object.

Key entities in the schema include:

• Deployment: The top-level object.
• DeploymentV3: The structure for version 3 of the deployment state.
• ManifestV1: Metadata about the deployment, including timestamps and plugin versions.
• ResourceV3: The state of an individual resource, including its URN, type, ID, inputs, and outputs.

This structured state is critical for Pulumi's ability to perform comparisons and generate accurate deployment plans.

Sources: sdk/go/common/apitype/deployments.json

Conclusion

The deployment commands are the engine of the Pulumi CLI, providing the essential functionality for infrastructure as code. They offer a flexible and powerful interface for managing resources, whether running locally from a project directory, from a template, or orchestrated remotely through the Pulumi Cloud. The transactional nature of these commands, backed by a well-defined state schema, ensures that infrastructure can be managed reliably and predictably throughout its lifecycle.

Sources: pkg/resource/deploy/doc.go, pkg/engine/deployment.go:20-26