@pulumi/pulumi 3.137.1-alpha.xf146c2e → 3.138.0-alpha.x077d8e3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pulumi/pulumi",
-    "version": "3.137.1-alpha.xf146c2e",
+    "version": "3.138.0-alpha.x077d8e3",
     "description": "Pulumi's Node.js SDK",
     "license": "Apache-2.0",
     "repository": {

package/proto/provider_grpc_pb.js

@@ -353,22 +353,38 @@ function deserialize_pulumirpc_UpdateResponse(buffer_arg) {
 }
 
 
-// ResourceProvider is a service that understands how to create, read, update, or delete resources for types defined
-// within a single package.  It is driven by the overall planning engine in response to resource diffs.
+// The ResourceProvider service defines a standard interface for [resource providers](providers). A resource provider
+// manages a set of configuration, resources, functions and so on in a single package, and offers methods such as CRUD
+// operations on resources and invocations of functions. Resource providers are primarily managed by the Pulumi engine
+// as part of a deployment in order to interact with the cloud providers underpinning a Pulumi application.
 var ResourceProviderService = exports.ResourceProviderService = {
-  // Parameterize takes either a string array of command line inputs or a value embedded from sdk generation.
+  // `Parameterize` is the primary means of supporting [parameterized providers](parameterized-providers), which allow
+// a caller to change a provider's behavior ahead of its [configuration](pulumirpc.ResourceProvider.Configure) and
+// subsequent use. Where a [](pulumirpc.ResourceProvider.Configure) call allows a caller to influence provider
+// behaviour at a high level (e.g. by specifying the region in which an AWS provider should operate), a
+// `Parameterize` call may change the set of resources and functions that a provider offers (that is, its schema).
+// This is useful in any case where some "set" of providers can be captured by a single implementation that may
+// power fundamentally different schemata -- dynamically bridging Terraform providers, or managing Kubernetes
+// clusters with custom resource definitions, for instance, are good examples. The parameterized package that
+// `Parameterize` yields is known as a *sub-package* of the original (unparameterized) package.
 //
-// Providers can be parameterized with either multiple extension packages (which don't define their own provider
-// resources), or with a replacement package (which does define its own provider resource).
+// `Parameterize` supports two types of parameterization:
 //
-// Parameterize may be called multiple times for extension packages, but for a replacement package it will only be
-// called once. Extension packages may even be called multiple times for the same package name, but with different
-// versions.
+// * *Replacement parameterization*, whereby a `Parameterize` call results in a schema that completely replaces the
+//   original provider schema. Bridging a Terraform provider dynamically might be an example of this -- following
+//   the call to `Parameterize`, the provider's schema will become that of the Terraform provider that was bridged.
+//   Providers that implement replacement parameterization expect a *single* call to `Parameterize`.
 //
-// Parameterize should work the same for both the `ParametersArgs` input and the `ParametersValue` input. Either way
-// should return the sub-package name and version (which for `ParametersValue` should match the given input).
+// * *Extension parameterization*, in which a `Parameterize` call results in a schema that is a superset of the
+//   original. This is useful in cases where a provider can be extended with additional resources or functions, such
+//   as a Kubernetes provider that can be extended with resources representing custom resource definitions.
+//   Providers that implement extension parameterization should accept multiple calls to `Parameterize`. Extension
+//   packages may even be called multiple times with the same package name, but with different versions. The CRUD
+//   operations of extension resources must include the version of which sub-package they correspond to.
 //
-// For extension resources their CRUD operations will include the version of which sub-package they correspond to.
+// `Parameterize` should work the same whether it is provided with `ParametersArgs` or `ParametersValue` input. In
+// each case it should return the sub-package name and version (which when a `ParametersValue` is supplied should
+// match the given input).
 parameterize: {
     path: '/pulumirpc.ResourceProvider/Parameterize',
     requestStream: false,
@@ -392,7 +408,24 @@ getSchema: {
     responseSerialize: serialize_pulumirpc_GetSchemaResponse,
     responseDeserialize: deserialize_pulumirpc_GetSchemaResponse,
   },
-  // CheckConfig validates the configuration for this resource provider.
+  // `CheckConfig` validates a set of configuration inputs that will be passed to this provider instance.
+// `CheckConfig` is to provider resources what [](pulumirpc.ResourceProvider.Check) is to individual resources, and
+// is the first stage in configuring (that is, eventually executing a [](pulumirpc.ResourceProvider.Configure) call)
+// a provider using user-supplied values. In the case that provider inputs are coming from some source that has been
+// checked previously (e.g. a Pulumi state), it is not necessary to call `CheckConfig`.
+//
+// A `CheckConfig` call returns either a set of checked, known-valid inputs that may subsequently be passed to
+// [](pulumirpc.ResourceProvider.DiffConfig) and/or [](pulumirpc.ResourceProvider.Configure), or a set of errors
+// explaining why the inputs are invalid. In the case that a set of inputs are successfully validated and returned,
+// `CheckConfig` *may also populate default values* for provider configuration, returning them so that they may be
+// passed to a subsequent [](pulumirpc.ResourceProvider.Configure) call and persisted in the Pulumi state. In the
+// case that `CheckConfig` fails and returns a set of errors, it is expected that the caller (typically the Pulumi
+// engine) will fail provider registration.
+//
+// As a rule, the provider inputs returned by a call to `CheckConfig` should preserve the original representation of
+// the properties as present in the program inputs. Though this rule is not required for correctness, violations
+// thereof can negatively impact the end-user experience, as the provider inputs are using for detecting and
+// rendering diffs.
 checkConfig: {
     path: '/pulumirpc.ResourceProvider/CheckConfig',
     requestStream: false,

package/version.d.ts

@@ -1 +1 @@
-export declare const version = "3.137.1";
+export declare const version = "3.138.0";

package/version.js

@@ -13,5 +13,5 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.version = "3.137.1-alpha.xf146c2e";
+exports.version = "3.138.0-alpha.x077d8e3";
 //# sourceMappingURL=version.js.map