15184d702e
Fixes https://github.com/pulumi/pulumi/issues/16876 The pulumi provider protocol gRPC always starts by calling CheckConfig and then Configure. The problem is that CheckConfig accepts a property bag, which could contain secrets or outputs or resource references, etc. However, the engine doesn't know if the provider supports these items (and vice versa) until Configure is called, since Configure is the call where the engine and the provider agree on which parts of the protocol they support. This introduces a Handshake component to the provider protocol that establishes which version of the protocol the provider and engine support. This also adds the plugins root and program directories to that handshake request allowing a provider to know where it was started up from. This _also_ replaces `Provider.Attach` as the handshake request includes the engine address to connect to. Tasting notes: * Add `Handshake` with request/response to the protocol. `Handshake` starts as a high watermark for accepts secrets, accepts resources, etc but includes the plugins root and program directories (if possible), as well as the engine address. This pretty much replaces the need for `Attach`. * Modify `dialPlugin` (where the engine establishes gRPC connections to plugins) to take a callback that is used to initialise the connection * For non-provider plugins, pass `testConnection`, which captures the logic we have today -- call a dummy gRPC method and observed not implemented error to confirm connection is live * For provider plugins, pass `handshake`, which sends a `Handshake` and captures the response * All providers thus handshake at boot, as opposed to `Configure`, which a. happens later and b. is asynchronous * Modify provider implementation to track a `protocol`; move `acceptSecrets` and company from `configSource` to there * If `Handshake` is implemented, populate `protocol` on `dialPlugin`. If not, fallback to populating in `Configure` * Invariant: `Configure` implies `protocol` * The rest is largely plumbing * We can add similar Handshake methods for the other plugin types as well --------- Co-authored-by: Fraser Waters <fraser@pulumi.com> |
||
|---|---|---|
| .. | ||
| build-container | ||
| google/protobuf | ||
| pulumi | ||
| .checksum.txt | ||
| README.md | ||
| generate.sh | ||
| grpc_version.txt | ||
README.md
Protobuf and gRPC interfaces
This package contains Protobuf definitions for the various types, messages and interfaces that Pulumi components use to communicate. These definitions serve as the source of truth for several parts of the wider codebase.
Code generation
:::{note}
Code generated from Protobuf files is committed to the repository. If you change
one or more .proto files, you should run make build_proto to regenerate the
necessary stubs and commit the changes as part of the same piece of work.
:::
The gh-file:pulumi#proto/generate.sh script in this directory (called by the
build_proto target in the top-level gh-file:pulumi#Makefile) generates types
and gRPC clients for the languages supported in this repository (Go,
NodeJS/TypeScript and Python). Generated code is committed to the repository,
typically in proto directories at the relevant use sites (e.g.
gh-file:pulumi#sdk/nodejs/proto).
Documentation
We use the protoc-gen-doc
plugin to protoc to generate
Markdown documentation from the Protobuf files. This process is handled by the
gh-file:pulumi#docs/Makefile in the docs directory and uses the
gh-file:pulumi#docs/references/proto.md.tmpl template. Generated documentation ends
up in the docs/_generated directory (which is .gitignored), so e.g. this
index links to files in this folder.
Index
:::{toctree} :maxdepth: 1 :titlesonly:
/docs/_generated/proto/resource /docs/_generated/proto/provider /docs/_generated/proto/plugin /docs/_generated/proto/language /docs/_generated/proto/callback /docs/_generated/proto/loader /docs/_generated/proto/converter /docs/_generated/proto/analyzer /docs/_generated/proto/alias /docs/_generated/proto/engine /docs/_generated/proto/errors /docs/_generated/proto/source :::