consul/proto/private/pbpeering/peering.proto

// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: MPL-2.0

syntax = "proto3";

package hashicorp.consul.internal.peering;

import "annotations/ratelimit/ratelimit.proto";
import "google/protobuf/timestamp.proto";
import "private/pbcommon/common.proto";

// PeeringService handles operations for establishing peering relationships
// between disparate Consul clusters.
service PeeringService {
  rpc GenerateToken(GenerateTokenRequest) returns (GenerateTokenResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_WRITE,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  rpc Establish(EstablishRequest) returns (EstablishResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_WRITE,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  rpc PeeringRead(PeeringReadRequest) returns (PeeringReadResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_READ,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  rpc PeeringList(PeeringListRequest) returns (PeeringListResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_READ,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  rpc PeeringDelete(PeeringDeleteRequest) returns (PeeringDeleteResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_WRITE,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  // 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) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_WRITE,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  // TODO(peering): Rename this to PeeredServiceRoots? or something like that?
  rpc TrustBundleListByService(TrustBundleListByServiceRequest) returns (TrustBundleListByServiceResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_READ,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }

  rpc TrustBundleRead(TrustBundleReadRequest) returns (TrustBundleReadResponse) {
    option (hashicorp.consul.internal.ratelimit.spec) = {
      operation_type: OPERATION_TYPE_READ,
      operation_category: OPERATION_CATEGORY_PEERING
    };
  }
}

// PeeringState enumerates all the states a peering can be in.
enum PeeringState {
  // Undefined represents an unset value for PeeringState during
  // writes.
  UNDEFINED = 0;

  // Pending means the peering was created by generating a peering token.
  // Peerings stay in a pending state until the peer uses the token to dial
  // the local cluster.
  PENDING = 1;

  // Establishing means the peering is being established from a peering token.
  // This is the initial state for dialing peers.
  ESTABLISHING = 2;

  // Active means that the peering connection is active and healthy.
  ACTIVE = 3;

  // Failing means the peering connection has been interrupted but has not yet
  // been terminated.
  FAILING = 4;

  // Deleting means a peering was marked for deletion and is in the process
  // of being deleted.
  DELETING = 5;

  // Terminated means the peering relationship has been removed.
  TERMINATED = 6;
}

// SecretsWriteRequest encodes a request to write a peering secret as the result
// of some operation. Different operations, such as generating a peering token,
// lead to modifying the known secrets associated with a peering.
message SecretsWriteRequest {
  // PeerID is the local UUID of the peering this request applies to.
  string PeerID = 1;

  oneof Request {
    GenerateTokenRequest generate_token = 2;
    ExchangeSecretRequest exchange_secret = 3;
    PromotePendingRequest promote_pending = 4;
    EstablishRequest establish = 5;
  }

  // GenerateTokenRequest encodes a request to persist a peering establishment
  // secret. It is triggered by generating a new peering token for a peer cluster.
  message GenerateTokenRequest {
    // establishment_secret is the proposed secret ID to store as the establishment
    // secret for this peering.
    string establishment_secret = 1;
  }

  // ExchangeSecretRequest encodes a request to persist a pending stream secret
  // secret. It is triggered by an acceptor peer generating a long-lived stream secret
  // in exchange for an establishment secret.
  message ExchangeSecretRequest {
    // establishment_secret is the secret to exchange for the given pending stream secret.
    string establishment_secret = 1;

    // pending_stream_secret is the proposed secret ID to store as the pending stream
    // secret for this peering.
    string pending_stream_secret = 2;
  }

  // PromotePendingRequest encodes a request to promote a pending stream secret
  // to be an active stream secret. It is triggered when the accepting stream handler
  // validates an Open request from a peer with a pending stream secret.
  message PromotePendingRequest {
    // active_stream_secret is the proposed secret ID to store as the active stream
    // secret for this peering.
    string active_stream_secret = 1;
  }

  // EstablishRequest encodes a request to persist an active stream secret.
  // It is triggered after a dialing peer exchanges their establishment secret
  // for a long-lived active stream secret.
  message EstablishRequest {
    // active_stream_secret is the proposed secret ID to store as the active stream
    // secret for this peering.
    string active_stream_secret = 1;
  }
}

// PeeringSecrets defines a secret used for authenticating/authorizing peer clusters.
message PeeringSecrets {
  // PeerID is the local UUID of the peering this secret was generated for.
  string PeerID = 1;

  message Establishment {
    // SecretID is the one-time-use peering establishment secret.
    string SecretID = 1;
  }

  message Stream {
    // ActiveSecretID is the active UUID-v4 secret being used for authorization at
    // the peering stream.
    string ActiveSecretID = 1;

    // PendingSecretID is a UUID-v4 secret introduced during secret rotation.
    // When a peering is established or re-established, both the active secret and
    // pending secret are considered valid. However, once the dialing peer uses
    // the pending secret then it transitions to active and the previously active
    // secret is discarded.
    //
    // Pending secret IDs are only valid for long-lived stream secrets.
    // Only one establishment secret can exist for a peer at a time since they
    // are designed for one-time use.
    string PendingSecretID = 2;
  }

  Establishment establishment = 2;

  Stream stream = 3;
}

// 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;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 5;

  // 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;

  // StreamStatus contains information computed on read based on the state of the stream.
  //
  // mog: func-to=StreamStatusToAPI func-from=StreamStatusFromAPI
  StreamStatus StreamStatus = 13;

  // CreateIndex is the Raft index at which the Peering was created.
  // @gotags: bexpr:"-"
  uint64 CreateIndex = 11;

  // ModifyIndex is the latest Raft index at which the Peering. was modified.
  // @gotags: bexpr:"-"
  uint64 ModifyIndex = 12;

  // Remote contains metadata about the remote peer.
  RemoteInfo Remote = 17;

  // ManualServerAddresses provides a list of manually specified server addresses from the
  // user. If this is defined, then the automatic PeerServerAddresses are ignored.
  repeated string ManualServerAddresses = 18;
}

// RemoteInfo contains metadata about the remote peer.

// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringRemoteInfo
// output=peering.gen.go
// name=API
message RemoteInfo {
  // Partition is the remote peer's partition.
  string Partition = 1;
  // Datacenter is the remote peer's datacenter.
  string Datacenter = 2;

  // Locality identifies where the peer is running.
  // mog: func-to=LocalityToAPI func-from=LocalityFromAPI
  common.Locality Locality = 3;
}

// StreamStatus represents information about an active peering stream.
message StreamStatus {
  // ImportedServices is the list of services imported from this peering.
  repeated string ImportedServices = 1;

  // ExportedServices is the list of services exported to this peering.
  repeated string ExportedServices = 2;

  // LastHeartbeat represents when the last heartbeat message was received.
  google.protobuf.Timestamp LastHeartbeat = 3;

  // LastReceive represents when any message was last received, regardless of success or error.
  google.protobuf.Timestamp LastReceive = 4;

  // LastSend represents when any message was last sent, regardless of success or error.
  google.protobuf.Timestamp LastSend = 5;
}

// 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.
  // @gotags: bexpr:"-"
  uint64 CreateIndex = 6;

  // ModifyIndex is the latest Raft index at which the trust bundle was modified.
  // @gotags: bexpr:"-"
  uint64 ModifyIndex = 7;
}

// PeeringServerAddresses contains the latest snapshot of all known
// server addresses for a peer.
message PeeringServerAddresses {
  repeated string Addresses = 1;
}

// @consul-rpc-glue: LeaderReadTODO
message PeeringReadRequest {
  string Name = 1;
  string Partition = 2;
}

message PeeringReadResponse {
  Peering Peering = 1;
}

// @consul-rpc-glue: LeaderReadTODO
message PeeringListRequest {
  string Partition = 1;
}

message PeeringListResponse {
  repeated Peering Peerings = 1;
  uint64 Index = 2;
}

message PeeringWriteRequest {
  // Peering is the peering to write with the request.
  Peering Peering = 1;

  // SecretsWriteRequest contains the optional peering secrets to persist
  // with the peering. Peering secrets are not embedded in the peering
  // object to avoid leaking them.
  SecretsWriteRequest SecretsRequest = 2;

  map<string, string> Meta = 3;
}

// TODO(peering): Consider returning Peering if we keep this endpoint around
message PeeringWriteResponse {}

message PeeringDeleteRequest {
  string Name = 1;

  string Partition = 2;
}

message PeeringDeleteResponse {}

message TrustBundleListByServiceRequest {
  string ServiceName = 1;
  string Namespace = 2;
  string Partition = 3;
  string Kind = 4;
}

message TrustBundleListByServiceResponse {
  uint64 Index = 1;
  repeated PeeringTrustBundle Bundles = 2;
}

message TrustBundleReadRequest {
  string Name = 1;
  string Partition = 2;
}

message TrustBundleReadResponse {
  uint64 Index = 1;
  PeeringTrustBundle Bundle = 2;
}

// This is a purely internal type and does not require query metadata.
message PeeringTerminateByIDRequest {
  string ID = 1;
}

message PeeringTerminateByIDResponse {}

message PeeringTrustBundleWriteRequest {
  PeeringTrustBundle PeeringTrustBundle = 1;
}

message PeeringTrustBundleWriteResponse {}

message PeeringTrustBundleDeleteRequest {
  string Name = 1;

  string Partition = 2;
}

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;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 5;

  // ServerExternalAddresses is a list of addresses to put into the generated token. This could be used to specify
  // load balancer(s) or external IPs to reach the servers from the dialing side, and will override any server
  // addresses obtained from the "consul" service.
  repeated string ServerExternalAddresses = 6;
}

// 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;
}

// 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;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 4;
}

// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringEstablishResponse
// output=peering.gen.go
// name=API
message EstablishResponse {}