Component resources

Authoring a New Component Resource

To author a new component, either in a program or for a reusable library, create a subclass of ComponentResource. Inside of its constructor, chain to the base constructor, passing its type string, name, arguments, and options. Also inside of its constructor, allocate any child resources, passing the parent option as appropriate to ensure component resource children are parented correctly.

Here’s a simple component example:

class MyComponent extends pulumi.ComponentResource {
    constructor(name, myComponentArgs, opts) {
        super("pkg:index:MyComponent", name, {}, opts);
    }
}

class MyComponent extends pulumi.ComponentResource {
    constructor(name: string, myComponentArgs: MyComponentArgs, opts: pulumi.ComponentResourceOptions) {
        super("pkg:index:MyComponent", name, {}, opts);
    }
}

class MyComponent(pulumi.ComponentResource):
    def __init__(self, name, my_component_args, opts = None):
        super().__init__('pkg:index:MyComponent', name, None, opts)

type MyComponent struct {
    pulumi.ResourceState
}

func NewMyComponent(ctx *pulumi.Context, name string, myComponentArgs MyComponentArgs, opts ...pulumi.ResourceOption) (*MyComponent, error) {
    myComponent := &MyComponent{}
    err := ctx.RegisterComponentResource("pkg:index:MyComponent", name, myComponent, opts...)
    if err != nil {
        return nil, err
    }
    return myComponent, nil
}

using System.Collections.Generic;
using Pulumi;

class MyComponent : ComponentResource
{
    public MyComponent(string name, MyComponentArgs myComponentArgs, ComponentResourceOptions opts)
        : base("pkg:index:MyComponent", name, opts)
    {
    }
}

import com.pulumi.resources.ComponentResource;
import com.pulumi.resources.ComponentResourceOptions;

class MyComponent extends ComponentResource {
    public MyComponent(String name, MyComponentArgs myComponentArgs, ComponentResourceOptions opts) {
        super("pkg:index:MyComponent", name, null, opts);
    }
}

Upon creating a new instance of MyComponent, the call to the base constructor (using super/base) registers the component resource instance with the Pulumi engine. This records the resource’s state and tracks it across program deployments so that you see diffs during updates just like with a regular resource (even though component resources have no provider logic associated with them). Since all resources must have a name, a component resource constructor should accept a name and pass it to super.

If you wish to have full control over one of the custom resource’s lifecycle in your component resource—including running specific code when a resource has been updated or deleted—you should look into dynamic providers. These let you create full-blown resource abstractions in your language of choice.

A component resource must register a unique type name with the base constructor. In the example, the registration is pkg:index:MyComponent. To reduce the potential of other type name conflicts, this name contains the package and module name, in addition to the type: <package>:<module>:<type>. These names are namespaced alongside non-component resources, such as aws:lambda:Function.

For a complete end-to-end walkthrough of building a component from scratch, including setup, implementation, and publishing, see the Build a Component guide.

Component arguments and type requirements

When authoring components that will be consumed across different languages (multi-language components), the arguments class has specific requirements and limitations due to the need for serialization. These constraints ensure that component arguments can be transmitted to the Pulumi engine and reconstructed across language boundaries.

Serialization requirements

Component arguments must be serializable, meaning you must convert them to a format that the engine can transmit and reconstruct. This is necessary because:

The Pulumi engine needs to understand and validate the inputs
Multi-language components need to translate arguments between languages
The state needs to be stored and retrieved across deployments

Supported types

The following types are supported in component arguments:

Primitive types: string, number/int, boolean.
Arrays/lists: Arrays of any supported type.
Objects/maps: Objects with properties of supported types.
Input wrappers: Language-specific input types that wrap values:
- TypeScript/JavaScript: pulumi.Input<T>
- Python: pulumi.Input[T]
- Go: pulumi.StringInput, pulumi.IntInput, etc.
- .NET: Input<T>
- Java: Output<T>

Unsupported types

The following types are not supported in component arguments:

Union types: TypeScript union types like string | number are not supported due to limitations in schema inference.
Functions/callbacks: Functions cannot be used in component arguments as they cannot be represented in the schema.
Platform-specific types: Types that exist only in one language and cannot be translated.

Design recommendations

For better usability and maintainability:

Avoid deeply nested types: While complex generic types can be serialized, deeply nested structures make components harder to use and understand. Keep argument structures simple and flat when possible.

Example of unsupported TypeScript types:

// ❌ This will NOT work - union types are not supported
export interface MyComponentArgs {
    value: string | number;  // Union type - unsupported
    callback: () => void;    // Function - unsupported
}

// ✅ This WILL work - use primitives or Input types
export interface MyComponentArgs {
    value: pulumi.Input<string>;
    count: pulumi.Input<number>;
}

Constructor requirements by language

Each language has specific requirements for component constructors to ensure proper schema generation:

Requirements:

The constructor must have an argument named exactly args
The args parameter must have a type declaration (e.g., args: MyComponentArgs)

class MyComponent extends pulumi.ComponentResource {
    constructor(name: string, args: MyComponentArgs, opts?: pulumi.ComponentResourceOptions) {
        super("pkg:index:MyComponent", name, {}, opts);
    }
}

Requirements:

The __init__ method must have an argument named exactly args
The args parameter must have a type annotation (e.g., args: MyComponentArgs)

class MyComponent(pulumi.ComponentResource):
    def __init__(self, name: str, args: MyComponentArgs, opts: Optional[pulumi.ResourceOptions] = None):
        super().__init__('pkg:index:MyComponent', name, None, opts)

Requirements:

The constructor function should accept a context, name, args struct, and variadic resource options
The args should be a struct type

func NewMyComponent(ctx *pulumi.Context, name string, args *MyComponentArgs, opts ...pulumi.ResourceOption) (*MyComponent, error) {
    myComponent := &MyComponent{}
    err := ctx.RegisterComponentResource("pkg:index:MyComponent", name, myComponent, opts...)
    if err != nil {
        return nil, err
    }
    return myComponent, nil
}

Requirements:

The constructor must have exactly 3 arguments:
1. A string for the name (or any unspecified first argument)
2. An argument that is assignable from ResourceArgs (must extend ResourceArgs)
3. An argument that is assignable from ComponentResourceOptions

public class MyComponent : ComponentResource
{
    public MyComponent(string name, MyComponentArgs args, ComponentResourceOptions? opts = null)
        : base("pkg:index:MyComponent", name, opts)
    {
    }
}

public sealed class MyComponentArgs : ResourceArgs
{
    [Input("value")]
    public Input<string>? Value { get; set; }
}

Requirements:

The constructor must have exactly one argument that extends ResourceArgs
Other arguments (name, options) are not restricted but typically follow the standard pattern

public class MyComponent extends ComponentResource {
    public MyComponent(String name, MyComponentArgs args, ComponentResourceOptions opts) {
        super("pkg:index:MyComponent", name, null, opts);
    }
}

class MyComponentArgs extends ResourceArgs {
    @Import(name = "value")
    private Output<String> value;

    public Output<String> getValue() {
        return this.value;
    }
}

Best practices

When designing component arguments:

Wrap all scalar members in Input types: Every scalar argument should be wrapped in the language’s input type (e.g., pulumi.Input<string>). This allows users to pass both plain values and outputs from other resources, avoiding the need to use apply for resource composition.
Use basic types: Stick to primitive types, arrays, and basic objects.
Avoid union types: Instead of a single value with multiple types, consider multiple, mutually exclusive argument members and validate that only one of them has a value in your component constructor.
Document required vs. optional: Clearly document which arguments are required and which have defaults.
Follow language conventions: Use camelCase for schema properties but follow language-specific naming in implementation (snake_case in Python, PascalCase in .NET).

Creating Child Resources

Component resources often contain child resources. The names of child resources are often derived from the component resources’s name to ensure uniqueness. For example, you might use the component resource’s name as a prefix. Also, when constructing a resource, children must be registered as such. To do this, pass the component resource itself as the parent option.

This example demonstrates both the naming convention and how to designate the component resource as the parent:

class MyComponent extends pulumi.ComponentResource {
    constructor(name, myComponentArgs, opts) {
        super("pkg:index:MyComponent", name, {}, opts);

        // Create Child Resource
        this.bucket = new aws.s3.Bucket(`${name}-bucket`,
            {}, { parent: this });
    }
}

class MyComponent extends pulumi.ComponentResource {
    bucket: aws.s3.Bucket;

    constructor(name: string, myComponentArgs: MyComponentArgs, opts: pulumi.ComponentResourceOptions) {
        super("pkg:index:MyComponent", name, {}, opts);

        // Create Child Resource
        this.bucket = new aws.s3.Bucket(`${name}-bucket`,
            {}, { parent: this });
    }
}

class MyComponent(pulumi.ComponentResource):
    def __init__(self, name, my_component_args, opts = None):
        super().__init__('pkg:index:MyComponent', name, None, opts)

        # Create Child Resource
        self.bucket = s3.Bucket(f"{name}-bucket",
            opts=pulumi.ResourceOptions(parent=self))

type MyComponent struct {
    pulumi.ResourceState
    Bucket *s3.Bucket
}

func NewMyComponent(ctx *pulumi.Context, name string, myComponentArgs MyComponentArgs, opts ...pulumi.ResourceOption) (*MyComponent, error) {
    myComponent := &MyComponent{}
    err := ctx.RegisterComponentResource("pkg:index:MyComponent", name, myComponent, opts...)
    if err != nil {
        return nil, err
    }

    // Create Child Resource
    bucket, err := s3.NewBucket(ctx, fmt.Sprintf("%s-bucket", name),
        &s3.BucketArgs{}, pulumi.Parent(myComponent))
    if err != nil {
        return nil, err
    }
    myComponent.Bucket = bucket

    return myComponent, nil
}

using System.Collections.Generic;
using Pulumi;
using Pulumi.Aws.S3;

class MyComponent : ComponentResource
{
    public Bucket Bucket { get; private set; }

    public MyComponent(string name, MyComponentArgs myComponentArgs, ComponentResourceOptions opts)
        : base("pkg:index:MyComponent", name, opts)
    {
        // Create Child Resource
        this.Bucket = new Bucket($"{name}-bucket",
            new BucketArgs(), new CustomResourceOptions { Parent = this });
    }
}

import com.pulumi.resources.ComponentResource;
import com.pulumi.resources.ComponentResourceOptions;
import com.pulumi.aws.s3.Bucket;
import com.pulumi.aws.s3.BucketArgs;
import com.pulumi.resources.CustomResourceOptions;

class MyComponent extends ComponentResource {
    private final Bucket bucket;

    public MyComponent(String name, MyComponentArgs myComponentArgs, ComponentResourceOptions opts) {
        super("pkg:index:MyComponent", name, null, opts);

        // Create Child Resource
        this.bucket = new Bucket(String.format("%s-bucket", name),
            BucketArgs.builder().build(),
            CustomResourceOptions.builder()
                .parent(this)
                .build());
    }

    public Bucket bucket() {
        return this.bucket;
    }
}

Registering Component Outputs

Component resources can define their own output properties. Outputs in a component must be registered with the Pulumi IaC engine by calling registerOutputs. The Pulumi engine uses this information to display the logical outputs of the component resource and any changes to those outputs will be shown during an update.

For example, this code registers an S3 bucket’s computed domain name, which won’t be known until the bucket is created:

class MyComponent extends pulumi.ComponentResource {
    constructor(name, myComponentArgs, opts) {
        super("pkg:index:MyComponent", name, {}, opts);

        this.bucket = new aws.s3.Bucket(`${name}-bucket`,
            {}, { parent: this });

        // Registering Component Outputs
        this.registerOutputs({
            bucketDnsName: this.bucket.bucketDomainName
        });
    }
}

class MyComponent extends pulumi.ComponentResource {
    bucket: aws.s3.Bucket;

    constructor(name: string, myComponentArgs: MyComponentArgs, opts: pulumi.ComponentResourceOptions) {
        super("pkg:index:MyComponent", name, {}, opts);

        this.bucket = new aws.s3.Bucket(`${name}-bucket`,
            {}, { parent: this });

        // Registering Component Outputs
        this.registerOutputs({
            bucketDnsName: this.bucket.bucketDomainName
        });
    }
}

class MyComponent(pulumi.ComponentResource):
    def __init__(self, name, my_component_args, opts = None):
        super().__init__('pkg:index:MyComponent', name, None, opts)

        self.bucket = s3.Bucket(f"{name}-bucket",
            opts=pulumi.ResourceOptions(parent=self))

        # Registering Component Outputs
        self.register_outputs({
            "bucket_dns_name": self.bucket.bucket_domain_name
        })

type MyComponent struct {
    pulumi.ResourceState
    Bucket *s3.Bucket
}

func NewMyComponent(ctx *pulumi.Context, name string, myComponentArgs MyComponentArgs, opts ...pulumi.ResourceOption) (*MyComponent, error) {
    myComponent := &MyComponent{}
    err := ctx.RegisterComponentResource("pkg:index:MyComponent", name, myComponent, opts...)
    if err != nil {
        return nil, err
    }

    bucket, err := s3.NewBucket(ctx, fmt.Sprintf("%s-bucket", name),
        &s3.BucketArgs{}, pulumi.Parent(myComponent))
    if err != nil {
        return nil, err
    }
    myComponent.Bucket = bucket

    //Registering Component Outputs
    ctx.RegisterResourceOutputs(myComponent, pulumi.Map{
        "bucketDnsName": bucket.BucketDomainName,
    })

    return myComponent, nil
}

using System.Collections.Generic;
using Pulumi;
using Pulumi.Aws.S3;

class MyComponent : ComponentResource
{
    public Bucket Bucket { get; private set; }

    public MyComponent(string name, MyComponentArgs myComponentArgs, ComponentResourceOptions opts)
        : base("pkg:index:MyComponent", name, opts)
    {

        this.Bucket = new Bucket($"{name}-bucket",
            new BucketArgs(), new CustomResourceOptions { Parent = this });

        // Registering Component Outputs
        this.RegisterOutputs(new Dictionary<string, object?>
        {
            { "bucketDnsName", Bucket.BucketDomainName }
        });
    }
}

import com.pulumi.resources.ComponentResource;
import com.pulumi.resources.ComponentResourceOptions;
import com.pulumi.aws.s3.Bucket;
import com.pulumi.aws.s3.BucketArgs;
import com.pulumi.resources.CustomResourceOptions;

class MyComponent extends ComponentResource {
    private final Bucket bucket;

    public MyComponent(String name, MyComponentArgs myComponentArgs, ComponentResourceOptions opts) {
        super("pkg:index:MyComponent", name, null, opts);

        this.bucket = new Bucket(String.format("%s-bucket", name),
            BucketArgs.builder().build(),
            CustomResourceOptions.builder()
                .parent(this)
                .build());

        // Registering Component Outputs
        this.registerOutputs(Map.of(
            "bucketDnsName", bucket.bucketDomainName()
        ));
    }

    public Bucket bucket() {
        return this.bucket;
    }
}

The call to registerOutputs typically happens at the very end of the component resource’s constructor.

What RegisterOutputs Does

The registerOutputs call serves two critical functions:

Marks the component as fully constructed: It signals to the Pulumi engine that the component resource has finished registering all its child resources and should be considered complete.
Saves outputs to state: It registers the component’s outputs with the Pulumi engine so they are properly saved to the state file and can be referenced by other resources or exported from the stack.

Failing to call registerOutputs could cause serious issues with your component resource:

The component will appear as “creating…” indefinitely in the Pulumi Console
Outputs will not be saved to the state file, potentially causing data loss
The component lifecycle will not complete properly, which may affect dependency tracking and updates

Inheriting Resource Providers

One option all resources have is the ability to pass an explicit resource provider to supply explicit configuration settings. For instance, you may want to ensure that all AWS resources are created in a different region than the globally configured region. In the case of component resources, the challenge is that these providers must flow from parent to children.

To allow this, component resources accept a providers option that custom resources don’t have. This value contains a map from the provider name to the explicit provider instance to use for the component resource. The map is used by a component resource to fetch the proper provider object to use for any child resources. This example overrides the globally configured AWS region and sets it to us-east-1. Note that myk8s is the name of the Kubernetes provider.

let component = new MyComponent("...", {
    providers: {
        aws: useast1,
        kubernetes: myk8s,
    },
});

let component = new MyComponent("...", {
    providers: {
        aws: useast1,
        kubernetes: myk8s,
    },
});

component = MyComponent('...', ResourceOptions(providers={
    'aws': useast1,
    'kubernetes': myk8s,
}))

component, err := NewMyResource(ctx, "...", nil, pulumi.ProviderMap(
    map[string]pulumi.ProviderResource{
        "aws":        awsUsEast1,
        "kubernetes": myk8s,
    },
))

var component = new MyResource("...", new ComponentResourceOptions {
    Providers = {
        { "aws", awsUsEast1 },
        { "kubernetes", myk8s }
    }
});

var component = new MyResource("...",
    ComponentResourceOptions.builder()
        .providers(awsUsEast1, myk8s)
        .build());

If a component resource is itself a child of another component resource, its set of providers is inherited from its parent by default.

Adding Multi-language Support

By default, components are authored and consumed in the same programming language by extending the ComponentResource class. The class can then be imported or referenced using the language’s applicable pattern. To support consuming components in other languages, Pulumi can introspect your component class and generate the necessary SDKs. To support multi-language consumption, a couple additional steps are required.

Define a `PulumiPlugin.yaml` file

In your component directory, create a PulumiPlugin.yaml file and specify the runtime the component is authored in.

runtime: nodejs

runtime: python

runtime: go

runtime: dotnet

runtime: java

Define an Entry Point

The entrypoint analyzes components to automatically build a schema, and interact with the Pulumi engine to mange the component lifecycle.

Not required for TypeScript.

Create a _main_.py file in your component directory
In the main function, add a call to component_provider_host, specifying a list of components for the components argument

from pulumi.provider.experimental import Metadata, component_provider_host
from staticpage import MyComponent

if __name__ == "__main__":
    component_provider_host(name="python-components", components=[MyComponent])

Define a main.go file
Declare an instance of NewProviderBuilder, passing in a name, namespace and the components being built

The code below uses the new pulumi-go-provider v1 APIs. Make sure you are using the latest version of github.com/pulumi/pulumi-go-provider.

package main

import (
    "context"
    "log"

    "github.com/pulumi/pulumi-go-provider/infer"
)

func main() {
    prov, err := infer.NewProviderBuilder().
            WithNamespace("your-org-name").
            WithComponents(
                infer.ComponentF(MyComponent),
            ).
            Build()
    if err != nil {
        log.Fatal(err.Error())
    }

    _ = prov.Run(context.Background(), "go-components", "v0.0.1")
}

Create a Program.cs file
Add an entry point that calls the ComponentProviderHost

using System.Threading.Tasks;

class Program
{
    public static Task Main(string []args) =>
        Pulumi.Experimental.Provider.ComponentProviderHost.Serve(args);
}

Create an App.java file
Create a new instance of ComponentProviderHost in the entry point

package com.example.components;

import java.io.IOException;
import com.pulumi.provider.internal.Metadata;
import com.pulumi.provider.internal.ComponentProviderHost;

public class App {
    public static void main(String[] args) throws IOException, InterruptedException {
        new ComponentProviderHost("java-components", App.class.getPackage()).start(args);
    }
}

Publishing the Component

Once a component is authored, it can be published to the IDP Private Registry or consumed directly from a git repo.

Private Registry Publishing

Pulumi Private Registry is the source of truth for an organization’s infrastructure building blocks like components and templates – the same components and templates that power golden path workflows in Pulumi. To learn more about publishing packages to the private registry, check out the Pulumi Private Registry guide.

Consumption

In the consuming Pulumi application, add the component as a dependency.

pulumi package add github.com/myorg/my-component

If you’re using version tags, you can specify those as well.

pulumi package add github.com/myorg/my-component@v1.0.0

Under the hood, Pulumi:

Fetches your code from GitHub
Generates a local SDK from the component’s schema
Makes the generated SDK available to your Pulumi program in your chosen language

For detailed information about working with local packages, including SDK generation and dependency management, see the Local Packages guide.

Referencing Components Locally

For scenarios like monorepos, rapid development iterations, or when you’re working with components that don’t need to be published to a repository, you can reference local source code directly:

pulumi package add /path/to/local/secure-s3-component

Pulumi will identify the folder as a Pulumi component project, generate a local SDK, and make it available for import in your program—even if your consumer program is in a different language.

The Spectrum of Pulumi Components You Can Build

You can use Pulumi Components with more flexibility and control depending on your use case. This table shows the variety of use cases:

Feature	Single language	Multi-language with Auto-Generated SDKs	Manual Schema and SDKs
Best for	Quick development within a single language ecosystem	Cross-language teams needing to share components	More flexibility and control needed or strict API requirements
Cross-language consumption	No - limited to original language	Yes - consume in any Pulumi language	Yes - consume in any Pulumi language but YAML
Setup complexity	Minimal - standard programming patterns	Minimal - just requires package management	High - requires schema authoring and validation
Development workflow	Fast iteration with direct code changes	Requires SDK regeneration when component changes	Complex with schema updates and SDK publishing
API control	N/A	Moderate - auto-generated from source	Full - ship the same interface to all consumers
Version management	Simple - standard code versioning	Moderate - requires careful API changes	Complex - strict semantic versioning needed
Typical user	Individual developers or same-language teams	Platform teams sharing with developers	Enterprise teams with strict requirements or package publishers
Ideal use cases	• Rapid prototyping • Single team projects • Simple components	• Organization-wide libraries • Platform engineering • Multi-language environments	• Published packages • Complex validation needs
Limitations	• Single language only	• SDK regeneration overhead • Runtime dependencies • Some translation limitations	• Complex setup • Steep learning curve • Slower iteration

Component resources

On this page

On this page

Authoring a New Component Resource

Component arguments and type requirements

Serialization requirements

Supported types

Unsupported types

Design recommendations

Constructor requirements by language

Best practices

Creating Child Resources

Registering Component Outputs

What RegisterOutputs Does

Inheriting Resource Providers

Adding Multi-language Support

Define a `PulumiPlugin.yaml` file

Define an Entry Point

Publishing the Component

Private Registry Publishing

Consumption

Referencing Components Locally

The Spectrum of Pulumi Components You Can Build

On this page

On this page

Component resources

On this page

On this page

Authoring a New Component Resource

Component arguments and type requirements

Serialization requirements

Supported types

Unsupported types

Design recommendations

Constructor requirements by language

Best practices

Creating Child Resources

Registering Component Outputs

What RegisterOutputs Does

Inheriting Resource Providers

Adding Multi-language Support

Define a PulumiPlugin.yaml file

Define an Entry Point

Publishing the Component

Private Registry Publishing

Consumption

Referencing Components Locally

The Spectrum of Pulumi Components You Can Build

On this page

On this page

Define a `PulumiPlugin.yaml` file