Add Paramaterize to provider interface

[Frassle]

Description

This is the bare bones changes required to update the provider interface for parametrization. Nothing in the engine, sdks, cli, or codegen makes use of these new methods yet.

But providers team can start building on top of this interface. Note that this is subject to change, while this is likely the right design for parametrised providers there is a chance that we need to edit this interface before GA release.

Checklist

• I have run make tidy to update any new dependencies
• I have run make lint to verify my code passes the lint check
  • I have formatted my code using gofumpt

• I have added tests that prove my fix is effective or that my feature works

• I have run make changelog and committed the changelog/pending/<file> documenting my change

• Yes, there are changes in this PR that warrants bumping the Pulumi Cloud API version

[pulumi-bot]

Changelog

[uncommitted] (2024-05-15)

[iwahbe]

Thanks for getting this in!

[iwahbe]

As part of merging, I would really like to see the contract semantics as comments in provider.proto. Understanding many of our previous gRPC calls is difficult because they require implicit knowledge as to what they do. Right now, the comment on Parameterize reads:

// Parameterize takes either a string array of command line inputs or a value embedded from sdk generation.
rpc Parameterize(ParameterizeRequest) returns (ParameterizeResponse) {}

This is an ok description for ParameterizeRequest but doesn't tell us how Parameterize is actually used. At the very least, the description of Parameterize should include that:

• If Parameterize is called, it will be called exactly once and will be the first gRPC method called. If it's legal to call GetSchema() to get an initial schema before calling parameterize, we need to say that (because right now I assume it's not).
• Parameterize can be called with either CLI args or a pre-computed value. It is assumed that if a provider p where p.Parameterize(ARGS) yields VALUE, that p given p.Parameterize(ARGS) will behave the same as p given p.Parameterize(VALUE). -- An alternative design could be p.Parameterize(ARGS) only permits p.GetSchema(), and p.Parameterize(VALUE) must be called to acccess runtime methods (Create, Read, etc).
• A parameterized provider should embed VALUE in the schema it returns at SOME field. I'm not sure where SOME is (or if it exists yet).

These descriptions can change over time, but they should reflect the current understanding of how these methods are used. We have historically struggled with documenting our gRPC methods clearly and this is a good opportunity to fix that.

[Frassle]

As part of merging, I would really like to see the contract semantics as comments in

Can do, I'm still trying to work out how we're going to handle multiple versions of the same sub-package at the moment. I think we need it for CRDs and I think it requires the CRUD methods to be updated as well.

[iwahbe]

How does the engine know if a provider is being parameterized by an extension package or a replacement provider? As I understand it, the engine will need to treat extended and replaced providers very differently.

[Frassle]

Yeh it will be part of the register resource call.