Plugin and Package Commands

Relevant source files

The following files were used as context for generating this wiki page:

• pkg/cmd/pulumi/plugin/plugin.go
• pkg/cmd/pulumi/plugin/plugin_install.go
• pkg/cmd/pulumi/plugin/plugin_ls.go
• pkg/cmd/pulumi/packagecmd/package_info.go
• pkg/cmd/pulumi/packagecmd/package_publish_test.go
• sdk/go/common/workspace/plugins.go
• sdk/go/common/workspace/plugins_test.go
• sdk/go/common/workspace/project.json
• pkg/codegen/python/gen.go
• pkg/codegen/dotnet/gen.go

Pulumi uses a plugin-based architecture to support a wide variety of clouds, languages, and other tools. These plugins are dynamically loaded and distributed separately from the main Pulumi CLI. The pulumi plugin and pulumi package command families provide tools for developers to manage the lifecycle of these plugins and packages.

The plugin commands focus on the low-level management of plugin binaries, such as installing, listing, and removing them from the local cache. The package commands provide a higher-level interface for inspecting package contents and publishing them to the Pulumi Registry.

Sources: pkg/cmd/pulumi/plugin/plugin.go:18-31, README.md:16-22

Plugin Management (pulumi plugin)

The pulumi plugin command is the primary tool for managing language and resource provider plugins on a local machine.

Sources: pkg/cmd/pulumi/plugin/plugin.go:10-12

pulumi plugin install

This command installs plugins, either by specifying a particular plugin or by letting Pulumi compute the required plugins from the current project.

The command can install a specific plugin:
pulumi plugin install [KIND NAME [VERSION]]

Or it can install all plugins for the current project:
pulumi plugin install

Sources: pkg/cmd/pulumi/plugin/plugin_install.go:34-45

Arguments and Flags

Flag	Description
--server <url>	Specifies a custom URL to download plugins from.
--exact	Forces installation of an exact version match, disabling the default greater-than-or-equal-to (>=) check.
--file <path> / -f <path>	Installs a plugin from a local binary, folder, or tarball instead of downloading it.
--reinstall	Reinstalls a plugin even if a compatible version already exists.
--checksum <hash>	The expected SHA256 checksum for the plugin archive, used for validation.

Sources: pkg/cmd/pulumi/plugin/plugin_install.go:52-65

Installation Logic

The installation process follows a clear sequence to resolve, download, and install a plugin.

This diagram illustrates the flow for installing a Pulumi plugin using the plugin install command.

• If no arguments are provided, it first determines the required plugins from the current project using getProjectPlugins.
• For each plugin, it checks if a compatible version is already installed. If --exact is used, it looks for an exact version match; otherwise, it accepts any installed version that is greater than or equal to the required version.
• If a plugin needs to be installed (or --reinstall is forced), it either downloads the plugin from a remote server or uses a local file specified with --file.
• The downloaded or local file is then installed into the Pulumi plugin cache using pkgWorkspace.InstallPluginContent.

Sources: pkg/cmd/pulumi/plugin/plugin_install.go:121-182, pkg/cmd/pulumi/plugin/plugin.go:34-51

pulumi plugin ls

This command lists installed plugins. It provides information about the plugin's name, kind, version, size, and usage timestamps.

Flag	Description
--project / -p	Lists only the plugins used by the current project.
--json / -j	Emits the output in JSON format.

The output is sorted alphabetically by name and then by version in descending order, showing the newest versions first.

Sources: pkg/cmd/pulumi/plugin/plugin_ls.go:21-50

The JSON output for each plugin includes the following fields:

Field	Type	Description
name	string	The name of the plugin.
kind	string	The kind of plugin (e.g., resource, language).
version	string	The semantic version of the plugin.
size	uint64	The size of the plugin file in bytes.
installTime	string	The timestamp when the plugin was installed.
lastUsedTime	string	The timestamp when the plugin was last used.

Sources: pkg/cmd/pulumi/plugin/plugin_ls.go:60-70

Package Management (pulumi package)

The pulumi package commands offer a higher-level abstraction for interacting with Pulumi packages, including inspection and publication.

pulumi package info

This command displays information about a package, including its modules, resources, and functions. It can operate on a provider name, a local schema file, or a path.

Flag	Description
--module <name> / -m <name>	Specifies a module within the package to inspect.
--resource <name> / -r <name>	Specifies a resource within the module to get detailed information about.
--function <name> / -f <name>	Specifies a function within the module to get detailed information about.

• Without flags, it shows provider-level information like name, version, and a list of modules.
• With --module, it lists all resources and functions within that module.
• With --resource or --function, it displays detailed information about that specific item, including its inputs and outputs.

Sources: pkg/cmd/pulumi/packagecmd/package_info.go:30-61

pulumi package publish

This command is used to publish a package to the Pulumi Registry. The implementation details are primarily visible through its test file.

This diagram shows the sequence of actions for publishing a package.

The publishing process involves:

1. Extracting the package schema (schema.PackageSpec) from the specified source.
2. Determining the publisher. The publisher is resolved in the following order of precedence:
   1. The --publisher command-line flag.
   2. The publisher field within the package's schema.
   3. The user's default organization in the Pulumi Cloud.
3. Locating and reading the README.md file, either from a path specified with --readme or by searching the package source and then the installed plugin directory.
4. Constructing a PackagePublishOp and sending it to the Pulumi Cloud backend via the PublishPackage API call.

Sources: pkg/cmd/pulumi/packagecmd/package_publish_test.go:210-256

Plugin Discovery and Resolution

Pulumi has a well-defined process for discovering which plugins a project needs and resolving them from various sources.

Project Plugin Discovery

When a command like pulumi plugin install (with no arguments) is run, Pulumi discovers the necessary plugins by:

1. Reading the project's Pulumi.yaml file.
2. Creating a plugin context to analyze the project's program.
3. Calling engine.GetRequiredPlugins on the language host, which inspects the program's source code to determine its resource dependencies.

This process yields a list of workspace.PluginDescriptor objects, which specify the required plugins.

Sources: pkg/cmd/pulumi/plugin/plugin.go:34-51

Plugin Source Resolution

When a plugin needs to be downloaded, Pulumi resolves its source URL.

This diagram shows the logic for determining a plugin's download source.

The resolution logic is as follows:

1. If the PluginDescriptor has a PluginDownloadURL, it is used directly. This can be a standard http(s)://, github://, gitlab://, or git:// URL.
2. If not, it checks for an override in the PULUMI_PLUGIN_DOWNLOAD_URL_OVERRIDES environment variable.
3. If no override is found, it uses a fallback mechanism which first attempts to download from Pulumi's official GitHub releases.
4. If the GitHub release is not found, it falls back to https://get.pulumi.com.

Sources: sdk/go/common/workspace/plugins_test.go:411-662

Plugin and Package Metadata

Metadata files within a package and project provide crucial information for the CLI and code generation tools.

pulumi-plugin.json

This file is a standard part of a Pulumi package and provides essential metadata to the engine. It is typically generated by language-specific code generation tools.

Field	Description
resource	A boolean indicating if the plugin is a resource provider. Always true for provider plugins.
name	The name of the package (e.g., "aws").
version	The semantic version of the plugin.
server	The URL from which the plugin binary can be downloaded.
parameterization	Optional information for parameterized packages.

Sources: pkg/codegen/python/gen.go:1320-1346, pkg/codegen/dotnet/gen.go:1931-1953

Pulumi.yaml plugins Section

The Pulumi.yaml file can contain a plugins section to override the default plugin resolution behavior. This is primarily intended for local plugin development.

# Pulumi.yaml
name: my-project
runtime: nodejs
plugins:
  providers:
    - name: aws
      path: ../../pulumi-aws/bin
      version: 6.0.0

The plugins object can contain providers, languages, and analyzers arrays. Each entry has the following properties:

Field	Description
name	The name of the plugin to override.
path	The local filesystem path to the plugin folder.
version	An optional version to match. If not set, it will match any version requested by the engine.

Sources: sdk/go/common/workspace/project.json:173-207