This commit changes two things about our resource model: * Stop performing Pulumi Engine-side diffing of resource state. Instead, we defer to the resource plugins themselves to determine whether a change was made and, if so, the extent of it. This manifests as a simple change to the Diff function; it is done in a backwards compatible way so that we continue with legacy diffing for existing resource provider plugins. * Add a Read RPC method for resource providers. It simply takes a resource's ID and URN, plus an optional bag of further qualifying state, and it returns the current property state as read back from the actual live environment. Note that the optional bag of state must at least include enough additional properties for resources wherein the ID is insufficient for the provider to perform a lookup. It may, however, include the full bag of prior state, for instance in the case of a refresh operation. This is part of pulumi/pulumi#1108.
135 lines
6.7 KiB
Protocol Buffer
135 lines
6.7 KiB
Protocol Buffer
// Copyright 2016-2018, Pulumi Corporation. All rights reserved.
|
|
|
|
syntax = "proto3";
|
|
|
|
import "plugin.proto";
|
|
import "google/protobuf/empty.proto";
|
|
import "google/protobuf/struct.proto";
|
|
|
|
package 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 {
|
|
// Configure configures the resource provider with "globals" that control its behavior.
|
|
rpc Configure(ConfigureRequest) returns (google.protobuf.Empty) {}
|
|
// Invoke dynamically executes a built-in function in the provider.
|
|
rpc Invoke(InvokeRequest) returns (InvokeResponse) {}
|
|
// 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 "transacational").
|
|
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) {}
|
|
// GetPluginInfo returns generic information about this plugin, like its version.
|
|
rpc GetPluginInfo(google.protobuf.Empty) returns (PluginInfo) {}
|
|
}
|
|
|
|
message ConfigureRequest {
|
|
map<string, string> variables = 1; // a map of configuration keys to values.
|
|
}
|
|
|
|
// 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.
|
|
}
|
|
|
|
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 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.
|
|
}
|
|
|
|
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 values of provider inputs to diff.
|
|
google.protobuf.Struct news = 4; // the new values of provider inputs to diff.
|
|
}
|
|
|
|
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.
|
|
|
|
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.
|
|
}
|
|
|
|
message CreateResponse {
|
|
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).
|
|
}
|
|
|
|
message ReadResponse {
|
|
google.protobuf.Struct properties = 1; // the state of the resource read from the live environment.
|
|
}
|
|
|
|
message UpdateRequest {
|
|
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.
|
|
}
|
|
|
|
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.
|
|
}
|