Pulumi Blog: Tom Harding

New in Pulumi IaC: `onError` Resource Hook

Tom Harding — Mon, 23 Feb 2026 00:00:00 +0000

You can now control what happens when a resource fails during create, update, or delete—retry with backoff, fail fast, or handle errors in custom code. Last year, Pulumi IaC introduced the resource hooks feature, allowing you to run custom code at different points in the lifecycle of resources. Today we’re adding the onError hook so you can react when operations fail.

Recovering from errors

When a Pulumi program encounters an error while creating, updating, or deleting a resource, the operation halts and the error is reported back. Sometimes that’s not what we want—errors can be intermittent or temporary. If you’ve hit transient failures or resource-not-ready errors, the onError hook can help.

A common case is resource readiness: creating resources that depend on DNS propagation or the readiness of other servers. The program can fail simply because it ran too soon. Instead of failing, we can wait and retry. The example below shows how:

import * as pulumi from "@pulumi/pulumi";

const notStartedRetryHook = new pulumi.ErrorHook(
 "retry-when-not-started",
 async (args) => {
 const latestError = args.errors[0] ?? "";

 if (!latestError.includes("resource has not yet started")) {
 return false; // do not retry, this is another type of error
 }

 await new Promise((resolve) => setTimeout(resolve, 5000));
 return true; // retry
 },
);

const res = new MyResource("res", {}, {
 hooks: {
 onError: [notStartedRetryHook],
 },
});

import time

import pulumi


def retry_when_not_started(args: pulumi.ErrorHookArgs) -> bool:
 latest_error = args.errors[0] if args.errors else ""

 if "resource has not yet started" not in latest_error:
 return False # do not retry, this is another type of error

 time.sleep(5)
 return True # retry


not_started_retry_hook = pulumi.ErrorHook(
 "retry-when-not-started",
 retry_when_not_started,
)

res = MyResource(
 "res",
 opts=pulumi.ResourceOptions(
 hooks=pulumi.ResourceHookBinding(
 on_error=[not_started_retry_hook],
 ),
 ),
)

package main

import (
 "strings"
 "time"

 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
 pulumi.Run(func(ctx *pulumi.Context) error {
 hook, err := ctx.RegisterErrorHook(
 "retry-when-not-started",
 func(args *pulumi.ErrorHookArgs) (bool, error) {
 latest := ""
 if len(args.Errors) > 0 {
 latest = args.Errors[0]
 }

 if !strings.Contains(latest, "resource has not yet started") {
 return false, nil // do not retry, this is another type of error
 }

 time.Sleep(5 * time.Second)
 return true, nil // retry
 },
 )
 if err != nil {
 return err
 }

 _, err = NewMyResource(ctx, "res", &MyResourceArgs{}, pulumi.ResourceHooks(&pulumi.ResourceHookBinding{
 OnError: []*pulumi.ErrorHook{hook},
 }))
 if err != nil {
 return err
 }

 return nil
 })
}

using System;
using System.Threading;
using System.Threading.Tasks;
using Pulumi;

class ErrorHookStack : Stack
{
 public ErrorHookStack()
 {
 var retryHook = new ErrorHook(
 "retry-when-not-started",
 async (args, cancellationToken) =>
 {
 var latestError = args.Errors.Count > 0 ? args.Errors[0] : "";

 if (!latestError.Contains("resource has not yet started"))
 {
 return false; // do not retry, this is another type of error
 }

 await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
 return true; // retry
 });

 var res = new MyResource("res", new MyResourceArgs(), new CustomResourceOptions
 {
 Hooks = new ResourceHookBinding
 {
 OnError = { retryHook },
 },
 });
 }
}

Each time the operation fails, the hook receives the new error plus all previous attempts’ errors (newest first). The hook returns true or false to tell Pulumi whether to retry. If you return false, the program fails as normal with the most recent error. With that information, you can implement many failure models:

Use the number of errors to implement backoff—for example, wait one second on the first failure, two seconds on the second, and so on.
For known-intermittent resources, always retry once before failing.
Inspect error text to retry only for specific conditions (as in the example) and fail fast for others.

The callback runs in your language of choice, so you have full control over how failures are handled.

Next steps

This feature is fully supported in our Node, Python, Go, and .NET SDKs as of v3.219.0. For more information, see the hooks documentation.

Java and YAML do not support resource hooks.

Thanks for reading, and feel free to reach out with any questions via GitHub, X, or our Community Slack.

New in Pulumi IaC: `replacementTrigger` Resource Option

Tom Harding — Thu, 22 Jan 2026 00:00:00 +0000

Pulumi IaC gives us a declarative interface to updates. When we perform an update, Pulumi calculates the difference between your currently deployed infrastructure and what is being proposed, then deploys only what is required to migrate from the old state to the new state. Normally, this is exactly what we want: we minimize the amount of work required to perform the update, and don’t recreate anything unnecessarily. However, every now and then, we want to override this behavior.

Recently, we talked about the new replaceWith option, which allows us to tell Pulumi that any replacement of one resource should always trigger a replacement of another (for example, if the database is replaced, we should replace our application server). Today, we’re going to take this idea one step further and talk about another new feature that gives us even more control over this process: replacement triggers.

Forcing replacements

Let’s imagine we have a resource that, upon creation, generates some private keys. If that’s all the resource does, it probably isn’t ever going to change as far as Pulumi’s concerned: we wanted the resource before, and we want it after, so there is no change and no need to replace the resource that is already live. Now, let’s imagine that we want to cycle these private keys every month. How do we tell Pulumi that, if this update happens more than two weeks after the last time this resource was created, we want to recreate it?

As another example, perhaps we want to replace a resource every time some external version number is bumped. Let’s imagine a documentation server may need to be replaced every time a new version of an API is made available. We could use the --replace flag each time, but this process is error-prone to do manually, and would incur a maintenance burden to automate.

Defining replacement triggers

In essence, a replacement trigger is just a value attached to the resource as metadata. However, whenever this value changes between updates, it will trigger a replace operation on the given resource, regardless of whether anything else has changed.

Let’s take our previous example: we want something to be replaced every month. With replacement triggers, we can solve this by representing the current year and month as a string:

...

const today = new Date()

const keyManager = new KeyManagerResource("key-manager", {}, {
 replacementTrigger: today.getMonth() + '-' + today.getFullYear()
});

...

...
from datetime import datetime

today = datetime.now()
trigger = f"{today.month}-{today.year}"

key_manager = KeyManagerResource("key-manager", {},
 opts=pulumi.ResourceOptions(replacement_trigger=trigger))

...

...

today := time.Now()
trigger := fmt.Sprintf("%d-%d", int(today.Month()), today.Year())

keyManager, err := NewKeyManagerResource(ctx, "key-manager", &KeyManagerResourceArgs{},
 pulumi.ReplacementTrigger(pulumi.Any(trigger)))

...

...

var today = LocalDate.now();
var trigger = String.format("%d-%d", today.getMonthValue(), today.getYear())

var keyManager = new KeyManagerResource("key-manager",
 KeyManagerResourceArgs.Empty,
 CustomResourceOptions.builder()
 .replacementTrigger(Output.of(trigger))
 .build());

...

...

var today = DateTime.Now;
var trigger = $"{today.Month}-{today.Year}";

var keyManager = new KeyManagerResource("key-manager", new KeyManagerResourceArgs(),
 new CustomResourceOptions
 {
 ReplacementTrigger = Output.Create(trigger)
 });

...

When we run this update for the first time, the replacement trigger will be persisted to the Pulumi state. Each time we run an update, we’ll re-calculate the date string, and compare it against the current string. Finally, when we run the update again next month, and the date string no longer matches, our key-manager will be replaced and our new keys will be generated!

Next steps

This feature is fully supported across all our SDKs as of v3.215.0. For more information about resource options, see the resource options documentation.

Thanks for reading, and feel free to reach out with any questions via GitHub, X, or our Community Slack.

New in Pulumi IaC: `replaceWith` Resource Option

Tom Harding — Tue, 09 Dec 2025 00:00:00 +0000

The magic of Pulumi is that we rarely have to worry about the fine details of how our deployment and infrastructure management works, allowing us to focus instead on what we want. If our program declares an S3 bucket, Pulumi handles creation, updates, and deletion automatically.

Most of the time, this is exactly what we want. However, some use cases require finer-grained control over resource dependencies. Today, we’re introducing the replaceWith resource option, a new feature that gives you explicit control over replacement dependencies between resources.

Custom resource dependencies

When replacing a resource, the Pulumi engine walks the dependency graph to determine what else needs replacement. However, the answer isn’t always obvious:

Some dependencies aren’t obvious at the infrastructure level. For example, restarting a database server may require restarting its consumers to reconnect.
Provider-specific challenges exist. You might not be able to update a subnet’s properties while resources are using it, even without an observable dependency. Any subnet change must be accompanied by changes to all its consumers to avoid errors.
Application-level dependencies may exist beyond infrastructure. If two services maintain open connections in the application layer, replacing one should trigger replacement of the other.

Declaring our own dependencies

The replaceWith resource option makes these dependencies explicit in your code. Similar to deletedWith, passing references to other resources via replaceWith defines a relationship: when any target resource is replaced, the source is also replaced. This has some interesting implications:

We can define a number of resources that all replaceWith each other, and so any change to any member of the group will trigger an update to all the others.
Relationships are transitive: organizing resources hierarchically where children replaceWith their parents means any ancestor change triggers replacement of all descendants.

In code

import * as pulumi from "@pulumi/pulumi";
import * as aws from "@pulumi/aws";

const database = new aws.rds.Instance("app-db", { /* ... */ });

// The database location is provided to this instance
// by other means, so there is not an explicit dependency
// linking the two.
const app = new aws.ec2.Instance("app-service", { /* ... */ }, {
 // Here, we explicitly tie the two together: if the
 // database is upgraded, for example, we will need to
 // restart the application instance to ensure that
 // a connection is re-established.
 replaceWith: [database],
});

import pulumi
import pulumi_aws as aws

database = aws.rds.Instance('app-db', {})

# The database location is provided to this instance
# by other means, so there is not an explicit dependency
# linking the two.
application = aws.ec2.Instance('app-service', {},
 # Here, we explicitly tie the two together: if the
 # database is upgraded, for example, we will need to
 # restart the application instance to ensure that
 # a connection is re-established.
 opts=pulumi.ResourceOptions(replace_with=[database])
)

import (
 "github.com/pulumi/pulumi-aws/sdk/v6/go/aws/ec2"
 "github.com/pulumi/pulumi-aws/sdk/v6/go/aws/rds"
 "github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

database, err := rds.NewInstance(ctx, "app-db", &rds.InstanceArgs{ ... })
if err != nil {
 return err
}

// The database location is provided to this instance
// by other means, so there is not an explicit dependency
// linking the two.
application, err := ec2.NewInstance(ctx, "app-service", &ec2.InstanceArgs{ ... },
 // Here, we explicitly tie the two together; if the
 // database is upgraded, for example, we will need to
 // restart the application instance to ensure that
 // a connection is re-established.
 pulumi.ReplaceWith([]pulumi.Resource{database}))
if err != nil {
 return err
}

using Pulumi;
using Aws = Pulumi.Aws;

var database = new Aws.Rds.Instance("app-db", new() { ... });

// The database location is provided to this instance
// by other means, so there is not an explicit dependency
// linking the two.
var application = new Aws.Ec2.Instance("app-service", new() { ... }, new CustomResourceOptions
{
 // Here, we explicitly tie the two together; if the
 // database is upgraded, for example, we will need to
 // restart the application instance to ensure that
 // a connection is re-established.
 ReplaceWith = new[]
 {
 database,
 },
});

import com.pulumi.aws.ec2.Instance;
import com.pulumi.aws.ec2.InstanceArgs;
import com.pulumi.resources.CustomResourceOptions;

var database = new com.pulumi.aws.rds.Instance("app-db",
 com.pulumi.aws.rds.InstanceArgs.builder()
 .build());

// The database location is provided to this instance
// by other means, so there is not an explicit dependency
// linking the two.
var application = new Instance("app-service",
 InstanceArgs.builder()
 .build(),
 // Here, we explicitly tie the two together; if the
 // database is upgraded, for example, we will need to
 // restart the application instance to ensure that
 // a connection is re-established.
 CustomResourceOptions.builder()
 .replaceWith(database)
 .build());

resources:
 database:
 type: aws:rds:Instance
 properties:
 # ...
 # The database location is provided to this instance
 # by other means, so there is not an explicit dependency
 # linking the two.
 application:
 type: aws:ec2:Instance
 properties:
 # ...
 options:
 # Here, we explicitly tie the two together: if the
 # database is upgraded, for example, we will need to
 # restart the application instance to ensure that
 # a connection is re-established.
 replaceWith:
 - ${database}

Of course, this is a simple example, but hopefully it illustrates the point: we now have a way to make implicit dependencies between resources more explicit within our programs, and provide hints to Pulumi as to which services depend on others.

Next steps

This feature is supported as of Pulumi v3.207.0, and is now available within the Go, Python, NodeJS, and Java SDKs, with C# and YAML coming soon. Thanks for reading, and feel free to reach out with any questions via GitHub, X, or our Community Slack.

All Pulumi CLI flags are now supported as environment variables

Tom Harding — Fri, 21 Nov 2025 00:00:00 +0000

With the release of Pulumi v3.208.0, all CLI flags can now be configured as environment variables. This addresses a common friction point of having to remember the same flags across multiple commands and of ensuring that your entire team uses consistent CLI options.

Use cases

An example use case might be that you want to always refresh state before operations, or re-run programs during refresh and destroy (using --run-program). But remembering to add --refresh every time is tedious.

Another example is you’re working on a specific subset of your infrastructure and need to pass the same --target or --exclude flags repeatedly across multiple operations.

You’re working in a CI environment where you want to skip interactive prompts and previews. That means adding --yes and --skip-preview to every single command in your pipeline.

The usual workaround, if there is no env var already, is writing wrapper scripts or shell aliases, but these become another thing to maintain and share across your team.

How it works

Any CLI flag can now be set as an environment variable. The naming convention is straightforward: prefix the flag name with PULUMI_OPTION_, and convert dashes to underscores.

For example:

export PULUMI_OPTION_REFRESH=true

Target specific resources without repeating flags:

export PULUMI_OPTION_TARGET=foo,bar
# Equivalent to: --target foo --target bar

This works for any flag the CLI accepts. The environment variable takes precedence if you don’t explicitly pass the flag on the command line.

Using with direnv for project-level defaults

This becomes particularly useful when combined with tools like direnv. You can define project-specific CLI defaults in a .envrc file at the root of your project:

# Enable very verbose logging for debugging purposes
export PULUMI_OPTION_VERBOSE=3

# Always refresh before any Pulumi operation
export PULUMI_OPTION_REFRESH=true

# Skip previews and any dialogs or user prompts
export PULUMI_OPTION_YES=true
export PULUMI_OPTION_SKIP_PREVIEW=true

Now, running direnv allow . in this directory means that, whenever we access this directory, these options will be automatically applied to all commands that we run until we leave the directory!

Wrapping up

We hope that this change makes Pulumi much easier to configure across a range of different environments, and gives you another tool for managing operation defaults across your team. Thanks for reading, and feel free to share any feedback on GitHub, X, or our Community Slack.

New in Pulumi IaC: Support for skipping a resource

Tom Harding — Wed, 14 May 2025 00:00:00 +0000

Managing large-scale infrastructure can be challenging, especially when you need to perform operations on specific subsets of your resources. Pulumi’s stack operations like pulumi up and pulumi destroy are powerful for deploying and tearing down environments, but sometimes you need more fine-grained control over which resources are affected.

Today, we’re excited to announce a highly requested feature that will save you time and reduce complexity in your workflows: the ability to exclude specific resources from stack operations using the new --exclude and --exclude-dependents flags.

These new flags complement the existing --target functionality, giving you powerful options whether you want to focus on a small subset of resources or exclude just a few from larger operations. No more workarounds or custom scripts to achieve selective deployments!

The challenge: partial operations on large stacks

When managing infrastructure at scale, you often want to operate on most—but not all—resources in your stack. For example:

Deploying all resources except a database that requires a maintenance window
Refreshing most resources while skipping those with known differences
Updating production infrastructure while leaving critical services untouched
Testing changes to most components while preserving test data in development

Pulumi already has the --target flag to specify which resources to include in an operation. This works well when you want to target a small number of resources, but becomes unwieldy when you want to operate on most of your stack while excluding only a few resources.

The solution: introducing `--exclude` and `--exclude-dependents`

Our new --exclude flag solves this problem by letting you specify which resources to omit from stack operations. When paired with --exclude-dependents, you can also exclude all child resources of the specified resources, making it easy to exclude entire branches of your resource tree.

These flags are now available for all major stack operations:

pulumi up --exclude <URN>::resource-to-skip
pulumi preview --exclude <URN>::resource-to-skip
pulumi refresh --exclude <URN>::resource-to-skip
pulumi destroy --exclude <URN>::resource-to-skip

Each of these commands can also use the --exclude-dependents flag to exclude child resources.

An example: selective deployment of blog content

Let’s imagine you’re managing a static blog website with Pulumi. As part of your deployment, you have multiple HTML pages you’d like to deploy:

...

for (const file in await glob('posts/**/*.html')) {
 new aws.s3.BucketObject(`post-${file}`, {
 source: new pulumi.asset.FileAsset(file),
 ...
 })
}

...

...

for (const file in await glob('posts/**/*.html')) {
 new aws.s3.BucketObject(`post-${file}`, {
 source: new pulumi.asset.FileAsset(file),
 ...
 })
}

...

...

for file in glob("posts/**/*.html"):
 aws.s3.BucketObject(file,
 source = pulumi.FileAsset(file),
 ....
 )

...

...

files, err := filepath.Glob("posts/**/*.html")
if err != nil { return err }

for _, file := range files {
 _, err := s3.NewBucketObject(ctx, file, &s3.BucketObjectArgs{
 Source: pulumi.FileAsset(file),
 ...
 })

 if err != nil { return err }
}

...

...

var files = Directory.GetFiles("posts", "*.html");

foreach (var file in files)
{
 var bucketObject = new BucketObjectv2(file, new BucketObjectv2Args
 {
 Source = new FileAsset(file),
 ...
 });
}

...

This works well, but what if we have a list of draft articles that we don’t want to include in the deployment? We can optimistically assume we’ve finished more articles than we’ve started, so using --target to specify every article, as well as supporting resources (CSS, JavaScript, ownership controls, et cetera), would quickly become unmanageable.

pulumi up --target <URN>::style.css --target <URN>::post-hello.html ...

With the --exclude flag, this becomes much more manageable:

pulumi up --exclude <URN>::post-draft-1.html --exclude <URN>::post-draft-2.html ...

With this command, everything not specified using an --exclude tag will be included in the up operation, and thus we can avoid the hassle of naming every resource that isn’t a draft.

Next step: a draft group

This is fine for a personal blog site, but can still become unmanageable when we’re dealing with multiple authors, each with multiple drafts. In this case, we might want to group our drafts under a common parent:

...

// A parent component for all drafts
const drafts = new pulumi.ComponentResource('ComponentResource', 'drafts')

for (const file in await glob('drafts/**/*.html')) {
 new aws.s3.BucketObject(`draft-${file}`, {
 source: new pulumi.asset.FileAsset(`drafts/${file}`),
 ...
 }, { parent: drafts })
}

...

...

// A parent component for all drafts
const drafts: pulumi.ComponentResource =
 new pulumi.ComponentResource('ComponentResource', 'drafts')

for (const file in await glob('drafts/**/*.html')) {
 new aws.s3.BucketObject(`draft-${file}`, {
 source: new pulumi.asset.FileAsset(`drafts/${file}`),
 ...
 }, { parent: drafts })
}

...

...

# A parent component for all drafts
drafts = pulumi.ComponentResource(t="ComponentResource", name="drafts")

for file_path in glob("posts/**/*.html"):
 aws.s3.BucketObject(file_path,
 source = pulumi.FileAsset(file_path),
 opts = pulumi.ResourceOptions(parent = drafts),
 ....
 )

...


drafts := &DraftGroupComponent{}
err = ctx.RegisterComponentResource("ComponentResource", "drafts", drafts)
if err != nil { return err }

...

files, err := filepath.Glob("posts/*.html")
if err != nil { return err }

for _, file := range files {
 _, err := s3.NewBucketObject(ctx, file, &s3.BucketObjectArgs{
 Key: pulumi.String(file),
 ...
}, pulumi.Parent(drafts))

 if err != nil { return err }
}

...


public class MyComponentResource : ComponentResource { ... }

...

var files = Directory.GetFiles("posts", "*.html");
var drafts = new MyComponentResource("drafts");

foreach (var file in files)
{
 var bucketObject = new BucketObjectv2(file, new BucketObjectv2Args
 {
 Source = new FileAsset(file),
 ...
 }, new CustomResourceOptions
 {
 Parent = drafts
 });
}

...

In this setup, we now have a parent resource for all drafts. Using --exclude-dependents, we can now exclude everything under this parent resource without having to enumerate all of them individually:

pulumi up --exclude <URN>::ComponentResource::drafts --exclude-dependents

This command will exclude all drafts from the up operation, regardless of how many we have or how they’re named. We now have a nice, scalable way to manage our drafts across production and development environments!

Next steps

With these flags now available in Pulumi CLI v3.158.0., expect to see them introduced in the automation APIs and GitHub action soon. Thanks for reading, and feel free to share any feedback on GitHub, X, or our Community Slack.

Pulumi Blog: Tom Harding

New in Pulumi IaC: `onError` Resource Hook

Recovering from errors

Next steps

New in Pulumi IaC: `replacementTrigger` Resource Option

Forcing replacements

Defining replacement triggers

Next steps

New in Pulumi IaC: `replaceWith` Resource Option

Custom resource dependencies

Declaring our own dependencies

In code

Next steps

All Pulumi CLI flags are now supported as environment variables

Use cases

How it works

Using with direnv for project-level defaults

Wrapping up

New in Pulumi IaC: Support for skipping a resource

The challenge: partial operations on large stacks

The solution: introducing --exclude and --exclude-dependents

An example: selective deployment of blog content

Next step: a draft group

Next steps

The solution: introducing `--exclude` and `--exclude-dependents`