Authoring Pulumi Components
A ComponentResource groups related infrastructure resources into a reusable, logical unit. Components make infrastructure easier to understand, reuse, and maintain. Components appear as a single node with children nested underneath in pulumi preview/pulumi up output and in the Pulumi Cloud console.
This skill covers the full component authoring lifecycle. For general Pulumi coding patterns (Output handling, secrets, aliases, preview workflows), use the pulumi-best-practices skill instead.
When to Use This Skill
Invoke this skill when:
- Creating a new ComponentResource class
- Designing the args interface for a component
- Making a component consumable from multiple Pulumi languages
- Publishing or distributing a component package
- Refactoring inline resources into a reusable component
- Debugging component behavior (missing outputs, stuck creating, children at wrong level)
Component Anatomy
Every component has four required elements:
- Extend ComponentResource and call
super()with a type URN - Accept standard parameters: name, args, and
ComponentResourceOptions - Set
parent: thison all child resources - Call
registerOutputs()at the end of the constructor
TypeScript
Python
Type URN Format
The first argument to super() is the type URN: <package>:<module>:<type>.
Full examples: myorg:index:StaticSite, acme:index:KubernetesCluster
registerOutputs Is Required
Why: Without registerOutputs(), the component appears stuck in a "creating" state in the Pulumi console and outputs are not persisted to state.
Wrong:
Right:
Derive Child Names from the Component Name
Why: Hardcoded child names cause collisions when the component is instantiated multiple times.
Wrong:
Right:
Designing the Args Interface
The args interface is the most impactful design decision. It defines what consumers can configure and how composable the component is.
Wrap Properties in Input<T>
Why: Input<T> accepts both plain values and Output<T> from other resources. Without it, consumers must unwrap outputs manually with .apply().
Wrong:
Right:
Keep Structures Flat
Avoid deeply nested arg objects. Flat interfaces are easier to use and evolve.
No Union Types
Union types break multi-language SDK generation. Python, Go, and C# cannot represent string | number.
Wrong:
Right:
If you need to accept multiple forms, use separate optional properties:
No Functions or Callbacks
Functions cannot be serialized across language boundaries.
Wrong:
Right:
Use Defaults for Optional Properties
Set sensible defaults inside the constructor so consumers only configure what they need:
Exposing Outputs
Expose Only What Consumers Need
Components often create many internal resources. Expose only the values consumers need, not every internal resource.
Wrong:
Right:
Derive Composite Outputs
Use pulumi.interpolate or pulumi.concat to build derived values:
Component Design Patterns
Sensible Defaults with Override
Encode best practices as defaults. Allow consumers to override when they have specific requirements.
Conditional Resource Creation
Use optional args to gate creation of sub-resources:
Composition
Build higher-level components from lower-level ones. Each level manages a single concern.
Provider Passthrough
Accept explicit providers for multi-region or multi-account deployments. ComponentResourceOptions carries provider configuration to children automatically:
Children with { parent: this } automatically inherit the provider. No extra code is needed inside the component.
Multi-Language Components
If your component will be consumed from multiple Pulumi languages (TypeScript, Python, Go, C#, Java, YAML), package it as a multi-language component.
Do You Need Multi-Language?
Ask: "Will anyone consume this component from a different language than it was authored in?"
Single-language component (no packaging needed):
- Your team uses one language and the component stays within that codebase
- The component is internal to a single project or monorepo
- No
PulumiPlugin.yamlneeded -- just import the class directly
Multi-language component (packaging required):
- Other teams consume your component in different languages
- Platform teams building abstractions for developers who choose their own language
- YAML consumers need access -- even if you author in TypeScript, YAML programs require multi-language packaging to use your component
- Building a shared component library for your organization
- Publishing to the Pulumi private registry or public registry is a common reason, but not required for multi-language support
Common mistake: A TypeScript platform team builds components only their TypeScript users can consume. If application developers use Python or YAML, those components are invisible to them without multi-language packaging.
Setup
Create a PulumiPlugin.yaml in the component directory to declare the runtime:
Or for Python:
Serialization Constraints
For multi-language compatibility, args must be serializable. These constraints apply regardless of the authoring language:
Consuming Multi-Language Components
Consumers install the component with pulumi package add, which automatically downloads the provider plugin, generates a local SDK in the consumer's language, and updates Pulumi.yaml:
For fresh checkouts or CI environments, run pulumi install to ensure all package dependencies are available. The consumer does not need to manually generate SDKs.
Authors who publish SDKs to package managers (npm, PyPI, etc.) can optionally use pulumi package gen-sdk to generate language-specific SDKs for publishing. Most component authors do not need this -- pulumi package add handles SDK generation on the consumer side.
Entry Points
Published multi-language components require an entry point that hosts the component provider process. The entry point pattern differs by language.
TypeScript (runtime: nodejs):
Export component classes from index.ts. No separate entry point file is needed. Pulumi introspects exported classes automatically.
Python (runtime: python):
Create a __main__.py that calls component_provider_host with all component classes:
Go (runtime: go):
Create a main.go that builds and runs the provider:
C# (runtime: dotnet):
Create a Program.cs that serves the component provider host:
For a complete working example across all languages, see https://github.com/mikhailshilkov/comp-as-comp.
Reference: https://www.pulumi.com/docs/iac/using-pulumi/pulumi-packages/
Distribution
Choose a distribution method based on your audience:
Pulumi Private Registry
The private registry is the centralized catalog for your organization's components. It provides automatic API documentation, version management, and discoverability for all teams.
Publish a component to the private registry:
Version components using git tags with a v prefix:
A README file is required when publishing. Pulumi uses it as the component's documentation page in the registry.
Automate publishing from GitHub Actions using OIDC authentication:
Prerequisites: Configure GitHub OIDC integration with Pulumi Cloud before using this workflow.
The registry supports private GitHub and GitLab repositories. For non-OIDC setups, authenticate with GITHUB_TOKEN or GITLAB_TOKEN environment variables.
The private registry automatically generates SDK documentation for each published component. Enrich the generated docs by adding type annotations to your component's inputs and outputs (JSDoc in TypeScript, docstrings in Python, Annotate() methods in Go).
Reference: https://www.pulumi.com/docs/idp/get-started/private-registry/
Git Repository Distribution
Tag releases for consumers to pin versions:
Consumers install with:
Package Manager Distribution
Publish language-specific packages for native dependency management:
- npm:
npm publishfor TypeScript/JavaScript - PyPI:
twine uploadfor Python - NuGet:
dotnet nuget pushfor .NET - Maven Central: Standard Maven publishing for Java
Reference: https://www.pulumi.com/docs/iac/using-pulumi/pulumi-packages/
Anti-Patterns
Quick Reference
Related Skills
- pulumi-best-practices: General Pulumi patterns including Output handling, secrets, and aliases
- pulumi-automation-api: Programmatic orchestration for integration testing and multi-stack workflows
- pulumi-esc: Centralized secrets and configuration for component deployments
References
- https://www.pulumi.com/docs/iac/concepts/resources/components/
- https://www.pulumi.com/docs/iac/using-pulumi/pulumi-packages/
- https://www.pulumi.com/docs/idp/get-started/private-registry/
- https://www.pulumi.com/docs/iac/concepts/inputs-outputs/
- https://www.pulumi.com/docs/iac/concepts/resources/options/aliases/


