pulumi/sdk/proto/resource.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 "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "provider.proto";

package pulumirpc;

// ResourceMonitor is the interface a source uses to talk back to the planning monitor orchestrating the execution.
service ResourceMonitor {
    rpc SupportsFeature(SupportsFeatureRequest) returns (SupportsFeatureResponse) {}
    rpc Invoke(InvokeRequest) returns (InvokeResponse) {}
    rpc ReadResource(ReadResourceRequest) returns (ReadResourceResponse) {}
    rpc RegisterResource(RegisterResourceRequest) returns (RegisterResourceResponse) {}
    rpc RegisterResourceOutputs(RegisterResourceOutputsRequest) returns (google.protobuf.Empty) {}
}

// SupportsFeatureRequest allows a client to test if the resource monitor supports a certain feature, which it may use
// to control the format or types of messages it sends.
message SupportsFeatureRequest {
    string id = 1;  // the ID of the feature to test support for.
}

message SupportsFeatureResponse {
    bool hasSupport = 1; // true when the resource monitor supports this feature.
}

// There is a clear distinction here between the "properties" bag sent across the wire as part of these RPCs and
// properties that exist on Pulumi resources as projected into the target language. It is important to call out that the
// properties here are in the format that a provider will expect. This is to say that they are usually in camel case.
// If a language wants to project properties in a format *other* than camel-case, it is the job of the language to
// ensure that the properties are translated into camel case before invoking an RPC.

// ReadResourceRequest contains enough information to uniquely qualify and read a resource's state.
message ReadResourceRequest {
    string id = 1;                         // the ID of the resource to read.
    string type = 2;                       // the type of the resource object.
    string name = 3;                       // the name, for URN purposes, of the object.
    string parent = 4;                     // an optional parent URN that this child resource belongs to.
    google.protobuf.Struct properties = 5; // optional state sufficient to uniquely identify the resource.
    repeated string dependencies = 6;      // a list of URNs that this read depends on, as observed by the language host.
    string provider = 7;                   // an optional reference to the provider to use for this read.
    string version = 8;                    // the version of the provider to use when servicing this request.
    bool acceptSecrets = 9;                // when true operations should return secrets as strongly typed.
    repeated string additionalSecretOutputs = 10;   // a list of output properties that should also be treated as secret, in addition to ones we detect.
    repeated string aliases = 11;           // a list of additional URNs that shoud be considered the same.
}

// ReadResourceResponse contains the result of reading a resource's state.
message ReadResourceResponse {
    string urn = 1;                        // the URN for this resource.
    google.protobuf.Struct properties = 2; // the state of the resource read from the live environment.
}

// RegisterResourceRequest contains information about a resource object that was newly allocated.
message RegisterResourceRequest {
    // 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 type = 1;                   // the type of the object allocated.
    string name = 2;                   // the name, for URN purposes, of the object.
    string parent = 3;                 // an optional parent URN that this child resource belongs to.
    bool custom = 4;                   // true if the resource is a custom, managed by a plugin's CRUD operations.
    google.protobuf.Struct object = 5; // an object produced by the interpreter/source.
    bool protect = 6;                  // true if the resource should be marked protected.
    repeated string dependencies = 7;  // a list of URNs that this resource depends on, as observed by the language host.
    string provider = 8;               // an optional reference to the provider to manage this resource's CRUD operations.
    map<string, PropertyDependencies> propertyDependencies = 9; // a map from property keys to the dependencies of the property.
    bool deleteBeforeReplace = 10;     // true if this resource should be deleted before replacement.
    string version = 11;               // the version of the provider to use when servicing this request.
    repeated string ignoreChanges = 12; // a list of property selectors to ignore during updates.
    bool acceptSecrets = 13;           // when true operations should return secrets as strongly typed.
    repeated string additionalSecretOutputs = 14;  // a list of output properties that should also be treated as secret, in addition to ones we detect.
    repeated string aliases = 15;      // a list of additional URNs that shoud be considered the same.
}

// RegisterResourceResponse is returned by the engine after a resource has finished being initialized.  It includes the
// auto-assigned URN, the provider-assigned ID, and any other properties initialized by the engine.
message RegisterResourceResponse {
    string urn = 1;                    // the URN assigned by the engine.
    string id = 2;                     // the unique ID assigned by the provider.
    google.protobuf.Struct object = 3; // the resulting object properties, including provider defaults.
    bool stable = 4;                   // if true, the object's state is stable and may be trusted not to change.
    repeated string stables = 5;       // an optional list of guaranteed-stable properties.
}

// RegisterResourceOutputsRequest adds extra resource outputs created by the program after registration has occurred.
message RegisterResourceOutputsRequest {
    string urn = 1;                     // the URN for the resource to attach output properties to.
    google.protobuf.Struct outputs = 2; // additional output properties to add to the existing resource.
}