Targeted updates

By default, pulumi up, pulumi preview, pulumi refresh, and pulumi destroy operate on the entire stack. The Pulumi engine compares the program’s desired state to the stack’s current state and reconciles every resource in one pass. This is the recommended workflow because it keeps the program and the deployed infrastructure in sync.

Sometimes you need finer control. You might want to deploy one new resource without touching anything else, force the replacement of a single resource, or run a wide update while skipping a resource that’s in a maintenance window. Targeted update flags let you narrow the set of resources an operation touches.

The flags at a glance

All flags that accept a URN can be passed multiple times.

Specifying resources

Targeted flags accept resource URNs. A URN identifies one resource uniquely and looks like this:

urn:pulumi:dev::my-project::aws:s3/bucket:Bucket::my-bucket

The segments are: stack name, project name, resource type, and resource name. To list the URNs in a stack, run:

pulumi stack --show-urns

Wildcards

Both --target and --exclude accept wildcards in URN patterns:

• * matches any characters within a single URN segment (it does not cross : separators).
• ** matches any characters across segments.

Quote wildcard patterns so your shell doesn’t expand them. A few examples:

# Match every resource whose name is "my-bucket", in any project or stack.
pulumi up --target 'urn:pulumi:**::**::**::my-bucket'

# Match every S3 bucket in the stack.
pulumi up --target 'urn:pulumi:dev::my-project::aws:s3/bucket:Bucket::*'

# Exclude every resource under the "drafts" component.
pulumi up --exclude 'urn:pulumi:**::**::**::drafts' --exclude-dependents

URNs without wildcards must match a resource’s URN character-for-character. Short resource names alone are not accepted.

How targeting interacts with the dependency graph

By default, --target operates only on the resources whose URNs you list. Resources that depend on a targeted resource — or that a targeted resource depends on — are left in their existing state.

When a targeted resource needs an input from a non-targeted resource (for example, the ID of a VPC it lives in), the engine uses the value stored in the stack’s state from the last update. This means your targeted update sees the recorded state of the wider stack, not what the program would produce if it ran end-to-end.

--target-dependents opts you into pulling dependent resources into the operation. For example, if you target a VPC and pass --target-dependents, every subnet, security group, and instance whose declaration depends on the VPC is also included.

pulumi destroy treats dependents more strictly than the other commands. If a targeted resource has dependents and you don’t pass --target-dependents, the operation fails: deleting the resource would leave the stack in an inconsistent state. Pass --target-dependents to destroy the resource and its dependents together.

When to use --target vs. --exclude

Use --target when you want to operate on a small number of resources and leave the rest of the stack alone. Use --exclude when you want to operate on most of the stack but skip a few resources.

For example, deploying a single new resource is straightforward with --target:

pulumi up --target 'urn:pulumi:dev::my-project::aws:s3/bucket:Bucket::new-bucket'

But updating a stack with a hundred resources while skipping a single database under maintenance is much cleaner with --exclude:

pulumi up --exclude 'urn:pulumi:dev::my-project::aws:rds/instance:Instance::primary-db'

If you instead used --target for that update, you would have to enumerate every resource you wanted to include.

Replacing a single resource

--target-replace is shorthand for --target <URN> --replace <URN>. It restricts the update to the named resource and forces Pulumi to delete and recreate it rather than updating it in place. Use it when you need to force a recreation of one resource without rolling the rest of the stack forward:

pulumi up --target-replace 'urn:pulumi:dev::my-project::aws:ec2/instance:Instance::web-server'

This is different from --replace, which forces replacement of the named resource but still reconciles the rest of the stack at the same time.

Per-command behavior

The flags work the same way across up, preview, refresh, and destroy, with a few differences worth knowing:

• pulumi preview is the safest way to experiment with targeting. It shows you what an up with the same flags would change, without applying anything. Preview a targeted update before running it.
• pulumi refresh with --target updates the state of only the listed resources from the cloud provider. This is useful when you suspect drift in one resource and don’t want to wait for a full-stack refresh.
• pulumi destroy with --target requires --target-dependents whenever the targeted resource has dependents in the stack. Without it, destroy aborts rather than leave dangling references in state.

Limitations and trade-offs

Targeted operations are useful, but they introduce risks that whole-stack operations don’t have:

• Drift between code and infrastructure. A targeted update applies only what its flags allow. Changes elsewhere in your program are deferred until the next full update. If the deferred changes are forgotten, the deployed stack will not match what the program describes.
• Stale inputs. When a targeted resource references a non-targeted resource, the engine uses the value in state from the last full update. If the non-targeted resource has changed in a way that the program now describes differently, the targeted resource may end up with stale input values.
• Skipped dependents. Without --target-dependents, a downstream resource keeps its old configuration even when an upstream resource changes. The next full update will surface those deferred changes.
• Interaction with --refresh. Passing --refresh alongside --target only refreshes the targeted resources before the update. Other resources are not refreshed, even if their state is stale.
• Interaction with update plans. A plan generated from a targeted preview only describes operations on the targeted resources. Applying that plan to a full pulumi up will fail because the plan and the program’s full goal state will not match. Generate plans from full-stack previews when you intend to apply them to full-stack updates. See Update plans for more.

If you find yourself reaching for targeted operations regularly, consider splitting the stack into smaller stacks instead. Smaller stacks give you the same locality without the drift risk — whole-stack operations on a smaller stack are safer than targeted operations on a large one. See Organizing projects and stacks for guidance.

Examples

Deploy a single new resource

You’ve added one new bucket to a large program and want to deploy only it:

pulumi up --target 'urn:pulumi:dev::my-project::aws:s3/bucket:Bucket::reports'

Pulumi will create the bucket and leave the rest of the stack untouched.

Destroy a component and everything under it

A component groups a feature’s resources together. To tear the whole feature down in one command, target the component and pass --target-dependents:

pulumi destroy \
  --target 'urn:pulumi:dev::my-project::myorg:feature:Drafts::drafts' \
  --target-dependents

Every child of the drafts component is destroyed alongside the component itself.

Skip a stateful resource during a wide update

You’re rolling out application changes across a stack but the primary database is in a maintenance window. Exclude it from the update:

pulumi up \
  --exclude 'urn:pulumi:dev::my-project::aws:rds/instance:Instance::primary-db'

Every other resource is reconciled. Run the same update without --exclude once the maintenance window closes to bring the database back in sync with the program.

Force recreation of one resource

A configuration value is baked into a resource at creation time and an in-place update won’t pick it up. Force the resource to be replaced without disturbing anything else:

pulumi up --target-replace 'urn:pulumi:dev::my-project::aws:ec2/instance:Instance::web-server'

See also

• pulumi up, pulumi preview, pulumi refresh, and pulumi destroy command references.
• Update plans for constraining an update to a pre-approved set of operations.
• Organizing projects and stacks for splitting infrastructure when targeted operations become routine.