2023-03-28 22:48:58 +00:00
|
|
|
// Copyright (c) HashiCorp, Inc.
|
2023-08-21 17:31:54 +00:00
|
|
|
// SPDX-License-Identifier: MPL-2.0
|
2023-03-28 22:48:58 +00:00
|
|
|
|
2023-03-09 19:40:23 +00:00
|
|
|
syntax = "proto3";
|
|
|
|
|
2023-05-15 11:34:36 +00:00
|
|
|
// For more information, see: https://github.com/hashicorp/consul/tree/main/docs/resources
|
2023-03-09 19:40:23 +00:00
|
|
|
package hashicorp.consul.resource;
|
|
|
|
|
|
|
|
import "annotations/ratelimit/ratelimit.proto";
|
|
|
|
import "google/protobuf/any.proto";
|
2023-05-09 18:57:40 +00:00
|
|
|
import "google/protobuf/timestamp.proto";
|
2023-03-09 19:40:23 +00:00
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Type describes a resource's type. It follows the GVK (Group Version Kind)
|
|
|
|
// [pattern](https://book.kubebuilder.io/cronjob-tutorial/gvks.html) established
|
|
|
|
// by Kubernetes.
|
2023-03-09 19:40:23 +00:00
|
|
|
message Type {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Group describes the area of functionality to which this resource type
|
|
|
|
// relates (e.g. "catalog", "authorization").
|
2023-03-09 19:40:23 +00:00
|
|
|
string group = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// GroupVersion is incremented when sweeping or backward-incompatible changes
|
|
|
|
// are made to the group's resource types.
|
2023-03-09 19:40:23 +00:00
|
|
|
string group_version = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Kind identifies the specific resource type within the group.
|
2023-03-09 19:40:23 +00:00
|
|
|
string kind = 3;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Tenancy describes the tenancy units in which the resource resides.
|
2023-03-09 19:40:23 +00:00
|
|
|
message Tenancy {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Partition is the topmost administrative boundary within a cluster.
|
|
|
|
// https://developer.hashicorp.com/consul/docs/enterprise/admin-partitions
|
|
|
|
//
|
|
|
|
// When using the List and WatchList endpoints, provide the wildcard value "*"
|
|
|
|
// to list resources across all partitions.
|
2023-03-09 19:40:23 +00:00
|
|
|
string partition = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Namespace further isolates resources within a partition.
|
|
|
|
// https://developer.hashicorp.com/consul/docs/enterprise/namespaces
|
|
|
|
//
|
|
|
|
// When using the List and WatchList endpoints, provide the wildcard value "*"
|
|
|
|
// to list resources across all namespaces.
|
2023-03-09 19:40:23 +00:00
|
|
|
string namespace = 2;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// ID uniquely identifies a resource.
|
2023-03-09 19:40:23 +00:00
|
|
|
message ID {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Uid is the unique internal identifier we gave to the resource.
|
|
|
|
//
|
|
|
|
// It is primarily used to tell the difference between the current resource
|
|
|
|
// and previous deleted resources with the same user-given name.
|
|
|
|
//
|
|
|
|
// Concretely, Uid is a [ULID](https://github.com/ulid/spec) and you can treat
|
|
|
|
// its timestamp component as the resource's creation time.
|
2023-03-09 19:40:23 +00:00
|
|
|
string uid = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Name is the user-given name of the resource (e.g. the "billing" service).
|
2023-03-09 19:40:23 +00:00
|
|
|
string name = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Type identifies the resource's type.
|
2023-03-09 19:40:23 +00:00
|
|
|
Type type = 3;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Tenancy identifies the tenancy units (i.e. partition, namespace) in which
|
|
|
|
// the resource resides.
|
2023-03-09 19:40:23 +00:00
|
|
|
Tenancy tenancy = 4;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resource describes a resource of a known type managed by Consul.
|
2023-03-09 19:40:23 +00:00
|
|
|
message Resource {
|
2023-04-26 15:26:54 +00:00
|
|
|
// ID uniquely identifies the resource.
|
2023-03-09 19:40:23 +00:00
|
|
|
ID id = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Owner (optionally) describes which resource "owns" this resource, it is
|
|
|
|
// immutable and can only be set on resource creation. Owned resources will
|
|
|
|
// be automatically deleted when their owner is deleted.
|
2023-03-09 19:40:23 +00:00
|
|
|
ID owner = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Version is the low-level version identifier used by the storage backend
|
|
|
|
// in CAS (Compare-And-Swap) operations. It will change when the resource is
|
|
|
|
// modified in any way, including status updates.
|
|
|
|
//
|
|
|
|
// When calling the Write endpoint, providing a non-blank version will perform
|
|
|
|
// a CAS (Compare-And-Swap) write, which will result in an Aborted error code
|
|
|
|
// if the given version doesn't match what is stored.
|
2023-03-09 19:40:23 +00:00
|
|
|
string version = 3;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Generation is incremented whenever the resource's content (i.e. not its
|
|
|
|
// status) is modified. You can think of it as being the "user version".
|
|
|
|
//
|
|
|
|
// Concretely, Generation is a [ULID](https://github.com/ulid/spec) and you
|
|
|
|
// can treat its timestamp component as the resource's modification time.
|
2023-03-09 19:40:23 +00:00
|
|
|
string generation = 4;
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Metadata contains key/value pairs of arbitrary metadata about the resource.
|
2023-11-17 16:51:25 +00:00
|
|
|
// "deletionTimestamp" and "finalizers" keys are reserved for internal use.
|
2023-03-09 19:40:23 +00:00
|
|
|
map<string, string> metadata = 5;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Status is used by controllers to communicate the result of attempting to
|
|
|
|
// reconcile and apply the resource (e.g. surface semantic validation errors)
|
|
|
|
// with users and other controllers. Each status is identified by a unique key
|
|
|
|
// and should only ever be updated by one controller.
|
|
|
|
//
|
|
|
|
// Status can only be updated via the WriteStatus endpoint. Attempting to do
|
|
|
|
// so via the Write endpoint will result in an InvalidArgument error code.
|
2023-04-11 18:23:14 +00:00
|
|
|
map<string, Status> status = 6;
|
2023-03-09 19:40:23 +00:00
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Data contains the resource's type-specific content.
|
2023-03-09 19:40:23 +00:00
|
|
|
google.protobuf.Any data = 7;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Status is used by controllers to communicate the result of attempting to
|
|
|
|
// reconcile and apply a resource (e.g. surface semantic validation errors)
|
|
|
|
// with users and other controllers.
|
2023-04-11 18:23:14 +00:00
|
|
|
message Status {
|
2023-04-26 15:26:54 +00:00
|
|
|
// ObservedGeneration identifies which generation of a resource this status
|
|
|
|
// related to. It can be used to determine whether the current generation of
|
|
|
|
// a resource has been reconciled.
|
2023-04-11 18:23:14 +00:00
|
|
|
string observed_generation = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Conditions contains a set of discreet observations about the resource in
|
|
|
|
// relation to the current state of the system (e.g. it is semantically valid).
|
2023-04-11 18:23:14 +00:00
|
|
|
repeated Condition conditions = 2;
|
2023-05-09 18:57:40 +00:00
|
|
|
|
|
|
|
// UpdatedAt is the time at which the status was last written.
|
|
|
|
google.protobuf.Timestamp updated_at = 3;
|
2023-04-11 18:23:14 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Condition represents a discreet observation about a resource in relation to
|
|
|
|
// the current state of the system.
|
|
|
|
//
|
|
|
|
// It is heavily inspired by Kubernetes' [conditions](https://bit.ly/3H9Y6IK)
|
|
|
|
// and the Gateway API [types and reasons](https://bit.ly/3n2PPiP).
|
2023-04-11 18:23:14 +00:00
|
|
|
message Condition {
|
2023-04-26 15:26:54 +00:00
|
|
|
// State represents the state of the condition (i.e. true/false/unknown).
|
2023-04-11 18:23:14 +00:00
|
|
|
enum State {
|
2023-04-26 15:26:54 +00:00
|
|
|
// STATE_UNKNOWN means that the state of the condition is unknown.
|
|
|
|
//
|
2023-04-11 18:23:14 +00:00
|
|
|
// buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX
|
|
|
|
STATE_UNKNOWN = 0;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// STATE_TRUE means that the state of the condition is true.
|
2023-04-11 18:23:14 +00:00
|
|
|
STATE_TRUE = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// STATE_FALSE means that the state of the condition is false.
|
2023-04-11 18:23:14 +00:00
|
|
|
STATE_FALSE = 2;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Type identifies the type of condition (e.g. "Invalid", "ResolvedRefs").
|
2023-04-11 18:23:14 +00:00
|
|
|
string type = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// State represents the state of the condition (i.e. true/false/unknown).
|
2023-04-11 18:23:14 +00:00
|
|
|
State state = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Reason provides more machine-readable details about the condition (e.g.
|
|
|
|
// "InvalidProtocol").
|
2023-04-11 18:23:14 +00:00
|
|
|
string reason = 3;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Message contains a human-friendly description of the status.
|
2023-04-11 18:23:14 +00:00
|
|
|
string message = 4;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Resource identifies which resource this condition relates to, when it is
|
|
|
|
// not the core resource itself.
|
2023-04-11 18:23:14 +00:00
|
|
|
Reference resource = 5;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Reference identifies which resource a condition relates to, when it is not
|
|
|
|
// the core resource itself.
|
2023-04-11 18:23:14 +00:00
|
|
|
message Reference {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Type identifies the resource's type.
|
2023-04-11 18:23:14 +00:00
|
|
|
Type type = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Tenancy identifies the tenancy units (i.e. partition, namespace) in which
|
|
|
|
// the resource resides.
|
2023-04-11 18:23:14 +00:00
|
|
|
Tenancy tenancy = 2;
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Name is the user-given name of the resource (e.g. the "billing" service).
|
|
|
|
string name = 3;
|
2023-03-09 19:40:23 +00:00
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Section identifies which part of the resource the condition relates to.
|
|
|
|
string section = 4;
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-28 15:49:08 +00:00
|
|
|
// Tombstone represents a promise to delete all of a resource's immediately
|
|
|
|
// owned (child) resources, if any.
|
|
|
|
message Tombstone {
|
|
|
|
// Owner resource identifier.
|
|
|
|
ID owner = 1;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// ResourceService provides the shared primitives for storing, querying, and
|
|
|
|
// watching resources of different types.
|
|
|
|
//
|
|
|
|
// It is exposed on our external gRPC port and used internally by controllers.
|
|
|
|
//
|
|
|
|
// # Consistency Guarentees
|
|
|
|
//
|
|
|
|
// All reads are eventually consistent by default. Concretely, we guarantee
|
|
|
|
// [monotonic reads](https://jepsen.io/consistency/models/monotonic-reads).
|
|
|
|
//
|
|
|
|
// That is, a read will always return results that are as up-to-date as an
|
|
|
|
// earlier read, provided both happen on the same Consul server. But we do
|
|
|
|
// not make any such guarantee about writes. In other words, reads won't
|
|
|
|
// necessarily reflect earlier writes, even when made against the same server.
|
|
|
|
//
|
|
|
|
// This guarantee also holds between the Read and WatchList endpoints such that
|
|
|
|
// you'll never receive an event about a resource that you cannot immediately
|
|
|
|
// read, provided both the Read and WatchList happen on the same server.
|
|
|
|
//
|
|
|
|
// The Read endpoint also supports a strong consistency mode that guarantees
|
|
|
|
// [linearizability](https://jepsen.io/consistency/models/linearizable), such
|
|
|
|
// that a read will always return the most up-to-date version of a resource,
|
|
|
|
// without caveat.
|
|
|
|
//
|
|
|
|
// This is much more expensive than eventual consistency and when using the Raft
|
|
|
|
// storage backend, will increase load on the cluster leader, so should be used
|
|
|
|
// sparingly.
|
|
|
|
//
|
|
|
|
// To opt-in to strongly consistent reads set the `x-consul-consistency-mode`
|
|
|
|
// gRPC metadata field to "consistent".
|
2023-03-09 19:40:23 +00:00
|
|
|
service ResourceService {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Read a resource by ID.
|
|
|
|
//
|
|
|
|
// By default, reads are eventually consistent, but you can opt-in to strong
|
|
|
|
// consistency via the x-consul-consistency-mode metadata (see ResourceService
|
|
|
|
// docs for more info).
|
2023-05-09 18:57:40 +00:00
|
|
|
//
|
|
|
|
// Errors with NotFound if the resource is not found.
|
|
|
|
//
|
|
|
|
// Errors with InvalidArgument if the request fails validation or the resource
|
|
|
|
// is stored as a type with a different GroupVersion than was requested.
|
|
|
|
//
|
|
|
|
// Errors with PermissionDenied if the caller is not authorized to read
|
|
|
|
// the resource.
|
2023-03-09 19:40:23 +00:00
|
|
|
rpc Read(ReadRequest) returns (ReadResponse) {
|
2023-03-20 15:24:29 +00:00
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_READ,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Write a resource.
|
|
|
|
//
|
|
|
|
// To perform a CAS (Compare-And-Swap) write, provide the current resource
|
|
|
|
// version in the Resource.Version field. If the given version doesn't match
|
|
|
|
// what is currently stored, an Aborted error code will be returned.
|
|
|
|
//
|
2023-04-28 15:49:08 +00:00
|
|
|
// To perform a blanket write (update regardless of the stored version),
|
|
|
|
// provide an empty Version in the Resource.Version field. Note that the
|
|
|
|
// write may still fail due to not being able to internally do a CAS write
|
|
|
|
// and return an Aborted error code.
|
|
|
|
//
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resource.Id.Uid can (and by controllers, should) be provided to avoid
|
|
|
|
// accidentally modifying a resource if it has been deleted and recreated.
|
|
|
|
// If the given Uid doesn't match what is stored, a FailedPrecondition error
|
|
|
|
// code will be returned.
|
|
|
|
//
|
|
|
|
// It is not possible to modify the resource's status using Write. You must
|
|
|
|
// use WriteStatus instead.
|
2023-03-09 19:40:23 +00:00
|
|
|
rpc Write(WriteRequest) returns (WriteResponse) {
|
2023-03-20 15:24:29 +00:00
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_WRITE,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WriteStatus updates one of the resource's statuses. It should only be used
|
|
|
|
// by controllers.
|
|
|
|
//
|
|
|
|
// To perform a CAS (Compare-And-Swap) write, provide the current resource
|
|
|
|
// version in the Version field. If the given version doesn't match what is
|
|
|
|
// currently stored, an Aborted error code will be returned.
|
|
|
|
//
|
|
|
|
// Note: in most cases, CAS status updates are not necessary because updates
|
|
|
|
// are scoped to a specific status key and controllers are leader-elected so
|
|
|
|
// there is no chance of a conflict.
|
|
|
|
//
|
|
|
|
// Id.Uid must be provided to avoid accidentally modifying a resource if it has
|
|
|
|
// been deleted and recreated. If the given Uid doesn't match what is stored,
|
|
|
|
// a FailedPrecondition error code will be returned.
|
2023-03-09 19:40:23 +00:00
|
|
|
rpc WriteStatus(WriteStatusRequest) returns (WriteStatusResponse) {
|
2023-03-20 15:24:29 +00:00
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_WRITE,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// List resources of a given type, tenancy, and optionally name prefix.
|
|
|
|
//
|
|
|
|
// To list resources across all tenancy units, provide the wildcard "*" value.
|
|
|
|
//
|
|
|
|
// Results are eventually consistent (see ResourceService docs for more info).
|
2023-03-09 19:40:23 +00:00
|
|
|
rpc List(ListRequest) returns (ListResponse) {
|
2023-03-20 15:24:29 +00:00
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_READ,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-05-08 17:26:19 +00:00
|
|
|
// List resources of a given owner.
|
|
|
|
//
|
|
|
|
// Results are eventually consistent (see ResourceService docs for more info).
|
|
|
|
rpc ListByOwner(ListByOwnerRequest) returns (ListByOwnerResponse) {
|
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_READ,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// Delete a resource by ID.
|
|
|
|
//
|
|
|
|
// Deleting a non-existent resource will return a successful response for
|
|
|
|
// idempotency.
|
|
|
|
//
|
|
|
|
// To perform a CAS (Compare-And-Swap) deletion, provide the current resource
|
|
|
|
// version in the Version field. If the given version doesn't match what is
|
|
|
|
// currently stored, an Aborted error code will be returned.
|
|
|
|
//
|
|
|
|
// Resource.Id.Uid can (and by controllers, should) be provided to avoid
|
|
|
|
// accidentally modifying a resource if it has been deleted and recreated.
|
|
|
|
// If the given Uid doesn't match what is stored, a FailedPrecondition error
|
|
|
|
// code will be returned.
|
2023-03-09 19:40:23 +00:00
|
|
|
rpc Delete(DeleteRequest) returns (DeleteResponse) {
|
2023-03-20 15:24:29 +00:00
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_WRITE,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WatchList watches resources of the given type, tenancy, and optionally name
|
|
|
|
// prefix. It returns results for the current state-of-the-world at the start
|
|
|
|
// of the stream, and delta events whenever resources are written or deleted.
|
|
|
|
//
|
|
|
|
// To watch resources across all tenancy units, provide the wildcard "*" value.
|
|
|
|
//
|
|
|
|
// WatchList makes no guarantees about event timeliness (e.g. an event for a
|
|
|
|
// write may not be received immediately), but it does guarantee that events
|
|
|
|
// will be emitted in the correct order. See ResourceService docs for more
|
|
|
|
// info about consistency guarentees.
|
|
|
|
//
|
2023-03-27 19:37:54 +00:00
|
|
|
// buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
|
|
|
|
rpc WatchList(WatchListRequest) returns (stream WatchEvent) {
|
2023-03-20 15:24:29 +00:00
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_READ,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
2024-01-25 19:12:30 +00:00
|
|
|
|
|
|
|
// MutateAndValidate a resource.
|
|
|
|
//
|
|
|
|
// Applies a resource type's registered mutation and validation hooks to
|
|
|
|
// a resource. This is useful for filling in defaults and validating inputs before
|
|
|
|
// doing a Write. It's not a pre-requisite since the Write endpoint will also apply
|
|
|
|
// the hooks.
|
|
|
|
rpc MutateAndValidate(MutateAndValidateRequest) returns (MutateAndValidateResponse) {
|
|
|
|
option (hashicorp.consul.internal.ratelimit.spec) = {
|
|
|
|
operation_type: OPERATION_TYPE_READ,
|
|
|
|
operation_category: OPERATION_CATEGORY_RESOURCE
|
|
|
|
};
|
|
|
|
}
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// ReadRequest contains the parameters to the Read endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message ReadRequest {
|
2023-04-26 15:26:54 +00:00
|
|
|
// ID of the resource.
|
2023-03-09 19:40:23 +00:00
|
|
|
ID id = 1;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// ReadResponse contains the results of calling the Read endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message ReadResponse {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resource that was read.
|
2023-03-09 19:40:23 +00:00
|
|
|
Resource resource = 1;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// ListRequest contains the parameters to the List endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message ListRequest {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Type of resource to list.
|
2023-03-09 19:40:23 +00:00
|
|
|
Type type = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Tenancy units in which to list resources. To list resources in all units,
|
|
|
|
// provide the wildcard "*" value.
|
2023-03-09 19:40:23 +00:00
|
|
|
Tenancy tenancy = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// NamePrefix filters the results to those with a name beginning with the
|
|
|
|
// given prefix.
|
2023-03-09 19:40:23 +00:00
|
|
|
string name_prefix = 3;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// ListResponse contains the results of calling the List endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message ListResponse {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resources that were listed.
|
2023-03-09 19:40:23 +00:00
|
|
|
repeated Resource resources = 1;
|
|
|
|
}
|
|
|
|
|
2023-05-08 17:26:19 +00:00
|
|
|
// ListByOwnerRequest contains the parameters to the ListByOwner endpoint.
|
|
|
|
message ListByOwnerRequest {
|
|
|
|
ID owner = 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
// ListByOwnerResponse contains the results of calling the ListByOwner endpoint.
|
|
|
|
message ListByOwnerResponse {
|
|
|
|
// Resources that were listed.
|
|
|
|
repeated Resource resources = 1;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WriteRequest contains the parameters to the Write endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message WriteRequest {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resource to write.
|
2023-03-09 19:40:23 +00:00
|
|
|
Resource resource = 1;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WriteResponse contains the results of calling the Write endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message WriteResponse {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resource that was written.
|
2023-03-09 19:40:23 +00:00
|
|
|
Resource resource = 1;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WriteStatusRequest contains the parameters to the WriteStatus endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message WriteStatusRequest {
|
2023-04-26 15:26:54 +00:00
|
|
|
// ID of the resource to which the status will be written. Must contain a Uid.
|
2023-03-09 19:40:23 +00:00
|
|
|
ID id = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Version may be provided to perform a CAS (Compare-And-Swap) update of the
|
|
|
|
// status. If the given version doesn't match what is currently stored, an
|
|
|
|
// Aborted error code will be returned.
|
|
|
|
//
|
|
|
|
// Note: in most cases, CAS status updates are not necessary because updates
|
|
|
|
// are scoped to a specific status key and controllers are leader-elected so
|
|
|
|
// there is no chance of a conflict.
|
2023-03-09 19:40:23 +00:00
|
|
|
string version = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Key identifies which status will be written. Generally, each controller
|
|
|
|
// should write 1 status which it owns exclusively (i.e. no other controller
|
|
|
|
// updates it).
|
2023-03-09 19:40:23 +00:00
|
|
|
string key = 3;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Status that will be written to the resource.
|
2023-04-11 18:23:14 +00:00
|
|
|
Status status = 4;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WriteStatusResponse contains the results of calling the WriteStatus endpoint.
|
2023-04-11 18:23:14 +00:00
|
|
|
message WriteStatusResponse {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Resource to which the status was written.
|
2023-04-11 18:23:14 +00:00
|
|
|
Resource resource = 1;
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// DeleteRequest contains the parameters to the Delete endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message DeleteRequest {
|
2023-04-26 15:26:54 +00:00
|
|
|
// ID of the resource that will be deleted.
|
2023-03-09 19:40:23 +00:00
|
|
|
ID id = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Version may be provided to perform a CAS (Compare-And-Swap) deletion of the
|
|
|
|
// resource. If the given version doesn't match what is currently stored, an
|
|
|
|
// Aborted error code will be returned.
|
2023-03-09 19:40:23 +00:00
|
|
|
string version = 2;
|
|
|
|
}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// DeleteResponse contains the results of calling the Delete endpoint.
|
2023-03-09 19:40:23 +00:00
|
|
|
message DeleteResponse {}
|
|
|
|
|
2023-04-26 15:26:54 +00:00
|
|
|
// WatchListRequest contains the parameters to the WatchList endpoint.
|
2023-03-27 19:37:54 +00:00
|
|
|
message WatchListRequest {
|
2023-04-26 15:26:54 +00:00
|
|
|
// Type of resource to watch.
|
2023-03-27 19:37:54 +00:00
|
|
|
Type type = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// Tenancy units in which to watch resources. To list resources in all units,
|
|
|
|
// provide the wildcard "*" value.
|
2023-03-27 19:37:54 +00:00
|
|
|
Tenancy tenancy = 2;
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// NamePrefix filters the results to those with a name beginning with the
|
|
|
|
// given prefix.
|
2023-03-27 19:37:54 +00:00
|
|
|
string name_prefix = 3;
|
2023-03-09 19:40:23 +00:00
|
|
|
}
|
2023-04-26 15:26:54 +00:00
|
|
|
|
|
|
|
// WatchEvent is emitted on the WatchList stream when a resource changes.
|
|
|
|
message WatchEvent {
|
2024-02-02 21:11:05 +00:00
|
|
|
// Upsert indicates that the resource was written (i.e. created or
|
|
|
|
// updated). All events from the initial state-of-the-world will be upsert
|
|
|
|
// events.
|
|
|
|
message Upsert {
|
|
|
|
Resource resource = 1;
|
2023-04-26 15:26:54 +00:00
|
|
|
}
|
|
|
|
|
2024-02-02 21:11:05 +00:00
|
|
|
// Delete indicates that the resource was deleted.
|
|
|
|
message Delete {
|
|
|
|
Resource resource = 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
// EndOfSnapshot is sent to indicate that the initial snapshot events have
|
|
|
|
// been sent and future events will modify that set.
|
|
|
|
message EndOfSnapshot {}
|
2023-04-26 15:26:54 +00:00
|
|
|
|
2024-02-02 21:11:05 +00:00
|
|
|
oneof event {
|
|
|
|
Upsert upsert = 1;
|
|
|
|
Delete delete = 2;
|
|
|
|
EndOfSnapshot end_of_snapshot = 3;
|
|
|
|
}
|
2023-04-26 15:26:54 +00:00
|
|
|
}
|
2024-01-25 19:12:30 +00:00
|
|
|
|
|
|
|
// MutateAndValidateRequest contains the parameters to the MutateAndValidate endpoint.
|
|
|
|
message MutateAndValidateRequest {
|
|
|
|
Resource resource = 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
// MutateAndValidateResponse contains the results of calling the MutateAndValidate endpoint.
|
|
|
|
message MutateAndValidateResponse {
|
|
|
|
Resource resource = 1;
|
|
|
|
}
|