Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท Resources and Programs

Pulumi Resource Options: dependsOn, protect, aliases, ignoreChanges

Master Pulumi resource options: parent, dependsOn, protect, retainOnDelete, ignoreChanges, replaceOnChanges, deleteBeforeReplace, aliases, import, transforms and auto-naming.

Every resource constructor takes three things: a name, its arguments (inputs for the cloud), and options that tell the engine how to treat the resource. Options do not become cloud properties; they change planning, ordering and safety. This lesson covers the ones you will use constantly.

Name, arguments, options

TypeScript
const db = new aws.rds.Instance(
  "main-db",                          // logical name, part of the URN
  { engine: "postgres", instanceClass: "db.t4g.micro", allocatedStorage: 20 },  // arguments
  { protect: true, dependsOn: [subnetGroup] }                                   // options
);

Auto-naming

Most providers generate the physical name from the logical one by appending a random suffix: main-db becomes main-db-4c8e1d2. This lets you deploy the same program to two stacks in one account, and lets Pulumi create the replacement before deleting the old resource. You can set an explicit name argument when you must (bucket: "acme-site"), but then a replacement needs deleteBeforeReplace because two resources cannot share the name, and the name must be globally unique where the cloud requires it.

parent

parent makes a resource a child of another, forming a tree. Children appear nested in the CLI, inherit providers and certain options like protect, and their URNs include the parent's type. Components set it for you (Components).

TypeScript
new aws.s3.BucketObject("index", { bucket: bucket.id, source: new pulumi.asset.FileAsset("index.html") },
  { parent: bucket });

dependsOn

Normally dependencies come from Outputs. Use dependsOn only for a dependency that is not expressed as a value, such as a policy that must exist before a function runs:

TypeScript
const fn = new aws.lambda.Function("fn", { /* ... */ }, { dependsOn: [logPolicyAttachment] });

More in Dependencies and Ordering.

protect and retainOnDelete

protect: true makes pulumi destroy, and updates that would delete or replace the resource, fail. It is the seat belt for databases and state buckets. To remove it, change the option to false, run pulumi up, then destroy.

retainOnDelete: true lets Pulumi delete the resource from state while leaving the real thing in the cloud, useful when you hand a resource over to another stack.

TypeScript
new aws.s3.BucketV2("tfstate", {}, { protect: true, retainOnDelete: true });

ignoreChanges and replaceOnChanges

  • ignoreChanges: ["tags"] tells the engine to ignore differences in those properties, for example when an autoscaler or another tool edits desired capacity.
  • replaceOnChanges: ["userData"] forces replacement when that property changes, even if the provider could update in place.
TypeScript
const group = new aws.autoscaling.Group("asg", { desiredCapacity: 2 /* ... */ },
  { ignoreChanges: ["desiredCapacity"] });

deleteBeforeReplace

Flip the replacement order for fixed-name resources:

TypeScript
new aws.iam.Role("deploy", { name: "deploy-role", assumeRolePolicy }, { deleteBeforeReplace: true });

aliases

An alias tells the engine "this resource used to have another URN". That makes renames and moves into components safe:

TypeScript
// Renamed from "assets" to "site-assets"
new aws.s3.BucketV2("site-assets", {}, { aliases: [{ name: "assets" }] });

// Moved under a component parent
new aws.s3.BucketV2("assets", {}, { parent: this, aliases: [{ parent: pulumi.rootStackResource }] });

Keep aliases for a release or two, then remove them.

import

import adopts an existing cloud resource into state instead of creating it:

TypeScript
new aws.s3.BucketV2("legacy", { bucket: "acme-legacy-assets" }, { import: "acme-legacy-assets" });

The CLI can also do it: pulumi import aws:s3/bucketV2:BucketV2 legacy acme-legacy-assets prints code to paste. After the import succeeds, remove the import option.

provider, providers, version

provider picks an explicit provider for a resource; providers sets them for a component's subtree (Providers).

transforms

transforms (formerly transformations) rewrites arguments or options of the resource and its children, for example adding tags to everything under a component:

TypeScript
const component = new MyApp("app", {}, {
  transforms: [(args) => {
    if (args.type === "aws:s3/bucketV2:BucketV2") {
      args.props.tags = { ...args.props.tags, owner: "web" };
      return { props: args.props, opts: args.opts };
    }
    return undefined;
  }],
});

Stack-wide variants use pulumi.runtime.registerResourceTransform. Since the API surface has changed across releases, check the SDK reference for your version.

customTimeouts

TypeScript
new aws.rds.Instance("db", { /* ... */ }, { customTimeouts: { create: "40m", delete: "30m" } });

Stand-in: options that change a plan

This stand-in plays three options (protect, ignoreChanges, aliases) against a plan so you can see their effect.

JS Stand-in: options in a plan

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: auto-naming

JS Stand-in: auto-naming suffix

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does protect: true do?

    Protected resources cannot be deleted by Pulumi until you remove the option.
  2. 2. You rename a resource's logical name. What prevents a replacement?

    An alias maps the new URN to the old one so state is reused.
  3. 3. When is dependsOn appropriate?

    Output usage already records dependencies; dependsOn fills the remaining gaps.
  4. 4. What does the import option do?

    Give it the cloud ID of the existing resource.

Summary

  • Options guide the engine: parent, dependsOn, provider, protect, retainOnDelete, ignoreChanges, replaceOnChanges, deleteBeforeReplace, aliases, import, transforms, customTimeouts.
  • Auto-naming adds a suffix so stacks do not collide; explicit names need deleteBeforeReplace.
  • Use protect for stateful resources and aliases for every rename or move.
  • import adopts existing resources.

Next: Pulumi Programs in TypeScript, Python, Go and C#