Pulumi packages

Pulumi Packages are the core technology that enables Pulumi resources, components, and functions to be defined once and used in all Pulumi languages.

How packages work

Pulumi packages consist of two parts that allow them to be consumed in any Pulumi language:

1. The provider plugin which contains Pulumi code and can be written in any language Pulumi supports. The provider plugin contains custom resources, functions, and components. Custom resources define CRUD operations for infrastructure resources. Functions query cloud providers for resource data. Components encapsulate custom resources or other components into reusable abstractions.
2. An SDK in the language of the consuming program, which is generated from the provider’s schema file. SDKs may be published and hosted on package feeds (npm, PyPI, etc.) or they may be generated locally by the Pulumi CLI (in combination with the package schema) when the package is added to your Pulumi program.

Consuming packages

There are two ways to add Pulumi packages to your program:

• Packages with published SDKs: Use your language’s standard package manager. Most packages in the Pulumi Registry have published SDKs. Each package’s Installation & Configuration page shows the specific command for your language (example).
• Local packages: Use pulumi package add, which generates an SDK locally and adds a reference to Pulumi.yaml. This is used for components, Terraform providers, and other packages without published SDKs.

Installing packages

To install all dependencies, use pulumi install. This is the recommended approach because it handles both standard package manager dependencies (from package.json, requirements.txt, etc.) and any local packages defined in Pulumi.yaml in a single command.

Run pulumi install when:

• Setting up a project after cloning from source control
• Adding or updating packages
• Ensuring all team members have the same dependencies

Adding local packages

For packages without published SDKs, called local packages, use the pulumi package add command. This downloads the provider plugin, generates a local SDK in your language, and adds the package to your Pulumi.yaml:

# Example: Add a Terraform provider
pulumi package add terraform-provider hashicorp/random

# Example: Add a component from a git repository
pulumi package add example.com/org/repo.git/path@version

After adding a local package, run pulumi install to complete the installation.

Some common use cases for local packages include:

1. Using the Any Terraform provider to generate a local SDK for a Terraform provider. (This feature allows you to consume any Terraform provider in a Pulumi program.)
2. Using the Azure Native provider to generate a local SDK for a specific version of the Azure API.
3. Consuming a Pulumi component published in Pulumi IDP, or directly via a Git reference.

In order to consume a Pulumi package, there may be additional runtime requirements. Runtime requirements differ by the language in which the package is written:

• TypeScript packages require the NodeJS runtime.
• Python packages require a Python interpreter.
• Go packages do not require a runtime if they are compiled. If they are referenced via source (e.g. a Pulumi component published via Pulumi IDP), they require a compatible version of the Go language to be installed.
• .NET packages do not require a runtime if they are compiled as runtime-included binaries, which is Pulumi’s recommended approach. .NET packages compiled as runtime-dependent binaries require a runtime.
• Java packages require a JVM runtime.
• YAML packages do not have any specific runtime requirements.

The Pulumi Registry

The Pulumi Registry contains a listing of popular Pulumi packages, and each package’s Installation & Configuration page contains instructions on how to install the SDK for the provider (example). Most packages in the Pulumi Registry have published SDKs, including all of the packages for the major cloud providers. For packages that do not have published SDKs, the package’s main page will show how to generate an SDK (example).

Authoring packages

There are two common cases for authoring packages:

1. You are authoring a Pulumi component to be shared within your team, organization, or by anyone in the Pulumi community.
2. You are authoring a Pulumi provider that allows your package’s consumers to manage resources for a cloud or SaaS provider. (You might optionally publish this provider in the Pulumi Registry if you intend it for public consumption.)

Authoring a component for distribution

If you are authoring a Pulumi component to be shared within your team or organization, you will need to decide whether to use local packages or publish SDKs. Most component authors will want consumers to use local packages for the following reasons:

• Most component authors will want to use local packages because publishing SDKs requires significant overhead: your CI/CD process will need to generate SDKs for all Pulumi languages (or at least all the languages your package consumers will use) and you will need package feeds to host those published SDKs.
• If you are authoring components only (not custom resources), you can write them in any Pulumi language. However, if you want to publish SDKs for your components, you’ll need to use the Pulumi Provider SDK (written in Go) to generate the schema that enables multi-language SDK generation. For components, this added complexity is usually not worth the effort compared to using local packages.

For an example of building and publishing a component with local packages, see Build a Component.

However, using Pulumi Provider SDK and publishing SDKs might work better when:

• If the component is intended for internal use and your organization has security policies that restrict the ability of developers to install software on their devices (specifically, a required runtime for your package), writing your component in Go and publishing it as a binary with published SDKs hosted in an internal package feed will make it easier for consumers to use your package.
• If you are intending to publish your component(s) in the Pulumi Registry for general public consumption, you should write your component in Go, and publish it as a binary with published SDKs hosted in the standard public package feeds (i.e., npm, PyPI, etc.). Note that the Pulumi Registry requires package contributors to generate SDKs in all languages Pulumi supports.
• Your team is comfortable writing and maintaining code in Go.
• Your organization already has the package feeds necessary to host SDKs in all languages that might consume the component.

Authoring a Pulumi provider

If you are authoring a Pulumi provider that allows consumers to manage resources for a new cloud or SaaS provider, you should author your provider in Go using Pulumi Provider SDK.

For a guide to authoring your provider, see Build a Provider. For a guide to publishing your provider in the Pulumi Registry, see Publishing Pulumi Packages.