API

Pulumi exposes two distinct API surfaces:

• gRPC protocol — the wire format every plugin (language host, provider, analyzer, converter) implements. Defined in proto/pulumi/.
• Pulumi Cloud REST — the HTTP API that pkg/backend/httpstate/ talks to at app.pulumi.com. It is implemented and versioned by the Pulumi Cloud service (not in this repo); the client is in pkg/backend/httpstate/client/.

This section focuses on the gRPC protocol because that's where this repo defines API. The REST surface is documented from the cloud side.

Sub-pages

• gRPC and protobufs — the schema, generated code, and how to extend it.

Active contributors

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

Where the proto files live

proto/
├── generate.sh                # Code-gen driver
├── grpc_version.txt           # Pinned grpc-tools version
└── pulumi/
    ├── alias.proto
    ├── analyzer.proto         # Policy-pack interface
    ├── callback.proto
    ├── converter.proto        # `pulumi convert` plugins
    ├── engine.proto           # Engine RPCs (logging, root URN)
    ├── errors.proto
    ├── events.proto
    ├── language.proto         # Language host (≈30 KB)
    ├── plugin.proto           # Generic plugin metadata
    ├── provider.proto         # Resource providers (≈70 KB — the big one)
    ├── resource.proto         # ResourceMonitor — language → engine
    ├── resource_status.proto
    ├── source.proto
    ├── codegen/               # Codegen-specific protos
    └── testing/               # Test-only protos

Generated code lives in sdk/proto/go/, sdk/nodejs/proto/, and sdk/python/lib/pulumi/runtime/proto/. The Go package is named pulumirpc (not pulumi).

Versioning

The protocol is additive. Backwards-incompatible changes are vanishingly rare; the engine keeps fallback behavior for older clients. The mechanism for adding a feature without breaking older peers:

1. Add an optional field or new RPC to the .proto file.
2. The receiver checks for presence (Go: pointer fields; the others: has_* accessors).
3. Older clients/servers that don't know about the field are no-ops.

For larger features, SupportsFeature (in proto/pulumi/resource.proto) lets the language host probe the engine for support before committing to a code path. The newer GetDeploymentInfo RPC consolidates these probes.

See also

• Architecture overview
• Apps: language hosts
• Systems: deployment engine