Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Components and Reuse

Component Resources: Grouping Resources into Reusable Building Blocks

Learn how Pulumi component resources group several resources into one logical unit: the constructor contract, parent options, registerOutputs, URNs and the resource tree.

A real Pulumi program quickly grows past a handful of resources. A "static website" is a bucket, a public-access block, a bucket policy, a CDN distribution and a DNS record. Writing those five resources again for every site is tedious and error-prone. A component resource lets you wrap them in one class, give it a name and a small set of inputs, and use it like any other resource.

Components are Pulumi's main unit of reuse, comparable to modules in Terraform but written in a real programming language. This lesson explains the contract a component must follow and why the details (type token, parent, registerOutputs) matter.

The Pulumi CLI and the cloud providers cannot run on this site. The TypeScript below is read-only; the runnable examples are small JavaScript stand-ins that model how names, URNs and parent-child links work, so you can see the idea without a cloud account.

The shape of a component

In TypeScript a component extends pulumi.ComponentResource:

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

export interface StaticSiteArgs {
  indexDocument?: pulumi.Input<string>;
  tags?: pulumi.Input<Record<string, pulumi.Input<string>>>;
}

export class StaticSite extends pulumi.ComponentResource {
  public readonly bucketName: pulumi.Output<string>;
  public readonly websiteUrl: pulumi.Output<string>;

  constructor(name: string, args: StaticSiteArgs = {}, opts?: pulumi.ComponentResourceOptions) {
    super("acme:web:StaticSite", name, {}, opts);

    const bucket = new aws.s3.BucketV2(`${name}-bucket`, {
      tags: args.tags,
    }, { parent: this });

    const website = new aws.s3.BucketWebsiteConfigurationV2(`${name}-website`, {
      bucket: bucket.id,
      indexDocument: { suffix: args.indexDocument ?? "index.html" },
    }, { parent: this });

    this.bucketName = bucket.bucket;
    this.websiteUrl = website.websiteEndpoint;

    this.registerOutputs({
      bucketName: this.bucketName,
      websiteUrl: this.websiteUrl,
    });
  }
}

Four rules make this work:

  1. Call super with a type token. The first argument has the form package:module:Type, for example acme:web:StaticSite. Use your own organization or package name, never aws or pulumi, which belong to others.
  2. Pass the name and options through. The second argument is the logical name; opts carries things like provider, dependsOn and parent from the caller.
  3. Give every child { parent: this }. This links children to the component in the resource tree.
  4. Call registerOutputs. It tells Pulumi the component is finished and which values it exposes. Without it the component can show as still "creating" in some UIs and its outputs are not saved in state.

Why parent matters

Every resource has a URN (uniform resource name) that identifies it in state. It is built from the stack, the project, the chain of parent types, the type and the name:

TEXT
urn:pulumi:prod::website::acme:web:StaticSite$aws:s3/bucketV2:BucketV2::blog-bucket

The $ separates a parent type from a child type. When you set parent: this, the child's URN includes the component's type, and the console shows a tidy tree:

flowchart TB
  Stack["Stack: prod"] --> Blog["StaticSite: blog"]
  Stack --> Docs["StaticSite: docs"]
  Blog --> B1["BucketV2: blog-bucket"]
  Blog --> W1["WebsiteConfig: blog-website"]
  Docs --> B2["BucketV2: docs-bucket"]
  Docs --> W2["WebsiteConfig: docs-website"]

Parent links give you a tree in pulumi up output and let options such as protect and provider flow down to children.

Children inherit some options from the parent: if you create the component with a specific provider, every child uses it unless it overrides it, and protect: true on the parent applies to the children as well.

A stand-in: URNs and the resource tree

The first stand-in is not Pulumi, just a small model of how a resource tree turns into URNs. Run it and change the names.

Node.js Stand-in: building URNs from a parent chain

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The two buckets differ because their names carry the component name as a prefix. Always prefix child names with the component's name, as ${name}-bucket does. Physical names (the real bucket name in AWS) are auto-generated from the logical name plus a random suffix, which is another reason to keep logical names unique.

Defaults, validation and aliases

A good component is a small, opinionated API. Give inputs safe defaults, validate early and throw a clear error. Because the constructor is ordinary code, you can do anything your language allows:

TypeScript
if (args.retentionDays !== undefined && args.retentionDays < 1) {
  throw new Error(`StaticSite ${name}: retentionDays must be at least 1`);
}

Renaming is where components bite. If you rename a component from blog to blog-site, every child URN changes, and Pulumi plans to delete and recreate them. To avoid that, pass aliases to tell Pulumi the old identity:

TypeScript
const site = new StaticSite("blog-site", {}, {
  aliases: [{ name: "blog" }],
});

Aliases on a component are inherited by its children, so one alias covers the subtree. Move a component under another parent with aliases: [{ parent: oldParent }].

Node.js Stand-in: why a rename causes replace, and how an alias prevents it

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In the stand-in the child is named bucket and keeps its name while the component is renamed. That mirrors good practice: keep child logical names stable. (The real engine also rewrites the parent part of child URNs from the component's alias; the stand-in is simplified.)

Common mistakes

  • Forgetting parent: this. Children become top-level resources, their URNs lose the component type, and protect and provider no longer flow down.
  • Never calling registerOutputs. Outputs are not recorded as component outputs.
  • Doing async work in the constructor. Constructors cannot be async. Use Output.apply or pulumi.output(...), or look values up with the getXxxOutput functions.
  • Hard-coding names. Every instance of a component needs distinct child names; derive them from name.
  • Exposing too much. A component with forty inputs is just the provider API again. Offer the three or four choices consumers really make.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the purpose of passing { parent: this } to child resources?

    The parent link changes the child's URN, shapes the tree shown in the console and lets inherited options such as provider and protect reach the child.
  2. 2. Which first argument to super() is correct for a component you publish from your organization?

    The type token is package:module:Type and the package part should be one you own, not a provider namespace like aws.
  3. 3. What does registerOutputs do?

    registerOutputs marks the end of construction and saves the output values on the component resource in the state.
  4. 4. You rename a component from blog to blog-site and Pulumi plans to delete and recreate its children. How do you avoid that?

    Aliases tell Pulumi the new URN is the same resource as the old one, so it updates in place instead of replacing.

Summary

  • A component resource wraps several resources behind one name and a small input type.
  • Call super with a package:module:Type token, forward opts, use { parent: this } for every child and finish with registerOutputs.
  • Parent chains form the URN and the resource tree; inherited options flow from parent to child.
  • Renames and re-parenting change URNs, so use aliases to keep resources in place.
  • Keep the component API small, validate inputs early and prefix child names with the component name.

Next: Designing Component Inputs and Outputs