pulumi/proto/pulumi/provider.proto

// Copyright 2016-2018, Pulumi Corporation.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

import "pulumi/plugin.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";

package pulumirpc;

option go_package = "github.com/pulumi/pulumi/sdk/v3/proto/go;pulumirpc";

// 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.
service ResourceProvider {
    // `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.
    //
    // `Parameterize` supports two types of parameterization:
    //
    // * *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`.
    //
    // * *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.
    //
    // `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).
    rpc Parameterize(ParameterizeRequest) returns (ParameterizeResponse) {}

    // GetSchema fetches the schema for this resource provider.
    rpc GetSchema(GetSchemaRequest) returns (GetSchemaResponse) {}

    // `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 used for detecting and
    // rendering diffs.
    rpc CheckConfig(CheckRequest) returns (CheckResponse) {}

    // `DiffConfig` compares an existing ("old") provider configuration with a new configuration and computes the
    // difference (if any) between them. `DiffConfig` is to provider resources what [](pulumirpc.ResourceProvider.Diff)
    // is to individual resources. `DiffConfig` should only be called with values that have at some point been validated
    // by a [](pulumirpc.ResourceProvider.CheckConfig) call. The [](pulumirpc.DiffResponse) returned by a `DiffConfig`
    // call is used primarily to determine whether or not the newly configured provider is capable of managing resources
    // owned by the old provider. If `DiffConfig` indicates that the provider resource needs to be replaced, for
    // instance, then all resources owned by that provider will *also* need to be replaced. Replacement semantics should
    // thus be reserved for changes to configuration properties that are guaranteed to make old resources unmanageable.
    // Changes to an AWS region, for example, will almost certainly require a provider replacement, but changes to an
    // AWS access key, should almost certainly not.
    rpc DiffConfig(DiffRequest) returns (DiffResponse) {}

    // `Configure` is the final stage in configuring a provider instance. Callers supply two sets of data:
    //
    // * Provider-specific configuration, which is the set of inputs that have been validated by a previous
    //   [](pulumirpc.ResourceProvider.CheckConfig) call.
    // * Provider-agnostic ("protocol") configuration, such as whether or not the caller supports secrets.
    //
    // The provider is expected to return its own set of protocol configuration, indicating which features it supports
    // in turn so that the caller and the provider can interact appropriately.
    //
    // Providers may expect a *single* call to `Configure`. If a call to `Configure` is missing required configuration,
    // the provider may return a set of error details containing [](pulumirpc.ConfigureErrorMissingKeys) values to
    // indicate which keys are missing.
    rpc Configure(ConfigureRequest) returns (ConfigureResponse) {}

    // Invoke dynamically executes a built-in function in the provider.
    rpc Invoke(InvokeRequest) returns (InvokeResponse) {}

    // StreamInvoke dynamically executes a built-in function in the provider, which returns a stream
    // of responses.
    rpc StreamInvoke(InvokeRequest) returns (stream InvokeResponse) {}

    // Call dynamically executes a method in the provider associated with a component resource.
    rpc Call(CallRequest) returns (CallResponse) {}

    // `Check` validates a set of input properties against a given resource type. A `Check` call returns either a set of
    // checked, known-valid inputs that may subsequently be passed to [](pulumirpc.ResourceProvider.Diff),
    // [](pulumirpc.ResourceProvider.Create), or [](pulumirpc.ResourceProvider.Update); or a set of errors explaining
    // why the inputs are invalid. In the case that a set of inputs are successfully validated and returned, `Check`
    // *may also populate default values* for resource inputs, returning them so that they may be passed to a subsequent
    // call and persisted in the Pulumi state. In the case that `Check` fails and returns a set of errors, it is
    // expected that the caller (typically the Pulumi engine) will fail resource registration.
    //
    // As a rule, the provider inputs returned by a call to `Check` 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 used for detecting and rendering
    // diffs.
    rpc Check(CheckRequest) returns (CheckResponse) {}

    // `Diff` compares an existing ("old") set of resource properties with a new set of properties and computes the
    // difference (if any) between them. `Diff` should only be called with values that have at some point been validated
    // by a [](pulumirpc.ResourceProvider.Check) call.
    rpc Diff(DiffRequest) returns (DiffResponse) {}

    // `Create` provisions a new instance of the specified [(custom) resource](custom-resources). It returns a
    // provider-assigned ID for the resource as well as the output properties that arose from the creation properties.
    // Output properties are typically the union of the resource's input properties and any additional values that were
    // computed or made available during creation.
    //
    // If creation fails, `Create` may return an [](pulumirpc.ErrorResourceInitFailed) error detail explaining why.
    // Moreover, if `Create` does return an error, it must be the case that the resource was *not* created (that is,
    // `Create` can be thought of as transactional or atomic).
    rpc Create(CreateRequest) returns (CreateResponse) {}

    // `Read` reads the current live state associated with a resource identified by the supplied state. The given state
    // must be sufficient to uniquely identify the resource. This is typically just the resource ID, but may also
    // include other properties.
    rpc Read(ReadRequest) returns (ReadResponse) {}

    // `Update` updates an existing resource according to a new set of inputs, returning a new set of output properties.
    rpc Update(UpdateRequest) returns (UpdateResponse) {}

    // `Delete` deprovisions an existing resource as specified by its ID. `Delete` should be transactional/atomic -- if
    // a call to `Delete` fails, it must be the case that the resource was *not* deleted and can be assumed to still
    // exist.
    rpc Delete(DeleteRequest) returns (google.protobuf.Empty) {}

    // `Construct` provisions a new [component resource](component-resources). Providers that implement `Construct` are
    // referred to as [component providers](component-providers). `Construct` is to component resources what
    // [](pulumirpc.ResourceProvider.Create) is to [custom resources](custom-resources). Components do not have any
    // lifecycle of their own, and instead embody the lifecycles of the resources that they are composed of. As such,
    // `Construct` is effectively a subprogram whose resources will be persisted in the caller's state. It is
    // consequently passed enough information to manage fully these resources. At a high level, this comprises:
    //
    // * A [](pulumirpc.ResourceMonitor) endpoint which the provider can use to [register](resource-registration) nested
    //   custom or component resources that belong to the component.
    //
    // * A set of input properties.
    //
    // * A full set of [resource options](https://www.pulumi.com/docs/iac/concepts/options/) that the component should
    //   propagate to resources it registers against the supplied resource monitor.
    rpc Construct(ConstructRequest) returns (ConstructResponse) {}

    // Cancel signals the provider to gracefully shut down and abort any ongoing resource operations.
    // Operations aborted in this way will return an error (e.g., `Update` and `Create` will either return a
    // creation error or an initialization error). Since Cancel is advisory and non-blocking, it is up
    // to the host to decide how long to wait after Cancel is called before (e.g.)
    // hard-closing any gRPC connection.
    rpc Cancel(google.protobuf.Empty) returns (google.protobuf.Empty) {}
    // GetPluginInfo returns generic information about this plugin, like its version.
    rpc GetPluginInfo(google.protobuf.Empty) returns (PluginInfo) {}

    // Attach sends the engine address to an already running plugin.
    rpc Attach(PluginAttach) returns (google.protobuf.Empty)  {}

    // GetMapping fetches the mapping for this resource provider, if any. A provider should return an empty
    // response (not an error) if it doesn't have a mapping for the given key.
    rpc GetMapping(GetMappingRequest) returns (GetMappingResponse) {}

    // GetMappings is an optional method that returns what mappings (if any) a provider supports. If a provider does not
    // implement this method the engine falls back to the old behaviour of just calling GetMapping without a name.
    // If this method is implemented than the engine will then call GetMapping only with the names returned from this method.
    rpc GetMappings(GetMappingsRequest) returns (GetMappingsResponse) {}
}

// `ParameterizeRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Parameterize) call. A
// `ParameterizeRequest` may contain either:
//
// * a string array (`ParametersArgs`), intended to represent a set of command-line arguments so as to support
//   instantiating a parameterized provider from a command-line invocation (e.g. to generate an SDK).
// * a byte array accompanied by a name and version (`ParametersValue`), intended to represent a parameter embedded in a
//   previously generated SDK.
//
// Embedding parameter values in SDKs allows programs to consume parameterized providers without needing to know the
// details of the parameterization. Allowing the representation embedded into an SDK to differ from that supplied on the
// command-line permits providers to implement optimizations for the common, fast-path case (program execution), such as
// embedding a generated schema as opposed to generating it on-demand for each resource registration.
message ParameterizeRequest {
    // A parameter value, represented as an array of strings, as might be provided by a command-line invocation, such as
    // that used to generate an SDK.
    message ParametersArgs {
        repeated string args = 1;
    }

    // A parameter value, represented by an arbitrary array of bytes accompanied by a name and version. This is expected
    // to be the format used by parameterized provider SDKs.
    message ParametersValue {
        // The sub-package name for this sub-schema parameterization.
        string name = 1;
        // The sub-package version for this sub-schema parameterization.
        string version = 2;
        // The embedded value from the sub-package.
        bytes value = 3;
    }

    oneof parameters {
        // Arguments from the command line.
        ParametersArgs args = 1;
        // Values from a generated SDK.
        ParametersValue value = 2;
    }
}

// `ParameterizeResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Parameterize) call. It
// contains a name and version that can be used to identify the sub-package that now exists as a result of
// parameterization.
message ParameterizeResponse {
    // The name of the sub-package parameterized.
    string name = 1;
    // The version of the sub-package parameterized.
    string version = 2;
}

message GetSchemaRequest {
    // the schema version.
    int32 version = 1;
    // the name of the sub-package to lookup
    string subpackage_name = 2;
    // the version of the sub-package to lookup
    string subpackage_version = 3;
}

message GetSchemaResponse {
    string schema = 1; // the JSON-encoded schema.
}

// `ConfigureRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Configure) call. Requests
// include both provider-specific inputs (`variables` or `args`) and provider-agnostic ("protocol") configuration
// (`acceptSecrets`, `acceptResources`, and so on).
message ConfigureRequest {
    // :::{warning}
    // `variables` is deprecated; `args` should be used instead wherever possible.
    // :::
    //
    // A map of input properties for the provider. Compound values, such as nested objects, should be JSON encoded so
    // that they too can be passed as strings. For instance, the following configuration:
    //
    // ```
    // {
    //   "a": 42,
    //   "b": {
    //     "c": "hello",
    //     "d": true
    //   }
    // }
    // ```
    //
    // should be encoded as:
    //
    // ```
    // {
    //   "a": "42",
    //   "b": "{\"c\":\"hello\",\"d\":true}"
    // }
    // ```
    map<string, string> variables = 1;

    // A map of input properties for the provider.
    //
    // :::{warning}
    // `args` may include secrets. Because `ConfigureRequest` is sent before [](pulumirpc.ConfigureResponse) can specify
    // whether or not the provider accepts secrets in general, providers *must* handle secrets if they appear in `args`.
    // :::
    google.protobuf.Struct args = 2;

    // True if and only if the caller supports secrets. If true, operations should return strongly typed secrets if the
    // provider supports them also.
    bool acceptSecrets  = 3;

    // True if and only if the caller supports strongly typed resources. If true, operations should return resources as
    // strongly typed values if the provider supports them also.
    bool acceptResources = 4;

    // True if and only if the caller supports sending old inputs as part of [](pulumirpc.ResourceProvider.Diff) and
    // [](pulumirpc.ResourceProvider.Update) calls. If true, the provider should expect these fields to be populated in
    // these calls.
    bool sends_old_inputs = 5;

    // True if and only if the caller supports sending old inputs and outputs as part of
    // [](pulumirpc.ResourceProvider.Delete) calls. If true, the provider should expect these fields to be populated in
    // these calls.
    bool sends_old_inputs_to_delete = 6;
}

// `ConfigureResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Configure) call. Its primary
// purpose is to communicate features that the provider supports back to the caller.
message ConfigureResponse {
    // True if and only if the provider supports secrets. If true, the caller should pass secrets as strongly typed
    // values to the provider.
    bool acceptSecrets = 1;

    // True if and only if the provider supports the `preview` field on [](pulumirpc.ResourceProvider.Create) and
    // [](pulumirpc.ResourceProvider.Update) calls. If true, the engine should invoke these calls with `preview` set to
    // `true` during previews.
    bool supportsPreview = 2;

    // True if and only if the provider supports strongly typed resources. If true, the caller should pass resources as
    // strongly typed values to the provider.
    bool acceptResources = 3;

    // True if and only if the provider supports output values as inputs. If true, the engine should pass output values
    // to the provider where possible.
    bool acceptOutputs = 4;
}

// `ConfigureErrorMissingKeys` is the type of error details that may be sent in response to a
// [](pulumirpc.ResourceProvider.Configure) call when required configuration keys are missing.
message ConfigureErrorMissingKeys {
    // The type of key-value pairs representing keys that are missing from a [](pulumirpc.ResourceProvider.Configure)
    // call.
    message MissingKey {
        // The name of the missing configuration key.
        //
        // :::{note}
        // This should be the *Pulumi name* of the missing key, and not any provider-internal or upstream name. Names
        // that differ between Pulumi and an upstream provider should be translated prior to being returned.
        // :::
        string name = 1;

        // A description of the missing config key, as reported by the provider.
        string description = 2;
    }

    // A list of required configuration keys that were not supplied.
    repeated MissingKey missingKeys = 1;
}

message InvokeRequest {
    string tok = 1;                  // the function token to invoke.
    google.protobuf.Struct args = 2; // the arguments for the function invocation.

    // We used to send ResourceInvokeRequest for both provider invokes and monitor invokes, despite them being
    // different. We've now split them but need to make sure we don't confuse any old plugins/monitors making
    // sure those fields don't get reused.
    reserved 3 to 6;
    reserved "provider", "version", "acceptResources", "pluginDownloadURL";
}

message InvokeResponse {
    google.protobuf.Struct return = 1;  // the returned values, if invoke was successful.
    repeated CheckFailure failures = 2; // the failures if any arguments didn't pass verification.
}

message CallRequest {
    // ArgumentDependencies describes the resources that a particular argument depends on.
    message ArgumentDependencies {
        repeated string urns = 1; // A list of URNs this argument depends on.
    }

    // We used to send CallRequest for both provider calls and monitor calls, despite them being different.
    // We've now split them but need to make sure we don't confuse any old plugins/monitors making sure those
    // fields don't get reused.
    reserved 4, 5, 13, 16, 15;
    reserved "provider", "version", "pluginDownloadURL", "pluginChecksums", "sourcePosition";

    string tok = 1;                                        // the function token to invoke.
    google.protobuf.Struct args = 2;                       // the arguments for the function invocation.
    map<string, ArgumentDependencies> argDependencies = 3; // a map from argument keys to the dependencies of the argument.

    string project = 6;             // the project name.
    string stack = 7;               // the name of the stack being deployed into.
    map<string, string> config = 8; // the configuration variables to apply before running.
    repeated string configSecretKeys = 9; // the configuration keys that have secret values.
    bool dryRun = 10;                // true if we're only doing a dryrun (preview).
    int32 parallel = 11;            // the degree of parallelism for resource operations (<=1 for serial).
    string monitorEndpoint = 12;    // the address for communicating back to the resource monitor.
    string organization = 14;       // the organization of the stack being deployed into.

    bool accepts_output_values = 17; // the engine can be passed output values back, returnDependencies can be left blank if returning output values.
}

message CallResponse {
    // ReturnDependencies describes the resources that a particular return value depends on.
    message ReturnDependencies {
        repeated string urns = 1; // A list of URNs this return value depends on.
    }

    google.protobuf.Struct return = 1;  // the returned values, if call was successful.
    repeated CheckFailure failures = 3; // the failures if any arguments didn't pass verification.

    // a map from return value keys to the dependencies of the return value.
    //
    // returnDependencies will be augmented by the set of dependencies specified in return
    // via output property values.
    map<string, ReturnDependencies> returnDependencies = 2;
}

// `CheckRequest` is the type of requests sent as part of [](pulumirpc.ResourceProvider.CheckConfig) and
// [](pulumirpc.ResourceProvider.Check) calls. A `CheckRequest` primarily captures the URN and inputs of the resource
// being checked. In the case of [](pulumirpc.ResourceProvider.CheckConfig), the URN will be the URN of the provider
// resource being constructed, which may or may not be a [default provider](default-providers), and the inputs will be
// the provider configuration.
message CheckRequest {
    // The URN of the resource whose inputs are being checked. In the case of
    // [](pulumirpc.ResourceProvider.CheckConfig), this will be the URN of the provider resource being constructed,
    // which may or may not be a [default provider](default-providers).
    string urn = 1;

    // The old input properties or configuration for the resource, if any.
    google.protobuf.Struct olds = 2;

    // The new input properties or configuration for the resource, if any.
    //
    // :::{note}
    // If this resource has been specified with the
    // [`ignoreChanges`](https://www.pulumi.com/docs/concepts/options/ignorechanges/), then the values in `news` may
    // differ from those written in the Pulumi program registering this resource. In such cases, the caller (e.g. the
    // Pulumi engine) is expected to preprocess the `news` value by replacing every property matched by `ignoreChanges`
    // with its corresponding `olds` value (effectively ignoring the change).
    // :::
    google.protobuf.Struct news = 3;

    // `CheckRequest`s originally contained sequence numbers, but they have since been replaced by random seeds.
    reserved 4;
    reserved "sequenceNumber";

    // A random but deterministically computed hash, intended to be used for generating globally unique names.
    bytes randomSeed = 5;

    // The name of the resource being checked. This must match the name specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 6;

    // The type of the resource being checked. This must match the type specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 7;
}

// `CheckResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.CheckConfig) or
// [](pulumirpc.ResourceProvider.Check) call. A `CheckResponse` may contain either:
//
// * a set of checked, known-valid `inputs`. In the case of [](pulumirpc.ResourceProvider.CheckConfig), these may
//   subsequently be passed to [](pulumirpc.ResourceProvider.DiffConfig) and/or
//   [](pulumirpc.ResourceProvider.Configure). In the case of [](pulumirpc.ResourceProvider.Check), these may be passed
//   to any of the supported lifecycle methods that accept provider inputs.
// * a set of `failures` detailing invalid inputs.
//
// In cases where the supplied set of inputs is valid, a `CheckResponse` may contain default values that should
// persisted to Pulumi state and passed to subsequent calls.
message CheckResponse {
    // A valid, checked set of inputs. May contain defaults.
    google.protobuf.Struct inputs = 1;

    // Any validation failures that occurred.
    repeated CheckFailure failures = 2;
}

// A `CheckFailure` describes a single validation error that arose as part of a
// [](pulumirpc.ResourceProvider.CheckConfig) or [](pulumirpc.ResourceProvider.Check) call.
message CheckFailure {
    // The input property that failed validation.
    string property = 1;

    // The reason that the named property failed validation.
    string reason = 2;
}

// `DiffRequest` is the type of requests sent as part of [](pulumirpc.ResourceProvider.DiffConfig) and
// [](pulumirpc.ResourceProvider.Diff) calls. A `DiffRequest` primarily captures:
//
// * the URN of the resource whose properties are being compared;
// * the old and new input properties of the resource; and
// * the old output properties of the resource.
//
// In the case of [](pulumirpc.ResourceProvider.DiffConfig), the URN will be the URN of the provider resource being
// examined, which may or may not be a [default provider](default-providers), and the inputs and outputs will be the
// provider configuration and state. Inputs supplied to a [](pulumirpc.ResourceProvider.DiffConfig) call should have
// been previously checked by a call to [](pulumirpc.ResourceProvider.CheckConfig); inputs supplied to a
// [](pulumirpc.ResourceProvider.Diff) call should have been previously checked by a call to
// [](pulumirpc.ResourceProvider.Check).
message DiffRequest {
    // The ID of the resource being diffed.
    string id = 1;

    // The URN of the resource being diffed.
    string urn = 2;

    // The old *output* properties of the resource being diffed.
    google.protobuf.Struct olds = 3;

    // The new *input* properties of the resource being diffed. These should have been validated by an appropriate call
    // to [](pulumirpc.ResourceProvider.CheckConfig) or [](pulumirpc.ResourceProvider.Check).
    google.protobuf.Struct news = 4;

    // A set of [property paths](property-paths) that should be treated as unchanged.
    repeated string ignoreChanges = 5;

    // The old *input* properties of the resource being diffed.
    google.protobuf.Struct old_inputs = 6;

    // The name of the resource being diffed. This must match the name specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 7;

    // The type of the resource being diffed. This must match the type specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 8;
}

// `PropertyDiff` describes the kind of change that occurred to a property during a diff operation. A `PropertyDiff` may
// indicate that a property was added, deleted, or updated, and may further indicate that the change requires a
// replacement.
message PropertyDiff {
    // The kind of diff associated with this property.
    Kind kind = 1;

    // True if and only if this difference represents one between a pair of old and new inputs, as opposed to a pair of
    // old and new states.
    bool inputDiff = 2;

    // The type of property diff kinds.
    enum Kind {
        // This property was added.
        ADD = 0;

        // This property was added, and this change requires a replace.
        ADD_REPLACE = 1;

        // This property was removed.
        DELETE = 2;

        // This property was removed, and this change requires a replace.
        DELETE_REPLACE = 3;

        // This property's value was changed.
        UPDATE = 4;

        // This property's value was changed, and this change requires a replace.
        UPDATE_REPLACE = 5;
    }
}

// `DiffResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.DiffConfig) or
// [](pulumirpc.ResourceProvider.Diff) call. A `DiffResponse` indicates whether a resource is unchanged, requires
// updating (that is, can be changed "in place"), or requires replacement (that is, must be destroyed and recreated
// anew). Legacy implementations may also signal that it is unknown whether there are changes or not.
//
// `DiffResponse` has evolved since its inception and there are now a number of ways that providers can signal their
// intent to callers:
//
// * *Simple diffs* utilise the `changes` field to signal which fields are responsible for a change, and the `replaces`
//   field to further communicate which changes (if any) require a replacement as opposed to an update.
//
// * *Detailed diffs* are those with `hasDetailedDiff` set, and utilise the `detailedDiff` field to provide a more
//   granular view of the changes that have occurred. Detailed diffs are designed to allow providers to control
//   precisely which field names are displayed as responsible for a change, and to signal more accurately what kind of
//   change occurred (e.g. a field was added, deleted or updated).
message DiffResponse {
    // A set of properties which have changed and whose changes require the resource being diffed to be replaced. The
    // caller should replace the resource if this set is non-empty, or if any of the properties specified in
    // `detailedDiff` have a `*_REPLACE` kind.
    repeated string replaces = 1;

    // An optional list of properties that will not ever change (are stable).
    repeated string stables = 2;

    // If true, this resource must be deleted *before* its replacement is created.
    bool deleteBeforeReplace = 3;

    // The result of the diff. Indicates at a high level whether the resource has changed or not (or, in legacy cases,
    // if the provider does not know).
    DiffChanges changes = 4;

    // The set of properties which have changed. This field only supports top-level properties. It *does not* support
    // full [property paths](property-paths); implementations should use `detailedDiff` when this is required.
    repeated string diffs = 5;

    // `detailedDiff` can be used to implement more detailed diffs. A detailed diff is a map from [property
    // paths](property-paths) to [](pulumirpc.PropertyDiff)s, which describe the kind of change that occurred to the
    // property located at that path. If a provider does not implement this, the caller (typically the Pulumi engine)
    // will compute a representation based on the simple diff fields (`changes`, `replaces`, and so on).
    map<string, PropertyDiff> detailedDiff = 6;

    // True if and only if this response contains a `detailedDiff`.
    bool hasDetailedDiff = 7;

    // The type of high-level diff results.
    enum DiffChanges {
        // A diff was performed but it is unknown whether there are changes or not. This exists to support legacy
        // behaviour and should be generally avoided wherever possible.
        DIFF_UNKNOWN = 0;

        // A diff was performed and there were no changes. An update is not required.
        DIFF_NONE = 1;

        // A diff was performed, and changes were detected that require an update or replacement.
        DIFF_SOME = 2;
    }
}

// `CreateRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Create) call.
message CreateRequest {
    // The URN of the resource being created.
    string urn = 1;

    // The resource's input properties, to be set during creation. These should have been validated by a call to
    // [](pulumirpc.ResourceProvider.Check).
    google.protobuf.Struct properties = 2;

    // A timeout in seconds that the caller is prepared to wait for the operation to complete.
    double timeout = 3;

    // True if and only if the request is being made as part of a preview/dry run, in which case the provider should not
    // actually create the resource.
    bool preview = 4;

    // The name of the resource being created. This must match the name specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 5;

    // The type of the resource being created. This must match the type specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 6;
}

// `CreateResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Create) call. A `CreateResponse`
// contains the ID of the created resource, as well as any output properties that arose from the creation process.
message CreateResponse {
    // The ID of the created resource.
    string id = 1;

    // The resource's output properties. Typically this will be a union of the resource's input properties and any
    // additional values that were computed or made available during creation.
    google.protobuf.Struct properties = 2;
}

// `ReadRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Read) call.
message ReadRequest {
    // The ID of the resource to read.
    string id = 1;

    // The URN of the resource being read.
    string urn = 2;

    // Any current state for the resource being read. This state should be sufficient to uniquely identify the resource.
    google.protobuf.Struct properties = 3;

    // Any current input properties for the resource being read. These will only be populated when the
    // [](pulumirpc.ResourceProvider.Read) call is being made as part of a refresh operation.
    google.protobuf.Struct inputs = 4;

    // The name of the resource being read. This must match the name specified by the `urn` field, and is passed so that
    // providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 5;

    // The type of the resource being read. This must match the type specified by the `urn` field, and is passed so that
    // providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 6;
}

// `ReadResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Read) call. A `ReadResponse` contains
// the ID of the resource being read, as well as any state that was successfully read from the live environment.
message ReadResponse {
    // The ID of the read resource.
    string id = 1;

    // The output properties of the resource read from the live environment.
    google.protobuf.Struct properties = 2;

    // Output-derived input properties for the resource. These are returned as they would be returned from a
    // [](pulumirpc.ResourceProvider.Check) call with the same values.
    google.protobuf.Struct inputs = 3;
}

// `UpdateRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Update) call.
message UpdateRequest {
    // The ID of the resource being updated.
    string id = 1;

    // The URN of the resource being updated.
    string urn = 2;

    // The old *output* properties of the resource being updated.
    google.protobuf.Struct olds = 3;

    // The new input properties of the resource being updated. These should have been validated by a call to
    // [](pulumirpc.ResourceProvider.Check).
    google.protobuf.Struct news = 4;

    // A timeout in seconds that the caller is prepared to wait for the operation to complete.
    double timeout = 5;

    // A set of [property paths](property-paths) that should be treated as unchanged.
    repeated string ignoreChanges = 6;

    // True if and only if the request is being made as part of a preview/dry run, in which case the provider should not
    // actually update the resource.
    bool preview = 7;

    // The old *input* properties of the resource being updated.
    google.protobuf.Struct old_inputs = 8;

    // The name of the resource being updated. This must match the name specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 9;

    // The type of the resource being updated. This must match the type specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 10;
}

// `UpdateResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Update) call.
message UpdateResponse {
    // An updated set of resource output properties. Typically this will be a union of the resource's inputs and any
    // additional values that were computed or made available during the update.
    google.protobuf.Struct properties = 1;
}

// `DeleteRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Delete) call.
message DeleteRequest {
    // The ID of the resource to delete.
    string id = 1;

    // The URN of the resource to delete.
    string urn = 2;

    // The old *output* properties of the resource being deleted.
    google.protobuf.Struct properties = 3;

    // A timeout in seconds that the caller is prepared to wait for the operation to complete.
    double timeout = 4;

    // The old *input* properties of the resource being deleted.
    google.protobuf.Struct old_inputs = 5; // the old input values of the resource to delete.

    // The name of the resource being deleted. This must match the name specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 6;

    // The type of the resource being deleted. This must match the type specified by the `urn` field, and is passed so
    // that providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 7;
}

// `ConstructRequest` is the type of requests sent as part of a [](pulumirpc.ResourceProvider.Construct) call. A
// `ConstructRequest` captures enough data to be able to register nested components against the caller's resource
// monitor.
message ConstructRequest {
    // A `PropertyDependencies` list is a set of URNs that a particular property may depend on.
    message PropertyDependencies {
        // A list of URNs that this property depends on.
        repeated string urns = 1;
    }

    // A `CustomTimeouts` object encapsulates a set of timeouts for the various CRUD operations that might be performed
    // on this resource's nested resources. Timeout values are specified as duration strings, such as `"5ms"` (5
    // milliseconds), `"40s"` (40 seconds), or `"1m30s"` (1 minute and 30 seconds). The following units of time are
    // supported:
    //
    // * `ns`: nanoseconds
    // * `us` or `µs`: microseconds
    // * `ms`: milliseconds
    // * `s`: seconds
    // * `m`: minutes
    // * `h`: hours
    message CustomTimeouts {
        // How long a caller is prepared to wait for a nested resource's [](pulumirpc.ResourceProvider.Create) operation
        // to complete.
        string create = 1;

        // How long a caller is prepared to wait for a nested resource's [](pulumirpc.ResourceProvider.Update) operation
        // to complete.
        string update = 2;

        // How long a caller is prepared to wait for a nested resource's [](pulumirpc.ResourceProvider.Delete) operation
        // to complete.
        string delete = 3;
    }

    // The project to which this resource and its nested resources will belong.
    string project = 1;

    // The name of the stack being deployed into.
    string stack = 2;

    // Configuration for the specified project and stack.
    map<string, string> config = 3;

    // True if and only if the request is being made as part of a preview/dry run, in which case the provider should not
    // actually construct the component.
    bool dryRun = 4;

    // The degree of parallelism that may be used for resource operations. A value less than or equal to 1 indicates
    // that operations should be performed serially.
    int32 parallel = 5;

    // The address of the [](pulumirpc.ResourceMonitor) that the provider should connect to in order to send [resource
    // registrations](resource-registration) for its nested resources.
    string monitorEndpoint = 6;

    // The type of the component resource being constructed. This must match the type specified by the `urn` field, and
    // is passed so that providers do not have to implement URN parsing in order to extract the type of the resource.
    string type = 7;

    // The name of the component resource being constructed. This must match the name specified by the `urn` field, and
    // is passed so that providers do not have to implement URN parsing in order to extract the name of the resource.
    string name = 8;

    // Dependencies and resource options
    //
    // These are passed so that the component may propagate them to resources it registers against the supplied resource
    // monitor.
    //
    // Do *not* change field IDs. Add new fields at the end with appropriate field IDs as necessary.

    // An optional parent resource that the component (and by extension, its nested resources) should be children of.
    string parent = 9;

    // The component resource's input properties. Unlike the inputs of custom resources, these will *not* have been
    // passed to a call to [](pulumirpc.ResourceProvider.Check). By virtue of their being a composition of other
    // resources, component resources are able to (and therefore expected) to validate their own inputs. Moreover,
    // [](pulumirpc.ResourceProvider.Check) will be called on any inputs passed to nested custom resources as usual.
    google.protobuf.Struct inputs = 10;

    // A map of property dependencies for the component resource and its nested resources.
    map<string, PropertyDependencies> inputDependencies = 11;

    // A map of package names to provider references for the component resource and its nested resources.
    map<string, string> providers = 13;

    // A list of URNs that this resource and its nested resources depend on.
    repeated string dependencies = 15;

    // A set of configuration keys whose values are [secret](output-secrets).
    repeated string configSecretKeys = 16;

    // The organization to which this resource and its nested resources will belong.
    string organization = 17;

    // True if and only if the resource (and by extension, its nested resources) should be marked as protected.
    // Protected resources cannot be deleted without first being unprotected.
    bool protect = 12;

    // A list of additional URNs that should be considered the same as this component's URN (and which will therefore be
    // used to build aliases for its nested resource URNs). These may be URNs that previously referred to this component
    // e.g. if it had its parent (and consequently URN) changed.
    repeated string aliases = 14;

    // A list of input properties whose values should be treated as [secret](output-secrets).
    repeated string additionalSecretOutputs = 18;

    // A set of custom timeouts that specify how long the caller is prepared to wait for the various CRUD operations of
    // this resource's nested resources.
    CustomTimeouts customTimeouts = 19;

    // The URN of a resource that this resource (and thus its nested resources) will be implicitly deleted with. If the
    // resource referred to by this URN is deleted in the same operation that this resource would be deleted, the
    // [](pulumirpc.ResourceProvider.Delete) call for this resource will be elided (since this dependency signals that
    // it will have already been deleted).
    string deletedWith = 20;

    // If true, this resource (and its nested resources) must be deleted *before* its replacement is created.
    bool deleteBeforeReplace = 21;

    // A set of [property paths](property-paths) that should be treated as unchanged.
    repeated string ignoreChanges = 22;

    // A set of properties that, when changed, trigger a replacement.
    repeated string replaceOnChanges = 23;

    // True if [](pulumirpc.ResourceProvider.Delete) should *not* be called when the resource (and by extension, its
    // nested resources) are removed from a Pulumi program.
    bool retainOnDelete = 24;

    // True if the caller is capable of accepting output values in response to the call. If this is set, these outputs
    // may be used to communicate dependency information and so there is no need to populate
    // [](pulumirpc.ConstructResponse)'s `stateDependencies` field.
    bool accepts_output_values = 25;
}

// `ConstructResponse` is the type of responses sent by a [](pulumirpc.ResourceProvider.Construct) call.
message ConstructResponse {
    // A `PropertyDependencies` list is a set of URNs that a particular property may depend on.
    message PropertyDependencies {
        // A list of URNs that this property depends on.
        repeated string urns = 1;
    }

    // The URN of the constructed component resource.
    string urn = 1;

    // Any output properties that the component registered as part of its construction.
    google.protobuf.Struct state = 2;

    // A map of property dependencies for the component's outputs. This will be set if the caller indicated that it
    // could not receive dependency-communicating [output](outputs) values by setting [](pulumirpc.ConstructRequest)'s
    // `accepts_output_values` field to false.
    map<string, PropertyDependencies> stateDependencies = 3;
}

// ErrorResourceInitFailed is sent as a Detail `ResourceProvider.{Create, Update}` fail because a
// resource was created successfully, but failed to initialize.
message ErrorResourceInitFailed {
    string id = 1;                         // the ID of the created resource.
    google.protobuf.Struct properties = 2; // any properties that were computed during updating.
    repeated string reasons = 3;           // error messages associated with initialization failure.
    google.protobuf.Struct inputs = 4;     // the current inputs to this resource (only applicable for Read)
}



// GetMappingRequest allows providers to return ecosystem specific information to allow the provider to be
// converted from a source markup to Pulumi. It's expected that provider bridges that target a given ecosystem
// (e.g. Terraform, Kubernetes) would also publish a conversion plugin to convert markup from that ecosystem
// to Pulumi, using the bridged providers.
message GetMappingRequest {
    // the conversion key for the mapping being requested.
    string key = 1;
    // the optional provider key for the mapping being requested, if this is empty the provider should assume this
    // request is from an old engine from before GetMappings and should return it's "primary" mapping. If this is set
    // then the `provider` field in GetMappingResponse should be the same.
    string provider = 2;
}

// GetMappingResponse returns convert plugin specific data for this provider. This will normally be human
// readable JSON, but the engine doesn't mandate any form.
message GetMappingResponse {
    // the provider key this is mapping for. For example the Pulumi provider "terraform-template" would return "template" for this.
    string provider = 1;

    // the conversion plugin specific data.
    bytes data = 2;
}

// GetMappingsRequest allows providers to return ecosystem specific information without having to send back large data
// blobs for provider mappings that the engine doesn't then need.
message GetMappingsRequest {
    // the conversion key for the mapping being requested.
    string key = 1;
}

// GetMappingsRequest returns a list of providers that this provider can provide mapping information for.
message GetMappingsResponse {
    // the provider keys this provider can supply mappings for. For example the Pulumi provider "terraform-template"
    // would return ["template"] for this.
    repeated string providers = 1;
}