Skip to content

Add component packaging guide and reorganize cross-language content #17336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jkodroff wants to merge 5 commits into
base: master
Choose a base branch
from
+372 −243
Open

Add component packaging guide and reorganize cross-language content #17336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4ecee57
Add component packaging guide and reorganize cross-language content
jkodroff Jan 29, 2026
1dc3679
Update content/docs/iac/concepts/components/cross-language-components.md
jkodroff Jan 29, 2026
614b178
Update content/docs/iac/guides/building-extending/components/packagin…
jkodroff Jan 29, 2026
c935175
Apply style and formatting fixes
CamSoper Jan 29, 2026
aa1b3dc
Apply style and formatting fixes
CamSoper Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 4 additions & 201 deletions content/docs/iac/concepts/components/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -648,207 +648,10 @@ var component = new MyResource("...",

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
## Cross-language components

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.
By default, components are authored and consumed in the same programming language by extending the `ComponentResource` class. However, components can also be made available to programs written in other languages. When configured for cross-language support, Pulumi can introspect your component class and automatically generate SDKs for consumption in any Pulumi language.

### Define a `PulumiPlugin.yaml` file
For detailed information on setting up and using cross-language components, including how to configure `PulumiPlugin.yaml`, define entry points, publish, and consume components, see [Cross-language Components](/docs/iac/concepts/components/cross-language-components/).

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

{{< chooser language "typescript,python,go,csharp,java" >}}

{{% choosable language typescript %}}

```typescript
runtime: nodejs
```

{{% /choosable %}}
{{% choosable language python %}}

```python
runtime: python
```

{{% /choosable %}}
{{% choosable language go %}}

```go
runtime: go
```

{{% /choosable %}}
{{% choosable language csharp %}}

```csharp
runtime: dotnet
```

{{% /choosable %}}
{{% choosable language java %}}

```java
runtime: java
```

{{% /choosable %}}

{{< /chooser >}}

### Define an Entry Point

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

{{< chooser language "typescript,python,go,csharp,java" >}}

{{% choosable language typescript %}}

Not required for TypeScript.

{{% /choosable %}}
{{% choosable language python %}}

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

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

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

{{% /choosable %}}
{{% choosable language go %}}

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

{{% notes type="info" %}}
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`.
{{% /notes %}}

```go
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")
}
```

{{% /choosable %}}
{{% choosable language csharp %}}

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

```csharp
using System.Threading.Tasks;

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

{{% /choosable %}}
{{% choosable language java %}}

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

```java
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);
}
}
```

{{% /choosable %}}

{{< /chooser >}}

### Publishing the Component

Once a component is authored, it can be published to the [IDP Private Registry](/docs/idp/get-started/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](/docs/iac/concepts/resources/components/) and [templates](/docs/idp/developer-portals/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](/docs/idp/get-started/private-registry/).

#### Consumption

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

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

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

```bash
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

{{< notes type="info" >}}
For detailed information about working with local packages, including SDK generation and dependency management, see the [Local Packages](/docs/iac/guides/building-extending/packages/local-packages/) guide.
{{< /notes >}}

#### 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:

```bash
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<br>• Single team projects<br>• Simple components | • Organization-wide libraries<br>• Platform engineering<br>• Multi-language environments | • Published packages<br>• Complex validation needs |
| **Limitations** | • Single language only<br> | • SDK regeneration overhead<br>• Runtime dependencies<br>• Some translation limitations | • Complex setup<br>• Steep learning curve<br>• Slower iteration |
For a comparison of all component packaging approaches (single-language, cross-language, and provider-based), see [Packaging a Component](/docs/iac/guides/building-extending/components/packaging-a-component/).
Loading
Loading