Add component packaging guide and reorganize cross-language content #17336
Conversation
This commit adds a new "Packaging a Component" guide that provides a comprehensive comparison of three component packaging approaches: single-language, cross-language, and provider-based components. The guide helps users choose the right approach based on their team size, language diversity, and runtime requirements. Changes: - Add packaging-a-component.md with detailed comparison guide - Add cross-language-components.md with implementation details - Remove duplicate cross-language content from components/_index.md - Update build-a-component.md to reference new packaging guide - Add cross-references in building-extending/_index.md and private-registry.md The new guide includes decision criteria, advantages/limitations for each approach, and a summary table comparing key features. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Documentation ReviewThis PR adds comprehensive component packaging guidance and successfully reorganizes cross-language content. The new structure improves discoverability and provides clear decision criteria for choosing packaging approaches. Issues FoundSpelling ErrorLine 83 in packaging-a-component.md: Issue: "Regisitry" should be "Registry" Suggestion: Missing Leading Slash in LinkLine 83 in packaging-a-component.md: Current: [Publishing Pulumi packages](docs/iac/guides/building-extending/packages/publishing-packages/)Should be: [Publishing Pulumi packages](/docs/iac/guides/building-extending/packages/publishing-packages/)Inconsistent TerminologyLines 65 and 67 in cross-language-components.md: Current: ### Define an entry point
The entrypoint analyzes components...Suggestion: Use "entry point" (two words) consistently throughout for better readability: Positive Observations
SummaryThe reorganization successfully separates concerns: the main components page now focuses on concepts, the new cross-language-components.md covers implementation details, and packaging-a-component.md provides decision guidance. After fixing the three issues above, this PR will significantly improve the component documentation. Please mention me (@claude) if you'd like me to review any updates or help fix these issues. |
|
Your site preview for commit 4ecee57 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-17336-4ecee571.s3-website.us-west-2.amazonaws.com. |
iwahbe
left a comment
iwahbe
left a comment
There was a problem hiding this comment.
I'm fuzzy on the difference between Cross-language components and Provider-based components. Everything else looks great.
|
|
||
| ## 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. |
There was a problem hiding this comment.
This is true in some languages, but not all languages.
There was a problem hiding this comment.
"Not all languages" -> We're talking about Go (b/c it doesn't have inheritance) and YAML, I presume?
|
|
||
| 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" >}} |
There was a problem hiding this comment.
You can also write components in YAML.
There was a problem hiding this comment.
This content is temporary because it's already covered here (including YAML): https://www.pulumi.com/docs/iac/guides/building-extending/components/build-a-component/
We will de-duplicate the content in a fast-follow issue.
content/docs/iac/concepts/components/cross-language-components.md
Outdated
Show resolved
Hide resolved
|
|
||
| {{< /notes >}} | ||
|
|
||
| ### Generating local SDKs with pulumi install |
There was a problem hiding this comment.
If you use pulumi package add, you don't need to run pulumi install as follow-up, since pulumi package add already generates the SDKs for you. pulumi install will actually re-generate them.
content/docs/iac/guides/building-extending/components/packaging-a-component.md
Show resolved
Hide resolved
| 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.). |
There was a problem hiding this comment.
This is probably the wrong place for this discussion, but we already allow components written in other languages in the public registry, and we shouldn't require that people publish SDKs in all languages.
There was a problem hiding this comment.
pulumi package add will work for anything with a schema.
| 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 |
There was a problem hiding this comment.
This is also true for "Cross-language components" written in Go. Go only has one library for authoring Pulumi resources, both custom & component.
| - **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 |
There was a problem hiding this comment.
That's not true, they can be published to the IDP registry. I think they just don't display in IDP docs right now, but that may have changed. CC @fnune
content/docs/iac/guides/building-extending/components/packaging-a-component.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Ian Wahbe <me@iwahbe.com>
…g-a-component.md Co-authored-by: Ian Wahbe <me@iwahbe.com>
|
Your site preview for commit 1dc3679 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-17336-1dc36792.s3-website.us-west-2.amazonaws.com. |
|
Your site preview for commit 614b178 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-17336-614b1785.s3-website.us-west-2.amazonaws.com. |
- Fix grammar: "an SDKs" → "SDKs" - Fix typo: "Regisitry" → "Registry" - Fix broken link: add leading slash to publishing-packages path Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
CamSoper
left a comment
CamSoper
left a comment
There was a problem hiding this comment.
I've applied some minor style and formatting fixes. LGTM!
This is an excellent reorganization of the component packaging documentation. The new guide provides a clear decision framework for users choosing between packaging approaches, and the comparison table is particularly helpful.
Changes applied:
- Fixed grammar: "an SDKs" → "SDKs"
- Fixed typo: "Regisitry" → "Registry"
- Fixed broken link: added leading slash to publishing-packages path
|
Your site preview for commit c935175 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-17336-c9351750.s3-website.us-west-2.amazonaws.com. |
CamSoper
left a comment
CamSoper
left a comment
There was a problem hiding this comment.
Reverting approval to test tooling -- No changes actually required.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
CamSoper
left a comment
CamSoper
left a comment
There was a problem hiding this comment.
Applied minor style fixes. LGTM! Excellent reorganization of the component packaging docs.
|
Your site preview for commit aa1b3dc is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-17336-aa1b3dcc.s3-website.us-west-2.amazonaws.com. |
kramhuber
left a comment
kramhuber
left a comment
There was a problem hiding this comment.
Killer. Really well done.
This commit adds a new "Packaging a Component" guide that provides a comprehensive comparison of three component packaging approaches: single-language, cross-language, and provider-based components. The guide helps users choose the right approach based on their team size, language diversity, and runtime requirements.
Changes:
The new guide includes decision criteria, advantages/limitations for each approach, and a summary table comparing key features.
Fixes #16795