Components: Packaging Components Guide

[jkodroff]

Create a guide that explains the packaging strategy options:

1. Single-language components, distributed via language-native package managers (like npm)
2. Cross-language components, written in any language and consumable in any language via an automatically generated schema and local package SDK, consumed via pulumi package add, can be published to Pulumi IDP
3. Provider-based components, written in Go with pre-generated SDKs pushed to package feeds, consumed like Pulumi providers (e.g. by installing the SDK)

Create a new page "Packaging a Component". Make it a sibling of the current "Build a Component" guide. The content should have the following basic structure:

• Introduction: Why components are useful in general, how they can be distributed and shared, and what criteria is involved in deciding which approach to take
• Note that the process of authoring a component (inheriting from ComponentResource, etc.) is identical between all approaches (with the exception that inputs and outputs for cross-language and provider-based have some restrictions on what types they can support and link to topic below)
• Single-language components:
  • Where they are a good fit: smaller orgs, orgs only using a single language
  • Needs a (likely) private package feed to distribute
  • Relies upon documentation in the package description and API docs (cross-language components have auto-generated docs when published to Pulumi IDP)
  • Consumed by installing the published package (e.g. npm i)
• Cross-language components:
  • Where they are a good fit: platform teams providing self-service to application teams, medium to large orgs, best fit for most organizations
  • Specifically call out the pattern of platform teams authoring in their preferred language, allowing app teams to consume in their preferred language (including YAML)
  • Requires the consumer to have the runtime installed e.g. TypeScript-authored components require consumers to have nodejs installed. Requirements for runtimes are detailed in e.g. https://www.pulumi.com/docs/iac/languages-sdks/
  • Can publish to Pulumi IDP, will auto-generate docs, provide discoverability to app teams
  • Consumed by pulumi package add
• Provider-based components:
  • Good fit: usually very large orgs supporting many teams
  • Go has the pulumi-go-provider framework which handles most schema generation, plus Go compiles to a native binary and therefore has no runtime requirement for downstream providers. While it's possible to write a provider in any language, there's no schema tooling in other languages, so for all practical purposes, they must be written in Go.
  • The release process should publish SDKs in all languages in which the publisher intends to support consumption.
  • Pulumi IDP doesn't have support for publishing at this time
  • Can also add raw CustomResources (the base type of resource where the author defines the CRUD methods) in the same package
• Include https://www.pulumi.com/docs/iac/concepts/components/#adding-multi-language-support (and remove from its original source)
• Move content from https://www.pulumi.com/docs/iac/guides/building-extending/components/build-a-component/#sharing-and-reuse into this page.
• The section https://www.pulumi.com/docs/iac/guides/building-extending/components/build-a-component/#sharing-via-pulumi-package should be removed because it refers to publishing to the Pulumi (public) Registry.

Finally, we can include this detailed table at the end of the guide (but change the table heading to match the newer terminology): https://www.pulumi.com/docs/iac/concepts/components/#the-spectrum-of-pulumi-components-you-can-build

We will need to expand the table to both clarify some of the existing items and add additional ones. (Exact list TBD.)

The following pages should have links to the packaging guide:

• Components (concepts page)
• Build a Component (from where we removed the content on packaging a component)

Related: #15396

[jkodroff]

Hitting a snag b/c we don't have a concise name for New Components. Working this out with product so that we can have clear, concise, intuitive nomenclature for the 3 packaging options.