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";
import "pulumi/source.proto";

package pulumirpc;

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

// 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.
service ResourceProvider {
    // GetSchema fetches the schema for this resource provider.
    rpc GetSchema(GetSchemaRequest) returns (GetSchemaResponse) {}

    // CheckConfig validates the configuration for this resource provider.
    rpc CheckConfig(CheckRequest) returns (CheckResponse) {}
    // DiffConfig checks the impact a hypothetical change to this provider's configuration will have on the provider.
    rpc DiffConfig(DiffRequest) returns (DiffResponse) {}
    // Configure configures the resource provider with "globals" that control its behavior.
    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 that the given property bag is valid for a resource of the given type and returns the inputs
    // that should be passed to successive calls to Diff, Create, or Update for this resource. 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 using for detecting and rendering diffs.
    rpc Check(CheckRequest) returns (CheckResponse) {}
    // Diff checks what impacts a hypothetical update will have on the resource's properties.
    rpc Diff(DiffRequest) returns (DiffResponse) {}
    // Create allocates a new instance of the provided resource and returns its unique ID afterwards.  (The input ID
    // must be blank.)  If this call fails, the resource must not have been created (i.e., it is "transactional").
    rpc Create(CreateRequest) returns (CreateResponse) {}
    // Read the current live state associated with a resource.  Enough state must be include in the inputs to uniquely
    // identify the resource; this is typically just the resource ID, but may also include some properties.
    rpc Read(ReadRequest) returns (ReadResponse) {}
    // Update updates an existing resource with new values.
    rpc Update(UpdateRequest) returns (UpdateResponse) {}
    // Delete tears down an existing resource with the given ID.  If it fails, the resource is assumed to still exist.
    rpc Delete(DeleteRequest) returns (google.protobuf.Empty) {}

    // Construct creates a new instance of the provided component resource and returns its state.
    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) {}
}

message GetSchemaRequest {
    int32 version = 1; // the schema version.
}

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

message ConfigureRequest {
    map<string, string> variables = 1; // a map of configuration keys to values.
    google.protobuf.Struct args = 2;   // the input properties for the provider. Only filled in for newer providers.
    bool acceptSecrets  = 3;           // when true, operations should return secrets as strongly typed.
    bool acceptResources = 4;          // when true, operations should return resources as strongly typed values to the provider.
    bool sends_old_inputs = 5;         // when true, diff and update will be called with the old outputs and the old inputs.
    bool sends_old_inputs_to_delete = 6; // when true, delete will be called with the old outputs and the old inputs.
}

message ConfigureResponse {
    bool acceptSecrets = 1;   // when true, the engine should pass secrets as strongly typed values to the provider.
    bool supportsPreview = 2; // when true, the engine should invoke create and update with preview=true during previews.
    bool acceptResources = 3; // when true, the engine should pass resources as strongly typed values to the provider.
    bool acceptOutputs = 4;   // when true, the engine should pass output values to the provider.
}

// ConfigureErrorMissingKeys is sent as a Detail on an error returned from `ResourceProvider.Configure`.
message ConfigureErrorMissingKeys {
    message MissingKey {
        string name = 1;        // the Pulumi name (not the provider name!) of the missing config key.
        string description = 2; // a description of the missing config key, as reported by the provider.
    }

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

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.
    }

    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 provider = 4;                                   // an optional reference to the provider to use for this invoke.
    string version = 5;                                    // the version of the provider to use when servicing this request.
    string pluginDownloadURL = 13;                         // the pluginDownloadURL of the provider to use when servicing this request.
    map<string, bytes> pluginChecksums = 16;               // a map of checksums of the provider to use when servicing this request.

    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.

    SourcePosition sourcePosition = 15; // the optional source position of the user code that initiated the call.
}

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.
    map<string, ReturnDependencies> returnDependencies = 2; // a map from return value keys to the dependencies of the return value.
    repeated CheckFailure failures = 3;                     // the failures if any arguments didn't pass verification.
}

message CheckRequest {
    string urn = 1;                  // the Pulumi URN for this resource.
    google.protobuf.Struct olds = 2; // the old Pulumi inputs for this resource, if any.
    google.protobuf.Struct news = 3; // the new Pulumi inputs for this resource.

    // We used to send sequenceNumber but that has been replaced by randomSeed.
    reserved 4;
    reserved "sequenceNumber";

    bytes randomSeed = 5;            // a deterministically random hash, primarily intended for global unique naming.
}

message CheckResponse {
    google.protobuf.Struct inputs = 1;  // the provider inputs for this resource.
    repeated CheckFailure failures = 2; // any validation failures that occurred.
}

message CheckFailure {
    string property = 1; // the property that failed validation.
    string reason = 2;   // the reason that the property failed validation.
}

message DiffRequest {
    string id = 1;                     // the ID of the resource to diff.
    string urn = 2;                    // the Pulumi URN for this resource.
    google.protobuf.Struct olds = 3;   // the old output values of resource to diff.
    google.protobuf.Struct news = 4;   // the new input values of resource to diff.
    repeated string ignoreChanges = 5; // a set of property paths that should be treated as unchanged.
    google.protobuf.Struct old_inputs = 6;   // the old input values of the resource to diff.
}

message PropertyDiff {
    Kind kind = 1; // The kind of diff asdsociated with this property.
    bool inputDiff = 2; // The difference is between old and new inputs, not old and new state.

    enum Kind {
        ADD = 0;            // this property was added
        ADD_REPLACE = 1;    // this property was added, and this change requires a replace
        DELETE = 2;         // this property was removed
        DELETE_REPLACE = 3; // this property was removed, and this change requires a replace
        UPDATE = 4;         // this property's value was changed
        UPDATE_REPLACE = 5; // this property's value was changed, and this change requires a replace
    }
}

message DiffResponse {
    repeated string replaces = 1; // if this update requires a replacement, the set of properties triggering it.
    repeated string stables = 2;  // an optional list of properties that will not ever change.
    bool deleteBeforeReplace = 3; // if true, this resource must be deleted before replacing it.
    DiffChanges changes = 4;      // if true, this diff represents an actual difference and thus requires an update.
    repeated string diffs = 5;    // a list of the properties that changed.

    // detailedDiff is an optional field that contains map from each changed property to the type of the change.
    //
    // The keys of this map are property paths. These paths are essentially Javascript property access expressions
    // in which all elements are literals, and obey the following EBNF-ish grammar:
    //
    //   propertyName := [a-zA-Z_$] { [a-zA-Z0-9_$] }
    //   quotedPropertyName := '"' ( '\' '"' | [^"] ) { ( '\' '"' | [^"] ) } '"'
    //   arrayIndex := { [0-9] }
    //
    //   propertyIndex := '[' ( quotedPropertyName | arrayIndex ) ']'
    //   rootProperty := ( propertyName | propertyIndex )
    //   propertyAccessor := ( ( '.' propertyName ) |  propertyIndex )
    //   path := rootProperty { propertyAccessor }
    //
    // Examples of valid keys:
    // - root
    // - root.nested
    // - root["nested"]
    // - root.double.nest
    // - root["double"].nest
    // - root["double"]["nest"]
    // - root.array[0]
    // - root.array[100]
    // - root.array[0].nested
    // - root.array[0][1].nested
    // - root.nested.array[0].double[1]
    // - root["key with \"escaped\" quotes"]
    // - root["key with a ."]
    // - ["root key with \"escaped\" quotes"].nested
    // - ["root key with a ."][100]
    map<string, PropertyDiff> detailedDiff = 6; // a detailed diff appropriate for display.
    bool hasDetailedDiff = 7; // true if this response contains a detailed diff.

    enum DiffChanges {
        DIFF_UNKNOWN = 0; // unknown whether there are changes or not (legacy behavior).
        DIFF_NONE    = 1; // the diff was performed, and no changes were detected that require an update.
        DIFF_SOME    = 2; // the diff was performed, and changes were detected that require an update or replacement.
    }
}

message CreateRequest {
    string urn = 1;                        // the Pulumi URN for this resource.
    google.protobuf.Struct properties = 2; // the provider inputs to set during creation.
    double timeout = 3;                    // the create request timeout represented in seconds.
    bool preview = 4;                      // true if this is a preview and the provider should not actually create the resource.
}

message CreateResponse {
    // NOTE: The partial-update-error equivalent of this message is `ErrorResourceInitFailed`.

    string id = 1;                         // the ID of the created resource.
    google.protobuf.Struct properties = 2; // any properties that were computed during creation.
}

message ReadRequest {
    string id = 1;                         // the ID of the resource to read.
    string urn = 2;                        // the Pulumi URN for this resource.
    google.protobuf.Struct properties = 3; // the current state (sufficiently complete to identify the resource).
    google.protobuf.Struct inputs = 4;     // the current inputs, if any (only populated during refresh).
}

message ReadResponse {
    string id = 1;                         // the ID of the resource read back (or empty if missing).
    google.protobuf.Struct properties = 2; // the state of the resource read from the live environment.
    google.protobuf.Struct inputs = 3;     // the inputs for this resource that would be returned from Check.
}

message UpdateRequest {
    // NOTE: The partial-update-error equivalent of this message is `ErrorResourceInitFailed`.

    string id = 1;                     // the ID of the resource to update.
    string urn = 2;                    // the Pulumi URN for this resource.
    google.protobuf.Struct olds = 3;   // the old values of provider inputs for the resource to update.
    google.protobuf.Struct news = 4;   // the new values of provider inputs for the resource to update.
    double timeout = 5;                // the update request timeout represented in seconds.
    repeated string ignoreChanges = 6; // a set of property paths that should be treated as unchanged.
    bool preview = 7;                   // true if this is a preview and the provider should not actually create the resource.
    google.protobuf.Struct old_inputs = 8; // the old input values of the resource to diff.
}

message UpdateResponse {
    google.protobuf.Struct properties = 1; // any properties that were computed during updating.
}

message DeleteRequest {
    string id = 1;                         // the ID of the resource to delete.
    string urn = 2;                        // the Pulumi URN for this resource.
    google.protobuf.Struct properties = 3; // the current properties on the resource.
    double timeout = 4;                    // the delete request timeout represented in seconds.
    google.protobuf.Struct old_inputs = 5; // the old input values of the resource to delete.
}

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

    // CustomTimeouts specifies timeouts for resource provisioning operations.
    // Use it with the [Timeouts] option when creating new resources
    // to override default timeouts.
    //
    // Each timeout is specified as a duration string such as,
    // "5ms" (5 milliseconds), "40s" (40 seconds),
    // and "1m30s" (1 minute, 30 seconds).
    //
    // The following units are accepted.
    //
    //   - ns: nanoseconds
    //   - us: microseconds
    //   - µs: microseconds
    //   - ms: milliseconds
    //   - s: seconds
    //   - m: minutes
    //   - h: hours
    message CustomTimeouts {
        string create = 1;
        string update = 2;
        string delete = 3;
    }

    string project = 1;             // the project name.
    string stack = 2;               // the name of the stack being deployed into.
    map<string, string> config = 3; // the configuration variables to apply before running.
    bool dryRun = 4;                // true if we're only doing a dryrun (preview).
    int32 parallel = 5;             // the degree of parallelism for resource operations (<=1 for serial).
    string monitorEndpoint = 6;     // the address for communicating back to the resource monitor.

    string type = 7;                                          // the type of the object allocated.
    string name = 8;                                          // the name, for URN purposes, of the object.
    string parent = 9;                                        // an optional parent URN that this child resource belongs to.
    google.protobuf.Struct inputs = 10;                       // the inputs to the resource constructor.
    map<string, PropertyDependencies> inputDependencies = 11; // a map from property keys to the dependencies of the property.
    map<string, string> providers = 13;                       // the map of providers to use for this resource's children.
    repeated string dependencies = 15;                        // a list of URNs that this resource depends on, as observed by the language host.
    repeated string configSecretKeys = 16;                    // the configuration keys that have secret values.
    string organization = 17;                                 // the organization of the stack being deployed into.

    // Resource options:
    // Do not change field IDs. Add new fields at the end.
    bool protect                            = 12; // true if the resource should be marked protected.
    repeated string aliases                 = 14; // a list of additional URNs that shoud be considered the same.
    repeated string additionalSecretOutputs = 18; // additional output properties that should be treated as secrets.
    CustomTimeouts customTimeouts           = 19; // default timeouts for CRUD operations on this resource.
    string deletedWith                      = 20; // URN of a resource that, if deleted, also deletes this resource.
    bool deleteBeforeReplace                = 21; // whether to delete the resource before replacing it.
    repeated string ignoreChanges           = 22; // properties that should be ignored during a diff
    repeated string replaceOnChanges        = 23; // properties that, when changed, trigger a replacement
    bool retainOnDelete                     = 24; // whether to retain the resource in the cloud provider when it is deleted
}

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

    string urn = 1;                                          // the URN of the component resource.
    google.protobuf.Struct state = 2;                        // any properties that were computed during construction.
    map<string, PropertyDependencies> stateDependencies = 3; // a map from property keys to the dependencies of the property.
}

// 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;
}