open-consul/proto/pbpeering/peering.proto

392 lines
12 KiB
Protocol Buffer
Raw Normal View History

syntax = "proto3";
package peering;
import "google/protobuf/timestamp.proto";
import "google/protobuf/any.proto";
// TODO(peering): Handle this some other way
import "proto/pbstatus/status.proto";
// PeeringService handles operations for establishing peering relationships
// between disparate Consul clusters.
service PeeringService {
rpc GenerateToken(GenerateTokenRequest) returns (GenerateTokenResponse);
rpc Establish(EstablishRequest) returns (EstablishResponse);
rpc PeeringRead(PeeringReadRequest) returns (PeeringReadResponse);
rpc PeeringList(PeeringListRequest) returns (PeeringListResponse);
rpc PeeringDelete(PeeringDeleteRequest) returns (PeeringDeleteResponse);
// TODO(peering): As of writing, this method is only used in tests to set up Peerings in the state store.
// Consider removing if we can find another way to populate state store in peering_endpoint_test.go
rpc PeeringWrite(PeeringWriteRequest) returns (PeeringWriteResponse);
// TODO(peering): Rename this to PeeredServiceRoots? or something like that?
rpc TrustBundleListByService(TrustBundleListByServiceRequest) returns (TrustBundleListByServiceResponse);
rpc TrustBundleRead(TrustBundleReadRequest) returns (TrustBundleReadResponse);
// StreamResources opens an event stream for resources to share between peers, such as services.
// Events are streamed as they happen.
// buf:lint:ignore RPC_REQUEST_STANDARD_NAME
// buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
// buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE
rpc StreamResources(stream ReplicationMessage) returns (stream ReplicationMessage);
}
// PeeringState enumerates all the states a peering can be in
enum PeeringState {
// Undefined represents an unset value for PeeringState during
// writes.
UNDEFINED = 0;
// Initial means a Peering has been initialized and is awaiting
// acknowledgement from a remote peer.
INITIAL = 1;
// Active means that the peering connection is active and healthy.
ACTIVE = 2;
// Failing means the peering connection has been interrupted but has not yet
// been terminated.
FAILING = 3;
// Terminated means the peering relationship has been removed.
TERMINATED = 4;
}
// Peering defines a peering relationship between two disparate Consul clusters
//
// mog annotation:
//
// target=github.com/hashicorp/consul/api.Peering
// output=peering.gen.go
// name=API
message Peering {
// ID is a datacenter-scoped UUID for the peering.
// The ID is generated when a peering is first written to the state store.
string ID = 1;
// Name is the local alias for the peering relationship.
string Name = 2;
// Partition is the local partition connecting to the peer.
string Partition = 3;
// DeletedAt is the time when the Peering was marked for deletion
// This is nullable so that we can omit if empty when encoding in JSON
// mog: func-to=TimePtrFromProto func-from=TimePtrToProto
google.protobuf.Timestamp DeletedAt = 4;
2022-05-09 20:47:37 +00:00
// Meta is a mapping of some string value to any other string value
map<string, string> Meta = 5;
2022-05-09 20:47:37 +00:00
// State is one of the valid PeeringState values to represent the status of
// peering relationship.
//
// mog: func-to=PeeringStateToAPI func-from=PeeringStateFromAPI
PeeringState State = 6;
// PeerID is the ID that our peer assigned to this peering.
// This ID is to be used when dialing the peer, so that it can know who dialed it.
string PeerID = 7;
// PeerCAPems contains all the CA certificates for the remote peer.
repeated string PeerCAPems = 8;
// PeerServerName is the name of the remote server as it relates to TLS.
string PeerServerName = 9;
// PeerServerAddresses contains all the the connection addresses for the remote peer.
repeated string PeerServerAddresses = 10;
// ImportedServiceCount is the count of how many services are imported from this peering.
uint64 ImportedServiceCount = 13;
// ExportedServiceCount is the count of how many services are exported to this peering.
uint64 ExportedServiceCount = 14;
// CreateIndex is the Raft index at which the Peering was created.
uint64 CreateIndex = 11;
// ModifyIndex is the latest Raft index at which the Peering. was modified.
uint64 ModifyIndex = 12;
}
// PeeringTrustBundle holds the trust information for validating requests from a peer.
message PeeringTrustBundle {
// TrustDomain is the domain for the bundle, example.com, foo.bar.gov for example. Note that this must not have a prefix such as "spiffe://".
string TrustDomain = 1;
// PeerName associates the trust bundle with a peer.
string PeerName = 2;
// Partition isolates the bundle from other trust bundles in separate local partitions.
string Partition = 3;
// RootPEMs holds ASN.1 DER encoded X.509 certificate data for the trust bundle.
repeated string RootPEMs = 4;
// ExportedPartition references the remote partition of the peer
// which sent this trust bundle. Used for generating SpiffeIDs.
string ExportedPartition = 5;
// CreateIndex is the Raft index at which the trust domain was created.
uint64 CreateIndex = 6;
// ModifyIndex is the latest Raft index at which the trust bundle was modified.
uint64 ModifyIndex = 7;
}
// @consul-rpc-glue: Datacenter,ReadTODO
message PeeringReadRequest {
string Name = 1;
string Partition = 2;
string Datacenter = 3;
//TODO(peering) query metadata
}
message PeeringReadResponse {
Peering Peering = 1;
//TODO(peering) query metadata
}
// @consul-rpc-glue: Datacenter,ReadTODO
message PeeringListRequest {
string Partition = 1;
string Datacenter = 2;
//TODO(peering) query metadata
}
message PeeringListResponse {
repeated Peering Peerings = 1;
//TODO(peering) query metadata
}
// @consul-rpc-glue: Datacenter,WriteTODO
message PeeringWriteRequest {
Peering Peering = 1;
//TODO(peering): what to do with embedded write request?
string Datacenter = 2;
2022-05-09 20:47:37 +00:00
// Meta is a mapping of some string value to any other string value
map<string, string> Meta = 3;
}
// TODO(peering): Consider returning Peering if we keep this endpoint around
message PeeringWriteResponse {}
// @consul-rpc-glue: Datacenter,WriteTODO
message PeeringDeleteRequest {
string Name = 1;
string Partition = 2;
//TODO(peering): what to do with embedded write request?
string Datacenter = 3;
}
message PeeringDeleteResponse {}
// @consul-rpc-glue: Datacenter,ReadTODO
message TrustBundleListByServiceRequest {
string ServiceName = 1;
string Namespace = 2;
string Partition = 3;
string Kind = 4;
// these are common fields required for implementing structs.RPCInfo methods
// that are used to forward requests
string Datacenter = 5;
}
message TrustBundleListByServiceResponse {
uint64 Index = 1;
repeated PeeringTrustBundle Bundles = 2;
}
// @consul-rpc-glue: Datacenter,ReadTODO
message TrustBundleReadRequest {
string Name = 1;
string Partition = 2;
// these are common fields required for implementing structs.RPCInfo methods
// that are used to forward requests
string Datacenter = 3;
}
message TrustBundleReadResponse {
uint64 Index = 1;
PeeringTrustBundle Bundle = 2;
}
message PeeringTerminateByIDRequest {
string ID = 1;
}
message PeeringTerminateByIDResponse {}
// @consul-rpc-glue: Datacenter
message PeeringTrustBundleWriteRequest {
PeeringTrustBundle PeeringTrustBundle = 1;
//TODO(peering): what to do with embedded write request?
string Datacenter = 2;
}
message PeeringTrustBundleWriteResponse {}
// @consul-rpc-glue: Datacenter
message PeeringTrustBundleDeleteRequest {
string Name = 1;
string Partition = 2;
//TODO(peering): what to do with embedded write request?
string Datacenter = 3;
}
message PeeringTrustBundleDeleteResponse {}
// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringGenerateTokenRequest
// output=peering.gen.go
// name=API
message GenerateTokenRequest {
// Name of the remote peer.
string PeerName = 1;
// Partition is the local partition being peered.
string Partition = 2;
// these are common fields required for implementing structs.RPCInfo methods
// that are used to forward requests
string Datacenter = 3;
string Token = 4;
2022-05-09 20:47:37 +00:00
// Meta is a mapping of some string value to any other string value
map<string, string> Meta = 5;
}
// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringGenerateTokenResponse
// output=peering.gen.go
// name=API
message GenerateTokenResponse {
// PeeringToken is an opaque string provided to the remote peer for it to complete
// the peering initialization handshake.
string PeeringToken = 1;
}
// @consul-rpc-glue: Datacenter
//
// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringEstablishRequest
// output=peering.gen.go
// name=API
message EstablishRequest {
// Name of the remote peer.
string PeerName = 1;
// The peering token returned from the peer's GenerateToken endpoint.
string PeeringToken = 2;
// Partition is the local partition being peered.
string Partition = 3;
// these are common fields required for implementing structs.RPCInfo methods
// that are used to forward requests
string Datacenter = 4;
string Token = 5;
2022-05-09 20:47:37 +00:00
// Meta is a mapping of some string value to any other string value
map<string, string> Meta = 6;
}
//
// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringEstablishResponse
// output=peering.gen.go
// name=API
message EstablishResponse {}
message ReplicationMessage {
oneof Payload {
Request request = 1;
Response response = 2;
Terminated terminated = 3;
}
// A Request requests to subscribe to a resource of a given type.
message Request {
// An identifier for the peer making the request.
// This identifier is provisioned by the serving peer prior to the request from the dialing peer.
string PeerID = 1;
// Nonce corresponding to that of the response being ACKed or NACKed.
// Initial subscription requests will have an empty nonce.
// The nonce is generated and incremented by the exporting peer.
string Nonce = 2;
// The type URL for the resource being requested or ACK/NACKed.
string ResourceURL = 3;
// The error if the previous response was not applied successfully.
// This field is empty in the first subscription request.
status.Status Error = 4;
}
// A Response contains resources corresponding to a subscription request.
message Response {
// Nonce identifying a response in a stream.
string Nonce = 1;
// The type URL of resource being returned.
string ResourceURL = 2;
// An identifier for the resource being returned.
// This could be the SPIFFE ID of the service.
string ResourceID = 3;
// The resource being returned.
google.protobuf.Any Resource = 4;
// Operation enumerates supported operations for replicated resources.
enum Operation {
Unknown = 0;
// UPSERT represents a create or update event.
UPSERT = 1;
// DELETE indicates the resource should be deleted.
// In DELETE operations no Resource will be returned.
// Deletion by an importing peer must be done with the type URL and ID.
DELETE = 2;
}
// REQUIRED. The operation to be performed in relation to the resource.
Operation operation = 5;
}
// Terminated is sent when a peering is deleted locally.
// This message signals to the peer that they should clean up their local state about the peering.
message Terminated {}
}
// LeaderAddress is sent when the peering service runs on a consul node
// that is not a leader. The node either lost leadership, or never was a leader.
message LeaderAddress {
// address is an ip:port best effort hint at what could be the cluster leader's address
string address = 1;
}