Plugin system

Active contributors: Fraser Waters, Ian Wahbe, Justin Van Patten, Thomas Gummerer

Purpose

Almost every external behavior in Pulumi is delivered as a plugin: language hosts, providers, analyzers (policy packs), and converters are all plugins. The plugin system handles their discovery, download/install, version resolution, process lifecycle, and gRPC connection.

Plugin kinds

Kind	Binary name	Implements	Repo
Language	pulumi-language-<lang>	proto/pulumi/language.proto	This repo (Go/Node/Python/PCL) + external (.NET/Java/YAML)
Resource	pulumi-resource-<name>	proto/pulumi/provider.proto	One repo per provider
Analyzer	pulumi-analyzer-<name>	proto/pulumi/analyzer.proto	Policy pack repos
Converter	pulumi-converter-<name>	proto/pulumi/converter.proto	One repo per source format
Tool	pulumi-tool-<name>	varies	pulumi package plugins

Where the plugin code lives

Concern	Path
Discovery + install	pkg/engine/plugins.go (≈30 KB), pkg/engine/install_manager.go
Plugin host (gRPC client wrapper)	pkg/engine/plugin_host.go
Workspace plugin metadata	sdk/go/common/workspace/plugins.go
CLI commands	pkg/cmd/pulumi/plugin/
Package install (modern entry)	pkg/cmd/pulumi/packageinstallation/
Package resolution	pkg/cmd/pulumi/packageresolution/
Per-package workspace	pkg/cmd/pulumi/packageworkspace/
Storage abstraction	pkg/pluginstorage/
On-disk cache layout	~/.pulumi/plugins/<kind>-<name>-<version>/

Resolution

When the engine needs pulumi-resource-aws@6.10.0:

graph TD
    Need[Need: aws@6.10.0] --> Lock{In project lockfile?}
    Lock -->|yes| Cache{In ~/.pulumi/plugins?}
    Lock -->|no| Schema{Schema constraint in code?}
    Schema --> Cache
    Cache -->|hit| Spawn[Spawn process]
    Cache -->|miss| Download[Download from GitHub Releases<br/>or registry]
    Download --> Cache

The on-disk layout is ~/.pulumi/plugins/resource-aws-v6.10.0/pulumi-resource-aws (binary inside a versioned dir). pkg/cmd/pulumi/plugin/ shows it via pulumi plugin ls.

Install

pulumi plugin install resource aws v6.10.0 is the explicit form. Implicit installs happen during pulumi up if the lockfile mentions a plugin not present locally. The downloader supports:

• GitHub Releases (the common case).
• Pulumi-hosted plugin registry (introduced with Pulumi Cloud, controlled by pkg/backend/httpstate/cloud_registry.go).
• Custom URLs (advanced — --server flag).

pulumi-renovate[bot] keeps plugins fresh in CI.

Spawn lifecycle

The plugin host process model:

sequenceDiagram
    participant E as Engine (pkg/engine/plugins.go)
    participant P as Plugin process
    E->>P: exec binary
    P->>P: bind to local TCP port, print "12345" on stdout
    E->>P: read port from stdout
    E->>P: gRPC dial 127.0.0.1:12345
    E->>P: GetPluginInfo / Configure / etc.
    Note over E,P: Many RPCs follow
    E->>P: Cancel (best effort)
    E->>P: SIGTERM
    P-->>E: exit

Plugins:

1. Bind to a free local TCP port.
2. Print the port number on stdout.
3. Wait for gRPC requests.

The engine reads the port, dials, and uses the plugin until Cancel or until the operation ends. Plugins crashed mid-op are detected and surfaced as engine errors.

Process tracing

When run with --tracing, the engine propagates the trace endpoint to every plugin. Plugins write spans to the same destination, producing a unified per-operation trace.

Plugin storage

pkg/pluginstorage/ abstracts where downloaded plugins are stored. Default is the local cache; in some sandboxed environments (Pulumi Deployments) plugins are pre-staged elsewhere.

Entry points for modification

• Adding a plugin kind — extend apitype.PluginKind, teach plugins.go discovery, and define the .proto contract.
• Custom download source — implement an alternate PluginSource and wire it through pkg/cmd/pulumi/packageinstallation/.
• Plugin lockfile — sdk/go/common/workspace/plugins.go plus the project-level Pulumi.yaml schema.

See also

• Architecture overview
• Apps: language hosts — language plugins specifically.
• Apps: CLI — pulumi plugin and pulumi package commands.