Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Resources and Programs

Pulumi Dependencies, Ordering and Parallelism

Learn how Pulumi builds its dependency graph from Outputs, when to use dependsOn, how parallelism and --parallel work, deletion order, and how to view the graph and avoid cycles.

In Pulumi you rarely write "do this before that". The engine builds a dependency graph from the values you pass between resources, runs independent resources in parallel and reverses the order for deletes. This lesson explains the graph, the cases where you must add edges by hand, and how to inspect it.

Where edges come from

An edge A to B ("B depends on A") is created when:

  1. B receives an Output of A as an input (subnetId: subnet.id).
  2. B lists A in dependsOn.
  3. B has A as its parent (a child waits for its parent to be created, in most operations).
  4. B uses a provider instance that is itself a resource (the provider must exist first).
TypeScript
const vpc = new aws.ec2.Vpc("vpc", { cidrBlock: "10.0.0.0/16" });
const subnet = new aws.ec2.Subnet("subnet", { vpcId: vpc.id, cidrBlock: "10.0.1.0/24" });
const sg = new aws.ec2.SecurityGroup("sg", { vpcId: vpc.id });
const vm = new aws.ec2.Instance("vm", {
  ami: "ami-0abcdef1234567890",
  instanceType: "t3.micro",
  subnetId: subnet.id,
  vpcSecurityGroupIds: [sg.id],
});

The graph:

flowchart TD
  vpc --> subnet
  vpc --> sg
  subnet --> vm
  sg --> vm

subnet and sg are independent of each other, so Pulumi creates them at the same time.

Parallelism

Independent steps run concurrently. By default the engine runs as many as it can; you can limit it:

Terminal
pulumi up --parallel 4     # at most 4 steps in flight
pulumi up --parallel 1     # serial, useful when debugging or hitting API limits

Rate-limited APIs (some DNS or SaaS providers) sometimes need a lower value. Your program always runs once from top to bottom; only the resource operations overlap.

Deletion goes backwards

Deleting a stack, or removing resources, reverses the graph: the VM goes first, then the subnet and security group, then the VPC. This works because the state recorded each resource's dependencies; you do not have to keep the code that created them.

dependsOn for hidden dependencies

Sometimes B needs A to exist but takes no value from it. Classic example: a Lambda function needs its log-group permission attachment to exist before its first invocation.

TypeScript
const attach = new aws.iam.RolePolicyAttachment("fn-logs", { role: role.name, policyArn });
const fn = new aws.lambda.Function("fn", { role: role.arn, /* ... */ }, { dependsOn: [attach] });

Use dependsOn sparingly. It makes B wait for A, and, when A is a component, for all children of A. Too many manual edges slow the update and hide design problems.

Ordering things that do not have values: the Command and Time providers

Waiting for a fixed time or running a script are their own resources, so they take part in the graph:

TypeScript
import * as time from "@pulumiverse/time";

const wait = new time.Sleep("iam-propagation", { createDuration: "20s" }, { dependsOn: [role] });
const fn = new aws.lambda.Function("fn", { role: role.arn /* ... */ }, { dependsOn: [wait] });

This pattern replaces ad-hoc sleep calls and keeps the plan accurate.

Cycles

A cycle (A depends on B and B depends on A) cannot be built, because you cannot pass an Output that does not exist yet. The classic AWS case is two security groups that reference each other. The fix is to create both groups first and add the cross-references as separate rule resources:

TypeScript
const a = new aws.ec2.SecurityGroup("a", { vpcId: vpc.id });
const b = new aws.ec2.SecurityGroup("b", { vpcId: vpc.id });
new aws.vpc.SecurityGroupIngressRule("a-from-b", { securityGroupId: a.id, referencedSecurityGroupId: b.id, ipProtocol: "tcp", fromPort: 80, toPort: 80 });
new aws.vpc.SecurityGroupIngressRule("b-from-a", { securityGroupId: b.id, referencedSecurityGroupId: a.id, ipProtocol: "tcp", fromPort: 80, toPort: 80 });

Viewing the graph

Terminal
pulumi stack graph graph.dot
dot -Tpng graph.dot -o graph.png     # requires Graphviz

Pulumi Cloud shows the same graph in its UI, and pulumi stack --show-urns prints each resource's URN.

Stand-in: dependency waves

This stand-in computes parallel waves for creation, then the reverse for deletion. Change the graph and rerun.

JS Stand-in: create waves and delete order

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

No output.

Stand-in: limiting parallelism

JS Stand-in: --parallel N

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. How does Pulumi usually learn that one resource depends on another?

    Using resource.property as an input records the edge.
  2. 2. In which order are resources deleted?

    Dependents must be removed before the things they depend on.
  3. 3. When is dependsOn the right tool?

    It adds an explicit edge for hidden dependencies.
  4. 4. How do you resolve two security groups that reference each other?

    Separate rule resources break the cycle.

Summary

  • Edges come from Output inputs, dependsOn, parent and provider resources.
  • Independent resources run in parallel; --parallel N limits it.
  • Deletes run in reverse order using the recorded dependencies.
  • Break cycles by splitting references into separate resources; add dependsOn only for hidden dependencies.
  • pulumi stack graph exports the graph.

Next: Loops, Conditionals and Functions in Programs