diff --git a/content/docs/iac/concepts/components/_index.md b/content/docs/iac/concepts/components/_index.md index 94d5399a17e5..0cac5d92a848 100644 --- a/content/docs/iac/concepts/components/_index.md +++ b/content/docs/iac/concepts/components/_index.md @@ -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
• 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 | +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/). diff --git a/content/docs/iac/concepts/components/cross-language-components.md b/content/docs/iac/concepts/components/cross-language-components.md new file mode 100644 index 000000000000..bb4748a5c8e1 --- /dev/null +++ b/content/docs/iac/concepts/components/cross-language-components.md @@ -0,0 +1,238 @@ +--- +title_tag: "Cross-language Components" +meta_desc: "Learn how to create Pulumi components that can be consumed in any language with auto-generated SDKs." +title: Cross-language Components +h1: Cross-language Components +meta_image: /images/docs/meta-images/docs-meta.png +menu: + iac: + parent: iac-concepts-components + weight: 5 +aliases: +- /docs/iac/concepts/components/cross-language-components/ +--- + +Cross-language components support consumption in any Pulumi language. You implement the component once in your preferred language, and Pulumi automatically generates SDKs for other languages. + +## 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. + +{{< 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 +1. 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 +1. 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 +1. 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 +1. 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 >}} + +## Distribution + +### Sharing via Git + +Storing a component in a Git repository allows for version control, collaboration, and easier integration into multiple projects. Developers can add the component to their Pulumi projects using the command: + +```bash +$ pulumi package add [/path/to/component]@ +``` + +The only steps necessary to enable this are to push your component project to a git repo, and create a release tag for the versioning. Pulumi supports referencing both GitHub and GitLab releases. You can also target a standard internally hosted git service, just by providing the repo URL without the `` portion. + +Pulumi will automatically generate the needed language-specific end user SDK for your project. For example, if the Pulumi project was written in Python, the `pulumi package add` command would detect this and generate the Python SDK on-the-fly, as well as adding the dependency to your `requirements.txt` and running `pip install -r requirements.txt` for you. The output will also give you an example of the correct `import` statement to use the component. + +``` +$ pulumi package add https://github.com/pulumi/staticpagecomponent@v0.1.0 +Downloading provider: github.com_pulumi_staticpagecomponent.git +Successfully generated a Python SDK for the staticpagecomponent package at /example/use-static-page-component/sdks/staticpagecomponent + +[...] + +You can then import the SDK in your Python code with: + + import pulumi_static_page_component as static_page_component +``` + +{{< notes type="tip" >}} + +Pulumi also supports private repos in GitHub and GitLab. Pulumi will read standard environment variables like `GITHUB_TOKEN` and `GITLAB_TOKEN` if available in order to authenticate access to a private repo during `pulumi package add`. + +{{< /notes >}} + +### Generating local SDKs with pulumi install + +Once you've added an entry to the packages section of your Pulumi.yaml file, you can run `pulumi install` to generate a local SDK in your project. This command will process all packages listed in your Pulumi.yaml and create the necessary SDK files. Check in these files if you want fully reproducible builds, or add them to .gitignore if you prefer to regenerate them on each checkout. When using .gitignore, team members will need to run `pulumi install` after checkout to regenerate the SDK. + +### Publishing to Pulumi IDP Private Registry + +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. + +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 package](/docs/iac/guides/building-extending/packages/local-packages/) 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 package SDK, and make it available for import in your program—even if your consumer program is in a different language. diff --git a/content/docs/iac/guides/building-extending/_index.md b/content/docs/iac/guides/building-extending/_index.md index 48bbc90315e6..38af2215172f 100644 --- a/content/docs/iac/guides/building-extending/_index.md +++ b/content/docs/iac/guides/building-extending/_index.md @@ -28,6 +28,8 @@ Build reusable infrastructure components to encapsulate and share infrastructure **[Testing Components](/docs/iac/guides/building-extending/components/testing-components/)** - Write automated tests for your components to ensure they work correctly and maintain quality as they evolve. +**[Package a Component](/docs/iac/guides/building-extending/components/packaging-a-component/)** - Choose the right packaging approach for your components: single-language, cross-language, or provider-based distribution. + ## Providers Create custom providers to integrate new cloud platforms and services with Pulumi. diff --git a/content/docs/iac/guides/building-extending/components/build-a-component.md b/content/docs/iac/guides/building-extending/components/build-a-component.md index e4791b035c5a..3b4879de31c7 100644 --- a/content/docs/iac/guides/building-extending/components/build-a-component.md +++ b/content/docs/iac/guides/building-extending/components/build-a-component.md @@ -2909,46 +2909,8 @@ Duration: 10s Success! We were able to use our component as just a single resource within our Pulumi program and it managed five other resources under the hood for us. This greatly reduces the amount of code an end user has to write to be able to host an HTML file in S3. -## Sharing and Reuse +## Next steps -In the above examples, the component was referenced from a nearby directory, local to the machine. In order to share a component, it needs to be accessed outside of your local machine. There are two main ways to do that; sharing via a Git repo, or publishing as a Pulumi Package. +Now that you've built a component, you can package and distribute it for reuse. See [Packaging a Component](/docs/iac/guides/building-extending/components/packaging-a-component/) to learn about single-language, cross-language, and provider-based packaging approaches. -### Sharing via Git - -Storing a component in a Git repository allows for version control, collaboration, and easier integration into multiple projects. Developers can add the component to their Pulumi projects using the command: - -```bash -$ pulumi package add @ -``` - -The only steps necessary to enable this are to push your component project to a git repo, and create a release tag for the versioning. Pulumi supports referencing both GitHub and GitLab releases. You can also target a standard internally hosted git service, just by providing the repo URL without the `` portion. - -Pulumi will automatically generate the needed language-specific end user SDK for your project. For example, if the Pulumi project was written in Python, the `pulumi package add` command would detect this and generate the Python SDK on-the-fly, as well as adding the dependency to your `requirements.txt` and running `pip install -r requirements.txt` for you. The output will also give you an example of the correct `import` statement to use the component. - -``` -$ pulumi package add https://github.com/pulumi/staticpagecomponent@v0.1.0 -Downloading provider: github.com_pulumi_staticpagecomponent.git -Successfully generated a Python SDK for the staticpagecomponent package at /example/use-static-page-component/sdks/staticpagecomponent - -[...] - -You can then import the SDK in your Python code with: - - import pulumi_static_page_component as static_page_component -``` - -{{< notes type="tip" >}} - -Pulumi also supports private repos in GitHub and GitLab. Pulumi will read standard environment variables like `GITHUB_TOKEN` and `GITLAB_TOKEN` if available in order to authenticate access to a private repo during `pulumi package add`. - -{{< /notes >}} - -### Generating Local SDKs with pulumi install - -Once you've added an entry to the packages section of your Pulumi.yaml file, you can run `pulumi install` to generate a local SDK in your project. This command will process all packages listed in your Pulumi.yaml and create the necessary SDK files. Check in these files if you want fully reproducible builds, or add them to .gitignore if you prefer to regenerate them on each checkout. When using .gitignore, team members will need to run `pulumi install` after checkout to regenerate the SDK. - -### Sharing via Pulumi Package - -Publishing a component as a Pulumi package makes it easier to distribute and integrate into Pulumi workflows. This method enables community contributions and ensures that infrastructure components remain modular and maintainable. By packaging the component, it becomes easier to reuse across teams and projects, improving consistency and efficiency in infrastructure management. It also makes your component available for use within Pulumi Cloud Deployments. - -Learn more in the [Publishing packages](/docs/iac/using-pulumi/extending-pulumi/publishing-packages/) guide. +For testing strategies, see [Testing Components](/docs/iac/guides/building-extending/components/testing-components/). diff --git a/content/docs/iac/guides/building-extending/components/packaging-a-component.md b/content/docs/iac/guides/building-extending/components/packaging-a-component.md new file mode 100644 index 000000000000..4b4b9cec9319 --- /dev/null +++ b/content/docs/iac/guides/building-extending/components/packaging-a-component.md @@ -0,0 +1,122 @@ +--- +title_tag: "Packaging a Component" +meta_desc: "Learn how to package and distribute Pulumi components using single-language, cross-language, and provider-based approaches." +title: Packaging a Component +h1: Packaging a Component +meta_image: /images/docs/meta-images/docs-meta.png +menu: + iac: + name: Package a Component + parent: iac-guides-components + weight: 30 +aliases: +- /docs/iac/guides/building-extending/components/packaging-a-component/ +--- + +Once you've authored a Pulumi component, you will probably want to package and distribute it so others can use it. This guide covers three different approaches to packaging components, each with different trade-offs for distribution, versioning, and discoverability. + +## Choosing a packaging approach + +Pulumi offers three ways to package components: + +1. **[Single-language components](#single-language-components)**: Share components as source code with native package managers. Single-language components are a good fit for smaller organizations where all Pulumi code is written in a single language. +1. **[Cross-language components](#cross-language-components)**: Support multiple languages with auto-generated SDKs from a single implementation. Cross-language components are a good fit for platform teams who want to create reusable abstractions to consume internally or to provide self-service for application teams. +1. **[Provider-based components](#provider-based-components)**: Build components as Pulumi providers with zero runtime dependencies for consumers. Provider-based components are a good fit for organizations with a high degree of Pulumi expertise who expect to distribute components to a large number of teams across many languages or organizations with specific runtime requirements. + +{{% notes type="info" %}} +Most platform teams should consider cross-language components as their default option because they provide multi-language consumption with minimal overhead and also have enhanced support within Pulumi Cloud. +{{% /notes %}} + +## Single-language components + +Single-language components are written and consumed in the same language and behave just like any other shareable class in your language of choice. You distribute single-language components by publishing packages in the language's package manager (npm, PyPI, etc.). Because single-language components are limited to the language of authorship, they are a good fit for smaller teams or organizations that expect to only ever use Pulumi in a single language. + +### Distribution and consumption + +Single-language components are distributed via the native package management tool for the language in which the component is authored: npm for TypeScript, PyPI for Python, Go modules, etc. They are consumed by adding a reference to the package (or importing from a local path on disk), just like any other module or package. + +### Advantages and limitations + +When considering single-language components, bear the following tradeoffs in mind: + +- **Lowest overhead**: Components work like any other class in your language and do not require SDKs +- **No argument type limitations**: Arguments to single-language components can use any type, including union types, as they do not need to be serializable +- **Single language only**: Cannot be consumed from other Pulumi languages +- **No Pulumi IDP support**: Cannot be published to Pulumi IDP Private Registry at this time + +## Cross-language components + +Cross-language components support consumption in any Pulumi language. You implement the component once in your preferred language, and Pulumi automatically generates SDKs via [local packages](/docs/iac/guides/building-extending/packages/local-packages/) for other languages when the component is added to a downstream Pulumi program. + +For detailed information on packaging and using cross-language components, see [Cross-language Components](/docs/iac/concepts/components/cross-language-components/). + +{{% notes type="info" %}} +A common usage pattern for cross-language components is for a platform team to author components in a general purpose language (like TypeScript), publish those components in Pulumi Cloud IDP for discoverability and auto-generated documentation, and then allow application teams to consume those components so they can compose the infrastructure for their applications in the language of their choosing (including YAML). + +This pattern gives a high degree of self-service to application teams so that they are able to consume infrastructure patterns without needing to know the details about how to create and connect every individual resource. Applications teams are still free to add additional resources to their Pulumi code in cases where the platform team does not have a suitable component published. +{{% /notes %}} + +### Distribution and consumption + +Because cross-language components are distributed as source, they do not need to be explicitly published. Consumers use the [`pulumi package add`](/docs/iac/cli/commands/pulumi_package_add/) command to install the component, specifying a git URL and revision (or a local path for monorepos or local testing), and Pulumi automatically generates the appropriate language SDK as a [local package](/docs/iac/guides/building-extending/packages/local-packages/). + +Pulumi Cloud customers can explicitly publish versions of components to Pulumi IDP Private Registry using the [`pulumi package publish`](/docs/iac/cli/commands/pulumi_package_publish/) command. Publishing a package to Pulumi Cloud gives platform teams the ability to provide self-service to application teams by sharing components in a browsable gallery complete with READMEs and auto-generated SDK documentation in all Pulumi languages. + +### Advantages and limitations + +When considering cross-language components, bear the following tradeoffs in mind: + +- **Write and consume in any language**: Cross-language components can be written in and consumed by any supported Pulumi language +- **Lowest overhead for distribution**: Cross-language components are distributed as source via git references (SHA, branch, or tag) and do not require a build artifact (binary or published SDKs) in order to be consumed +- **Pulumi IDP support**: Can be published to Pulumi Cloud for discoverability and automatic API documentation +- **SDK regeneration overhead**: Consumers must regenerate SDKs when the component is updated +- **Runtime dependencies**: Consumers must have the runtime installed for the language in which the component is written (Node.js, Python, etc.) +- **Argument type limitations**: Because calls to cross-language components are serialized, there are some limitations on the types that can be included in the component's resources. For more information see [Component arguments and type requirements](/docs/iac/concepts/components/#component-arguments-and-type-requirements) + +## Provider-based components + +Provider-based components are built as full Pulumi [providers](/docs/iac/concepts/providers/). They compile to native binaries with no runtime dependencies and can include both [component resources and custom resources](/docs/iac/concepts/resources/#resources). Because provider-based components have a higher overhead for CI/CD and publishing, and in most cases are written in Go, they are a fit for very large organizations that have many teams using many different languages, or organizations where the runtime requirements for cross-language components are not suitable. + +{{% notes type="info" %}} +If you want to create a component for public consumption and publish it in the [Pulumi Registry](/registry), you should create a provider-based component, author it in Go, and publish SDKs in the public feeds for each language (npmjs.org, etc.). + +For more information on submitting packages to the Pulumi Registry, see [Publishing Pulumi packages](/docs/iac/guides/building-extending/packages/publishing-packages/). +{{% /notes %}} + +### Distribution and consumption + +Provider-based components are typically distributed as pre-built SDKs published to multiple package managers (one for each language a consumer would use). The provider binary must also be published in an accessible location. + +Consumers install the published SDKs (like any other Pulumi provider package). Pulumi will automatically download (and cache) the provider binary when the consuming Pulumi program is first run (just like providers). + +For more information on authoring providers see [Build a provider](/docs/iac/guides/building-extending/providers/build-a-provider/) + +### Advantages and Limitations + +When considering provider-based components, bear the following tradeoffs in mind: + +- **No runtime dependencies for consumers**: Consumers don't need Node.js, Python, or any other runtime installed because the provider plugin is distributed as a native binary +- **Full provider capabilities**: In addition to any components you want to include in the package, provider packages written in Go can also include custom resources that make direct API calls +- **Go strongly recommended**: Providers are usually written in Go because the Pulumi supported tooling makes maintaining the provider [schema](/docs/iac/guides/building-extending/packages/schema/) significantly easier compared to other languages (see note for details) +- **CI/CD Overhead**: Provider-based components typically have pre-published SDKs, which requires a more involved CI/CD process (including publishing to a package feed after a release) +- **Argument type limitations**: Because calls to provider-based components are serialized, there are some limitations on the types that can be included in the component's resources. For more information see [Component arguments and type requirements](/docs/iac/concepts/components/#component-arguments-and-type-requirements) +- **No Pulumi IDP support**: Cannot be published to Pulumi IDP Private Registry + +{{% notes type="info" %}} +Providers (and provider-based components) may technically be written in any language if the author is willing to hand-author the schema. Maintaining schemas by hand is labor-intensive and the learning curve maintaining schemas may be prohibitive for many teams. Pulumi provides tooling in the [`pulumi-go-provider`](https://github.com/pulumi/pulumi-go-provider) framework to automatically infer the schema and reduce the need for manually maintained schema files. Pulumi does not provide tooling for inferring schemas in languages other than Go. + +Consuming providers written in languages other than Go requires consumers to have the runtime of the provider's language installed, similar to Cross-language components. +{{% /notes %}} + +## Component packaging summary + +The table below summarizes the trade-offs between the three packaging approaches: + +| Feature | Single-language components | Cross-language components | Provider-based components | +|---------|--------------------------|-------------------------------------------|--------------------------| +| **Best for** | Smaller organizations using a single language | Platform teams providing reusable abstractions and self-service | Organizations distributing to many teams/languages or with specific runtime requirements, or components designed for public consumption | +| **Cross-language consumption** | No - limited to original language | Yes - consume in any Pulumi language | Yes - consume in any Pulumi language| +| **Pulumi Cloud IDP Private Registry support** | No | Yes | No | +| **Packaging complexity** | Minimal - publish a native package | Low - requires PulumiPlugin.yaml and entry points | High - requires schema authoring, SDK generation, and binary publishing | +| **Distribution** | Source published to package managers (npm, PyPI, etc.) | Pulumi IDP Private Registry and/or git references | Pre-built SDKs published to native package managers | +| **Runtime dependencies** | n/a | Language runtime for authoring language required | None - distributed as native binary | diff --git a/content/docs/idp/get-started/private-registry.md b/content/docs/idp/get-started/private-registry.md index 029f98878a29..fa43d4950655 100644 --- a/content/docs/idp/get-started/private-registry.md +++ b/content/docs/idp/get-started/private-registry.md @@ -20,9 +20,11 @@ Developers leverage templates and components in their preferred workflows, wheth [Pulumi Components](/docs/iac/concepts/resources/components/) are a way to encapsulate resources in a reusable manner. Components are also a powerful way for platform teams to integrate security, compliance, and operational requirements into golden paths so that developers don't need to worry about it. Once a component is pushed to GitHub or GitLab, it is published to an organization's private registry using the `publish` CLI command. Pulumi automatically introspects the component schema and generates API docs, which are displayed in the registry. +For detailed information about different component packaging approaches, see [Packaging a Component](/docs/iac/guides/building-extending/components/packaging-a-component/). + ### Publishing Components -If you're new to Pulumi components, the [Build a Component](/docs/iac/using-pulumi/extending-pulumi/build-a-component/) guide is a great resource for getting started. Once you've authored your component, push it to a GitHub or GitLab repository that Pulumi can access. Private repositories are supported, but the repository must be open to inbound requests. +If you're new to Pulumi components, the [Build a Component](/docs/iac/guides/building-extending/components/build-a-component/) guide is a great resource for getting started. Once you've authored your component, push it to a GitHub or GitLab repository that Pulumi can access. Private repositories are supported, but the repository must be open to inbound requests. The `publish` CLI command is used to publish components to the private registry.