WIP: Add a 'remote' ExternalClient

Signed-off-by: Nic Cope <[email protected]>

apis/proto/external/v1alpha1/external.proto

@@ -0,0 +1,136 @@
+/*
+Copyright 2024 The Crossplane Authors.
+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";
+
+package external.proto.v1alpha1;
+
+import "google/protobuf/struct.proto";
+
+option go_package = "github.com/crossplane/crossplane-runtime/apis/proto/external/v1alpha1";
+
+// An ExternalService observes, creates, updates, and deletes external resources.
+service ExternalService {
+	// Observe the external resource the supplied managed resource represents,
+	// if any. Observe implementations must not modify the external resource,
+	// but may update the supplied managed resource to reflect the state of the
+	// external resource. Status modifications are automatically persisted
+	// unless resource_late_initialized is true.
+    rpc Observe(ObserveRequest) returns (ObserveResponse) {}
+
+	// Create an external resource per the specifications of the supplied
+	// managed resource. Called when Observe reports that the associated
+	// external resource does not exist. Create implementations may update
+	// managed resource annotations, and those updates will be persisted. All
+	// other updates will be discarded.
+    rpc Create(CreateRequest) returns (CreateResponse) {}
+
+	// Update the external resource represented by the supplied managed
+	// resource, if necessary. Called unless Observe reports that the associated
+	// external resource is up to date.
+    rpc Update(UpdateRequest) returns (UpdateResponse) {}
+
+	// Delete the external resource upon deletion of its associated managed
+	// resource. Called when the managed resource has been deleted.
+    rpc Delete(DeleteRequest) returns (DeleteResponse) {}
+}
+
+// An ObserveRequest requests that an external resource be observed.
+message ObserveRequest {
+    // The JSON representation of the managed resource to observe.
+    google.protobuf.Struct resource = 1;
+}
+
+// An ObserveResponse contains the result of observing an external resource.
+message ObserveResponse {
+    // The JSON representation of the observed managed resource.
+    google.protobuf.Struct resource = 1;
+
+	// Connection details required to connect to this resource. These details
+	// are a set that is collated throughout the managed resource's lifecycle -
+	// i.e. returning new connection details will have no affect on old details
+	// unless an existing key is overwritten. Crossplane may publish these
+	// credentials to a store (e.g. a Secret).
+    map<string, bytes> connection_details = 2;
+
+	// Must be true if a corresponding external resource exists for the managed
+	// resource. Typically this is proven by the presence of an external
+	// resource of the expected kind whose unique identifier matches the managed
+	// resource's external name. Crossplane uses this information to determine
+	// whether it needs to create or delete the external resource.
+    bool resource_exists = 3;
+
+	// Must be true if the corresponding external resource appears to be
+	// up-to-date - i.e. updating the external resource to match the desired
+	// state of the managed resource would be a no-op. Keep in mind that often
+	// only a subset of external resource fields can be updated. Crossplane uses
+	// this information to determine whether it needs to update the external
+	// resource.
+    bool resource_up_to_date = 4;
+
+    // Must be true if the managed resource's spec was updated during its
+    // observation. A Crossplane provider may update a managed resource's spec
+    // fields after it is created or updated, as long as the updates are limited
+    // to setting previously unset fields, and adding keys to maps. Crossplane
+    // uses this information to determine whether changes to the spec were made
+    // during observation that must be persisted. Note that changes to the spec
+    // will be persisted before changes to the status, and that pending changes
+    // to the status may be lost when the spec is persisted. Status changes will
+    // be persisted by the first subsequent observation that _does not_ late
+    // initialize the managed resource, so it is important that Observe
+    // implementations do not late initialize the resource every time they are
+    // called.
+    bool resource_late_initialized = 5;
+}
+
+// A CreateRequest requests that an external resource be created.
+message CreateRequest {
+    // The JSON representation of the managed resource to create.
+    google.protobuf.Struct resource = 1;
+}
+
+// A CreateResponse contains the result of creating an external resource.
+message CreateResponse {
+    // The JSON representation of the created managed resource.
+    google.protobuf.Struct resource = 1;
+
+    map<string, bytes> connection_details = 2;
+}
+
+// An UpdateRequest requests that an external resource be updated.
+message UpdateRequest {
+    // The JSON representation of the managed resource to update.
+    google.protobuf.Struct resource = 1;
+
+    map<string, bytes> connection_details = 2;
+}
+
+// An UpdateResponse contains the result of updating an external resource.
+message UpdateResponse {
+    // The JSON representation of the updated managed resource.
+    google.protobuf.Struct resource = 1;
+
+    map<string, bytes> connection_details = 2;
+}
+
+// A DeleteRequest requests that an external resource be deleted.
+message DeleteRequest {
+    // The JSON representation of the managed resource to delete.
+    google.protobuf.Struct resource = 1;
+}
+
+// A DeleteResponse contains the result of deleting an external resource.
+message DeleteResponse {
+    // The JSON representation of the deleted managed resource.
+    google.protobuf.Struct resource = 1;
+}