Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Components and Reuse

Pulumi Packages and Multi-Language Components: Sharing Across Teams

Share Pulumi components beyond one program: plain libraries, multi-language component packages, schemas, SDK generation, versioning and the Pulumi Registry.

A component in your own repository is easy to reuse: import the class. The real question is how to share it with other teams, some of whom write Python, Go or C# instead of TypeScript. Pulumi offers three levels of sharing, from a plain library to a published, versioned, multi-language component package.

None of the Pulumi tooling runs on this site, so the commands and files below are read-only. The runnable stand-ins model the parts that are pure logic: version constraints and the idea of one schema driving several language SDKs.

Level 1: a plain library in your language

If everyone uses the same language, publish the component like any library: an npm package, a PyPI package, a Go module, a NuGet package. Consumers install it and import the class.

JSON
{
  "name": "@acme/pulumi-static-site",
  "version": "1.4.0",
  "main": "bin/index.js",
  "peerDependencies": {
    "@pulumi/pulumi": "^3.0.0",
    "@pulumi/aws": "^6.0.0"
  }
}

Declare @pulumi/pulumi and provider packages as peer dependencies. If your library bundled its own copy, resources created by the library would belong to a different Pulumi SDK instance than the program's, causing confusing "resource monitor" errors.

Pros: simplest. Cons: one language only, and a breaking change in the library affects every consumer when they upgrade.

Level 2: multi-language component packages

A multi-language component (MLC) is a component written in one language but usable from all Pulumi languages. Pulumi infers a schema from your component class (its constructor args and outputs) and generates a local SDK for each consumer language. At runtime the Pulumi engine runs your component in its own language host, so a Python program can use a component written in TypeScript without having Node.js code of its own.

A component project has a PulumiPlugin.yaml marking the runtime:

YAML
runtime: nodejs

Consumers add the package with the CLI:

Terminal
pulumi package add github.com/acme/pulumi-static-site@v1.4.0

This generates a local SDK for the language of the consuming project and updates its project file. Then they use it as any provider:

Python
import pulumi_static_site as site

blog = site.StaticSite("blog", index_document="index.html")
pulumi.export("url", blog.website_url)

Because the SDK is generated from the schema, the schema has strict rules. In a TypeScript component, the args interface may only use types that can be serialized: strings, numbers, booleans, arrays, maps, Input/Output wrappers of those and nested interfaces. Functions, classes and unions that cannot be expressed in the schema are not allowed. The same goes for outputs.

You can inspect the generated schema with pulumi package get-schema and generate SDKs without publishing using pulumi package gen-sdk.

Level 3: publishing to a registry

For a larger organization, publish packages so everyone finds them in one place. The Pulumi Registry lists public providers and components, and an organization can run a private registry in Pulumi Cloud for internal components. Publishing records the package version and its schema and generates documentation and SDK instructions. Use semantic versioning:

  • Patch (1.4.1): bug fix, no input or output changes.
  • Minor (1.5.0): new optional inputs or new outputs.
  • Major (2.0.0): removed or renamed inputs, outputs, changed required inputs, or anything that replaces resources.
flowchart LR
  Src["Component source (TypeScript)"] --> Schema["Schema (inferred)"]
  Schema --> PySDK["Python SDK"]
  Schema --> GoSDK["Go SDK"]
  Schema --> CsSDK["C# SDK"]
  Schema --> JavaSDK["Java SDK"]
  PySDK --> Prog["Consumer programs"]
  GoSDK --> Prog
  CsSDK --> Prog
  JavaSDK --> Prog

One component, one schema, SDKs for every language.

What changes between versions

Changing a component is not like changing a function: the consumer's state contains URNs and resource properties created by the old version. A change that renames a child resource, changes its type or changes an immutable property will make the next pulumi up replace resources, possibly including databases. So:

  • Keep child logical names stable (or add aliases).
  • Treat adding a required input as a breaking change; make new inputs optional with a default that preserves behavior.
  • Document replacements in a changelog.
  • Run pulumi preview in a staging stack when you upgrade, and look for replace.

Stand-in: semantic version constraints

Consumers pin ranges such as ^1.4.0 (compatible with 1.x, at least 1.4.0) and ~1.4.0 (patch updates only). This stand-in implements the two operators and picks the highest satisfying version, as a package manager would.

Node.js Stand-in: caret and tilde ranges

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that ^1.4.0 accepts 1.5.0 but never 2.0.0. That is the contract that makes the "breaking change means major" rule important: consumers trust it.

Stand-in: one schema, many SDKs

An MLC schema is data. A generator turns it into per-language code. This toy generator emits a typed constructor signature for TypeScript and Python from the same description, to show why the schema must stay simple.

Node.js Stand-in: generating signatures from one schema

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing a sharing level

Situation Choice
One team, one language Plain library (npm, PyPI, Go module)
Several languages, internal Multi-language component, private registry
Public, community use Published package with schema and docs in the Pulumi Registry

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a shared component library list @pulumi/pulumi as a peer dependency?

    If the library bundles its own copy of the SDK, resources it creates belong to a different SDK instance than the program's, which leads to errors.
  2. 2. What makes a multi-language component usable from Python when it is written in TypeScript?

    The schema describes args and outputs; the CLI generates an SDK per language and the engine runs the component in its own language host.
  3. 3. A component adds a new required input. Which version bump is appropriate?

    A new required input breaks existing callers, so it is a breaking change and needs a major version.
  4. 4. Which type in a component's args interface is NOT allowed for multi-language components?

    Args must be expressible in the schema, so functions and other non-serializable types are not allowed.

Summary

  • Share components as plain libraries when one language is enough; use peer dependencies for the Pulumi SDK and providers.
  • Multi-language components generate per-language SDKs from an inferred schema, added with pulumi package add.
  • Keep args and outputs serializable and simple so the schema can express them.
  • Follow semantic versioning, because consumers pin ranges and state depends on stable URNs.
  • A private registry gives an organization one place to publish and find components.

Next: Pulumi State: What Is Inside a Checkpoint